Package software.amazon.awssdk.enhanced.dynamodb.internal.extensions.utility

Class NestedRecordUtils

java.lang.Object
software.amazon.awssdk.enhanced.dynamodb.internal.extensions.utility.NestedRecordUtils
@SdkInternalApi public final class NestedRecordUtils extends Object

  • Method Details

    • getTableSchemaForListElement

      public static TableSchema<?> getTableSchemaForListElement(TableSchema<?> rootSchema, String key)
      Resolves and returns the TableSchema for the element type of list attribute from the provided root schema.

      This method is useful when dealing with lists of nested objects in a DynamoDB-enhanced table schema, particularly in scenarios where the list is part of a flattened nested structure.

      If the provided key contains the nested object delimiter (e.g., _NESTED_ATTR_UPDATE_), the method traverses the nested hierarchy based on that path to locate the correct schema for the target attribute. Otherwise, it directly resolves the list element type from the root schema using reflection.

      If the list element type is not annotated with @DynamoDbBean or @DynamoDbImmutable (e.g. when a custom converter handles serialization via @DynamoDbConvertedBy), this method returns null to indicate that no schema introspection is possible or necessary for that element type.

      Parameters:
      rootSchema - The root TableSchema representing the top-level entity.
      key - The key representing the list attribute, either flat or nested (using a delimiter).
      Returns:
      The TableSchema representing the list element type, or null if the element type is not a DynamoDB-annotated class.
      Throws:
      IllegalArgumentException - If no converter is found for the attribute or if the converter has no type parameters.

    • getTableSchemaForListElement

      public static TableSchema<?> getTableSchemaForListElement(TableSchema<?> rootSchema, String key, Map<NestedRecordUtils.SchemaLookupKey,Optional<TableSchema<?>>> nestedSchemaCache)
      Same as getTableSchemaForListElement(TableSchema, String) but allows callers to provide a shared per-operation cache for nested schema lookups.

    • resolveSchemasPerPath

      public static Map<String,TableSchema<?>> resolveSchemasPerPath(Map<String,AttributeValue> attributesToSet, TableSchema<?> rootSchema)
      Traverses the attribute keys representing flattened nested structures and resolves the corresponding TableSchema for each nested path.

      The method constructs a mapping between each unique nested path (represented as dot-delimited strings) and the corresponding TableSchema object derived from the root schema. It supports resolving schemas for arbitrarily deep nesting, using the _NESTED_ATTR_UPDATE_ pattern as a path delimiter.

      This is typically used in update or transformation flows where fields from nested objects are represented as flattened keys in the attribute map (e.g., parent_NESTED_ATTR_UPDATE_child).

      Parameters:
      attributesToSet - A map of flattened attribute keys to values, where keys may represent paths to nested attributes.
      rootSchema - The root TableSchema of the top-level entity.
      Returns:
      A map where the key is the nested path (e.g., "parent.child") and the value is the TableSchema corresponding to that level in the object hierarchy.

    • resolveSchemasPerPath

      public static Map<String,TableSchema<?>> resolveSchemasPerPath(Map<String,AttributeValue> attributesToSet, TableSchema<?> rootSchema, Map<NestedRecordUtils.SchemaLookupKey,Optional<TableSchema<?>>> nestedSchemaCache)
      Same as resolveSchemasPerPath(Map, TableSchema) but allows callers to provide a shared per-operation cache for nested schema lookups.

    • reconstructCompositeKey

      public static String reconstructCompositeKey(String path, String attributeName)
      Converts a dot-separated path to a composite key using nested object delimiters. Example: reconstructCompositeKey("parent.child", "attr") returns "parent_NESTED_ATTR_UPDATE_child_NESTED_ATTR_UPDATE_attr"
      Parameters:
      path - the dot-separated path; may be null or empty
      attributeName - the attribute name to append; must not be null
      Returns:
      the composite key with nested object delimiters

    • getNestedSchemaCached

      public static Optional<TableSchema<?>> getNestedSchemaCached(Map<NestedRecordUtils.SchemaLookupKey,Optional<TableSchema<?>>> cache, TableSchema<?> parentSchema, String attributeName)
      Cached wrapper around EnhancedClientUtils.getNestedSchema(software.amazon.awssdk.enhanced.dynamodb.TableSchema<?>, java.lang.String). Cache key is based on (parent schema identity, attribute name).

    • getListElementSchemaCached

      public static TableSchema<?> getListElementSchemaCached(Map<NestedRecordUtils.SchemaLookupKey,TableSchema<?>> cache, TableSchema<?> parentSchema, String attributeName, Map<NestedRecordUtils.SchemaLookupKey,Optional<TableSchema<?>>> nestedSchemaCache)
      Cached wrapper for resolving list element schema, storing results (including null) in the provided cache.

      getTableSchemaForListElement(TableSchema, String, Map) returns null when the list element type is not a DynamoDB-annotated class (e.g. when a custom converter handles serialization). Callers should check for null before attempting to introspect the returned schema.