Package software.amazon.awssdk.enhanced.dynamodb.document

Interface EnhancedDocument

All Known Implementing Classes:
DefaultEnhancedDocument
public interface EnhancedDocument
Interface representing the Document API for DynamoDB. The Document API operations are designed to work with open content, such as data with no fixed schema, data that cannot be modeled using rigid types, or data that has a schema. This interface provides all the methods required to access a Document, as well as constructor methods for creating a Document that can be used to read and write to DynamoDB using the EnhancedDynamoDB client. Additionally, this interface provides flexibility when working with data, as it allows you to work with data that is not necessarily tied to a specific data model. The EnhancedDocument interface provides two ways to use AttributeConverterProviders:

Enhanced Document with default attribute Converter to convert the attribute of DDB item to basic default primitive types in Java 

 EnhancedDocument enhancedDocument = EnhancedDocument.builder().attributeConverterProviders(AttributeConverterProvider
 .defaultProvider()).build();

Enhanced Document with Custom attribute Converter to convert the attribute of DDB Item to Custom Type. 

 // CustomAttributeConverterProvider.create() is an example for some Custom converter provider
 EnhancedDocument enhancedDocumentWithCustomConverter = EnhancedDocument.builder().attributeConverterProviders
 (CustomAttributeConverterProvider.create(), AttributeConverterProvide.defaultProvider()
 .put("customObject", customObject, EnhancedType.of(CustomClass.class))
 .build();

Enhanced Document can be created with Json as input using Static factory method.In this case it used defaultConverterProviders. 

 EnhancedDocument enhancedDocumentWithCustomConverter = EnhancedDocument.fromJson("{\"k\":\"v\"}");
The attribute converter are always required to be provided, thus for default conversion AttributeConverterProvider.defaultProvider() must be supplied.

  • Method Details

    • fromJson

      static EnhancedDocument fromJson(String json)
      Creates a new EnhancedDocument instance from a JSON string. The AttributeConverterProvider.defaultProvider() is used as the default ConverterProvider. To use a custom ConverterProvider, use the builder methods: EnhancedDocument.Builder.json(String) to supply the JSON string, then use EnhancedDocument.Builder.attributeConverterProviders(AttributeConverterProvider...) to provide the custom ConverterProvider. 
       EnhancedDocument documentFromJson = EnhancedDocument.fromJson("{\"key\": \"Value\"}");
      Parameters:
      json - The JSON string representation of a DynamoDB Item.
      Returns:
      A new instance of EnhancedDocument.
      Throws:
      IllegalArgumentException - if the json parameter is null

    • fromAttributeValueMap

      static EnhancedDocument fromAttributeValueMap(Map<String,AttributeValue> attributeValueMap)
      Creates a new EnhancedDocument instance from a AttributeValue Map. The AttributeConverterProvider.defaultProvider() is used as the default ConverterProvider. Example usage: 
      EnhancedDocument documentFromJson = EnhancedDocument.fromAttributeValueMap(stringKeyAttributeValueMao)
      ); }
      Parameters:
      attributeValueMap - - Map with Attributes as String keys and AttributeValue as Value.
      Returns:
      A new instance of EnhancedDocument.
      Throws:
      IllegalArgumentException - if the json parameter is null

    • builder

      static EnhancedDocument.Builder builder()
      Creates a default builder for EnhancedDocument.

    • toBuilder

      EnhancedDocument.Builder toBuilder()
      Converts an existing EnhancedDocument into a builder object that can be used to modify its values and then create a new EnhancedDocument.
      Returns:
      A EnhancedDocument.Builder initialized with the values of this EnhancedDocument.

    • isNull

      boolean isNull(String attributeName)
      Checks if the document is a null value.
      Parameters:
      attributeName - Name of the attribute that needs to be checked.
      Returns:
      true if the specified attribute exists with a null value; false otherwise.

    • isPresent

      boolean isPresent(String attributeName)
      Checks if the attribute exists in the document.
      Parameters:
      attributeName - Name of the attribute that needs to be checked.
      Returns:
      true if the specified attribute exists with a null/non-null value; false otherwise.

    • get

      <T> T get(String attributeName, EnhancedType<T> type)
      Returns the value of the specified attribute in the current document as a specified EnhancedType; or null if the attribute either doesn't exist or the attribute value is null.

      Retrieving String Type for a document 

      String resultCustom = document.get("key", EnhancedType.of(String.class));
      Retrieving Custom Type for which Convertor Provider was defined while creating the document 
      Custom resultCustom = document.get("key", EnhancedType.of(Custom.class));
      Retrieving list of strings in a document 
      List<String> resultList = document.get("key", EnhancedType.listOf(String.class));
      Retrieving a Map with List of strings in its values 
      Map<String, List<String>>> resultNested = document.get("key", new EnhancedType<Map<String, List<String>>>(){});

      Type Parameters:
      T - The type of the attribute value.
      Parameters:
      attributeName - Name of the attribute.
      type - EnhancedType of the value
      Returns:
      Attribute value of type T }

    • get

      <T> T get(String attributeName, Class<T> clazz)
      Returns the value of the specified attribute in the current document as a specified class type; or null if the attribute either doesn't exist or the attribute value is null.

      Retrieving String Type for a document 

      String resultCustom = document.get("key", String.class);
      Retrieving Custom Type for which Convertor Provider was defined while creating the document 
      Custom resultCustom = document.get("key", Custom.class);

      Note : This API should not be used to retrieve values of List and Map types. Instead, getList and getMap APIs should be used to retrieve attributes of type List and Map, respectively.

      Type Parameters:
      T - The type of the attribute value.
      Parameters:
      attributeName - Name of the attribute.
      clazz - Class type of value.
      Returns:
      Attribute value of type T }

    • getString

      String getString(String attributeName)
      Gets the String value of specified attribute in the document.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a string; or null if the attribute either doesn't exist or the attribute value is null

    • getNumber

      SdkNumber getNumber(String attributeName)
      Gets the SdkNumber value of specified attribute in the document.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a number; or null if the attribute either doesn't exist or the attribute value is null

    • getBytes

      SdkBytes getBytes(String attributeName)
      Gets the SdkBytes value of specified attribute in the document.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      the value of the specified attribute in the current document as SdkBytes; or null if the attribute either doesn't exist or the attribute value is null.

    • getStringSet

      Set<String> getStringSet(String attributeName)
      Gets the Set of String values of the given attribute in the current document.
      Parameters:
      attributeName - the name of the attribute.
      Returns:
      the value of the specified attribute in the current document as a set of strings; or null if the attribute either does not exist or the attribute value is null.

    • getNumberSet

      Set<SdkNumber> getNumberSet(String attributeName)
      Gets the Set of String values of the given attribute in the current document.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a set of SdkNumber; or null if the attribute either doesn't exist or the attribute value is null.

    • getBytesSet

      Set<SdkBytes> getBytesSet(String attributeName)
      Gets the Set of String values of the given attribute in the current document.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a set of SdkBytes; or null if the attribute doesn't exist.

    • getList

      <T> List<T> getList(String attributeName, EnhancedType<T> type)
      Gets the List of values of type T for the given attribute in the current document.
      Type Parameters:
      T - Type T of List elements
      Parameters:
      attributeName - Name of the attribute.
      type - EnhancedType of Type T.
      Returns:
      value of the specified attribute in the current document as a list of type T, or null if the attribute does not exist.

    • getMap

      <K, V> Map<K,V> getMap(String attributeName, EnhancedType<K> keyType, EnhancedType<V> valueType)
      Returns a map of a specific Key-type and Value-type based on the given attribute name, key type, and value type. Example usage: When getting an attribute as a map of UUID keys and Integer values, use this API as shown below: 
             Map<String, Integer> result = document.getMap("key", EnhancedType.of(String.class), EnhancedType.of(Integer.class));
      Type Parameters:
      K - The type of the Map keys.
      V - The type of the Map values.
      Parameters:
      attributeName - The name of the attribute that needs to be get as Map.
      keyType - Enhanced Type of Key attribute, like String, UUID etc that can be represented as String Keys.
      valueType - Enhanced Type of Values , which have converters defineds in EnhancedDocument.Builder.attributeConverterProviders(AttributeConverterProvider...) for the document
      Returns:
      Map of type K and V with the given attribute name, key type, and value type.

    • getJson

      String getJson(String attributeName)
      Gets the JSON document value of the specified attribute.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a JSON string; or null if the attribute either doesn't exist or the attribute value is null.

    • getBoolean

      Boolean getBoolean(String attributeName)
      Gets the Boolean value for the specified attribute.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a Boolean representation; or null if the attribute either doesn't exist or the attribute value is null.
      Throws:
      RuntimeException - if the attribute value cannot be converted to a Boolean representation. Note that the Boolean representation of 0 and 1 in Numbers and "0" and "1" in Strings is false and true, respectively.

    • getListOfUnknownType

      List<AttributeValue> getListOfUnknownType(String attributeName)
      Retrieves a list of AttributeValue objects for a specified attribute in a document. This API should be used when the elements of the list are a combination of different types such as Strings, Maps, and Numbers. If all elements in the list are of a known fixed type, use getList(String, EnhancedType) instead.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a List of AttributeValue

    • getMapOfUnknownType

      Map<String,AttributeValue> getMapOfUnknownType(String attributeName)
      Retrieves a Map with String keys and corresponding AttributeValue objects as values for a specified attribute in a document. This API is particularly useful when the values of the map are of different types such as strings, maps, and numbers. However, if all the values in the map for a given attribute key are of a known fixed type, it is recommended to use the method EnhancedDocument#getMap(String, EnhancedType, EnhancedType) instead.
      Parameters:
      attributeName - Name of the attribute.
      Returns:
      value of the specified attribute in the current document as a AttributeValue

    • toJson

      String toJson()
      Returns:
      document as a JSON string. Note all binary data will become base-64 encoded in the resultant string.

    • toMap

      Map<String,AttributeValue> toMap()
      This method converts a document into a key-value map with the keys as String objects and the values as AttributeValue objects. It can be particularly useful for documents with attributes of unknown types, as it allows for further processing or manipulation of the document data in a AttributeValue format.
      Returns:
      Document as a String AttributeValue Key-Value Map

    • attributeConverterProviders

      List<AttributeConverterProvider> attributeConverterProviders()
      Returns:
      List of AttributeConverterProvider defined for the given Document.