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

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

Enhanced Document can be created with Json as input using Static factory method.In this case it used defaultConverterProviders. The attribute converter are always required to be provided, thus for default conversion AttributeConverterProvider.defaultProvider() must be supplied.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	EnhancedDocument.Builder

Method Summary

Modifier and Type	Method and Description
List<AttributeConverterProvider>	attributeConverterProviders()
static EnhancedDocument.Builder	builder() Creates a default builder for EnhancedDocument.
static EnhancedDocument	fromAttributeValueMap(Map<String,AttributeValue> attributeValueMap) Creates a new EnhancedDocument instance from a AttributeValue Map.
static EnhancedDocument	fromJson(String json) Creates a new EnhancedDocument instance from a JSON string.
<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.
<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.
Boolean	getBoolean(String attributeName) Gets the Boolean value for the specified attribute.
SdkBytes	getBytes(String attributeName) Gets the SdkBytes value of specified attribute in the document.
Set<SdkBytes>	getBytesSet(String attributeName) Gets the Set of String values of the given attribute in the current document.
String	getJson(String attributeName) Gets the JSON document value of the specified attribute.
<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.
List<AttributeValue>	getListOfUnknownType(String attributeName) Retrieves a list of AttributeValue objects for a specified attribute in a document.
<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.
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.
SdkNumber	getNumber(String attributeName) Gets the SdkNumber value of specified attribute in the document.
Set<SdkNumber>	getNumberSet(String attributeName) Gets the Set of String values of the given attribute in the current document.
String	getString(String attributeName) Gets the String value of specified attribute in the document.
Set<String>	getStringSet(String attributeName) Gets the Set of String values of the given attribute in the current document.
boolean	isNull(String attributeName) Checks if the document is a null value.
boolean	isPresent(String attributeName) Checks if the attribute exists in the document.
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.
String	toJson()
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.

Method Detail

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.

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: ); }

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 Retrieving Custom Type for which Convertor Provider was defined while creating the document Retrieving list of strings in a document Retrieving a Map with List of strings in its values

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 Retrieving Custom Type for which Convertor Provider was defined while creating the document

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:

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.