com.amazonaws.services.dynamodbv2.document

Class Item

java.lang.Object

com.amazonaws.services.dynamodbv2.document.Item

public class Item
extends Object

An item in DynamoDB. An item is a collection of attributes. Each attribute has a name and a value. An attribute value can be one of the followings:

• String
• Set<String>
• Number (including any subtypes and primitive types)
• Set<Number>
• byte[]
• Set<byte[]>
• ByteBuffer
• Set<ByteBuffer>
• Boolean or boolean
• null
• Map<String,T>, where T can be any type on this list but must not induce any circular reference
• List<T>, where T can be any type on this list but must not induce any circular reference

For an Item to be successfully persisted in DynamoDB, at a minimum the respective attributes for the primary key must be specified.

Constructor Summary

Constructors

Constructor and Description
Item()

Method Summary

Methods

Modifier and Type	Method and Description
Map<String,Object>	asMap() Returns all attributes of the current item as a map.
Iterable<Map.Entry<String,Object>>	attributes() Returns all attributes of the current item.
Item	base64Decode(String... binaryAttrNames) Utility method to decode the designated binary attributes from base-64 encoding; converting binary lists into binary sets.
Item	convertListsToSets(String... listAttrNames) Utility method to converts the designated attributes from List into Set, throwing IllegalArgumentException should there be duplicate elements.
static Item	fromJSON(String json) Convenient factory method - instantiates an Item from the given JSON string.
static Item	fromMap(Map<String,Object> attributes) Convenient factory method - instantiates an Item from the given map.
Object	get(String attrName) Returns the value of the specified attribute in the current item as an object; or null if the attribute either doesn't exist or the attribute value is null.
BigInteger	getBigInteger(String attrName) Returns the value of the specified attribute in the current item as an BigInteger; or null if the attribute doesn't exist.
byte[]	getBinary(String attrName) Returns the value of the specified attribute in the current item as a byte array; or null if the attribute either doesn't exist or the attribute value is null.
Set<byte[]>	getBinarySet(String attrName) Returns the value of the specified attribute in the current item as a set of byte arrays; or null if the attribute either doesn't exist or the attribute value is null.
Boolean	getBOOL(String attrName) Returns the value of the specified attribute in the current item as a non-null Boolean.
boolean	getBoolean(String attrName) Returns the value of the specified attribute in the current item as a primitive boolean.
ByteBuffer	getByteBuffer(String attrName) Returns the value of the specified attribute in the current item as a ByteBuffer; or null if the attribute either doesn't exist or the attribute value is null.
Set<ByteBuffer>	getByteBufferSet(String attrName) Returns the value of the specified attribute in the current item as a set of ByteBuffer; or null if the attribute either doesn't exist or the attribute value is null.
double	getDouble(String attrName) Returns the value of the specified attribute in the current item as a double.
float	getFloat(String attrName) Returns the value of the specified attribute in the current item as a float.
int	getInt(String attrName) Returns the value of the specified attribute in the current item as an int.
String	getJSON(String attrName) Returns the value of the specified attribute in the current item as a JSON string; or null if the attribute either doesn't exist or the attribute value is null.
String	getJSONPretty(String attrName) Returns the value of the specified attribute in the current item as a JSON string with pretty indentation; or null if the attribute either doesn't exist or the attribute value is null.
<T> List<T>	getList(String attrName) Returns the value of the specified attribute in the current item as a set of T's.; or null if the attribute either doesn't exist or the attribute value is null.
long	getLong(String attrName) Returns the value of the specified attribute in the current item as an long.
<T> Map<String,T>	getMap(String attrName) Returns the value of the specified attribute in the current item as a map of string-to-T's; or null if the attribute either doesn't exist or the attribute value is null.
<T extends Number> Map<String,T>	getMapOfNumbers(String attrName, Class<T> valueType) Convenient method to return the specified attribute in the current item as a (copy of) map of string-to-T's where T must be a subclass of Number; or null if the attribute doesn't exist.
BigDecimal	getNumber(String attrName) Returns the value of the specified attribute in the current item as a BigDecimal; or null if the attribute either doesn't exist or the attribute value is null.
Set<BigDecimal>	getNumberSet(String attrName) Returns the value of the specified attribute in the current item as a set of BigDecimal's; or null if the attribute either doesn't exist or the attribute value is null.
Map<String,Object>	getRawMap(String attrName) Convenient method to return the value of the specified attribute in the current item as a map of string-to-Object's; or null if the attribute either doesn't exist or the attribute value is null.
short	getShort(String attrName) Returns the value of the specified attribute in the current item as a short.
String	getString(String attrName) Returns the value of the specified attribute in the current item as a string; or null if the attribute either doesn't exist or the attribute value is null.
Set<String>	getStringSet(String attrName) Returns the value of the specified attribute in the current item as a set of strings; or null if the attribute either doesn't exist or the attribute value is null.
Class<?>	getTypeOf(String attrName) Returns the type of the specified attribute in the current item; or null if the attribute either doesn't exist or the attribute value is null.
boolean	isNull(String attrName) Returns true if the specified attribute exists with a null value; false otherwise.
boolean	isPresent(String attrName) Returns true if this item contains the specified attribute; false otherwise.
int	numberOfAttributes() Returns the number of attributes of this item.
Item	removeAttribute(String attrName) Removes the specified attribute from the current item.
String	toJSON() Returns this item as a JSON string.
String	toJSONPretty() Returns this item as a pretty JSON string.
String	toString()
Item	with(String attrName, Object val) Sets the value of the specified attribute to the given value.
Item	withBigDecimalSet(String attrName, BigDecimal... vals) Sets the value of the specified attribute in the current item to the given value.
Item	withBigDecimalSet(String attrName, Set<BigDecimal> val) Sets the value of the specified attribute in the current item to the given value.
Item	withBigInteger(String attrName, BigInteger val) Sets the value of the specified attribute in the current item to the given value.
Item	withBinary(String attrName, byte[] val) Sets the value of the specified attribute in the current item to the given value.
Item	withBinary(String attrName, ByteBuffer val) Sets the value of the specified attribute in the current item to the given value.
Item	withBinarySet(String attrName, byte[]... vals) Sets the value of the specified attribute in the current item to the given value.
Item	withBinarySet(String attrName, ByteBuffer... vals) Sets the value of the specified attribute in the current item to the given value.
Item	withBinarySet(String attrName, Set<byte[]> val) Sets the value of the specified attribute in the current item to the given value.
Item	withBoolean(String attrName, boolean val) Sets the value of the specified attribute in the current item to the boolean value.
Item	withByteBufferSet(String attrName, Set<ByteBuffer> val) Sets the value of the specified attribute in the current item to the given value.
Item	withDouble(String attrName, double val) Sets the value of the specified attribute in the current item to the given value.
Item	withFloat(String attrName, float val) Sets the value of the specified attribute in the current item to the given value.
Item	withInt(String attrName, int val) Sets the value of the specified attribute in the current item to the given value.
Item	withJSON(String attrName, String json) Sets the value of the specified attribute in the current item to the given JSON document in the form of a string.
Item	withKeyComponent(String keyAttrName, Object keyAttrValue) Convenient methods - sets an attribute of this item for the specified key attribute name and value.
Item	withKeyComponents(KeyAttribute... components) Convenient methods - sets the attributes of this item from the specified key components.
Item	withList(String attrName, List<?> val) Sets the value of the specified attribute in the current item to the given value.
Item	withList(String attrName, Object... vals) Sets the value of the specified attribute in the current item to the given values as a list.
Item	withLong(String attrName, long val) Sets the value of the specified attribute in the current item to the given value.
Item	withMap(String attrName, Map<String,?> val) Sets the value of the specified attribute in the current item to the given value.
Item	withNull(String attrName) Sets the value of the specified attribute to null.
Item	withNumber(String attrName, BigDecimal val) Sets the value of the specified attribute in the current item to the given value.
Item	withNumber(String attrName, Number val) Sets the value of the specified attribute in the current item to the given value.
Item	withNumberSet(String attrName, Number... vals) Sets the value of the specified attribute in the current item to the given value.
Item	withNumberSet(String attrName, Set<Number> vals) Sets the value of the specified attribute in the current item to the given value.
Item	withPrimaryKey(PrimaryKey primaryKey) Convenient methods - sets the attributes of this item from the given key attributes.
Item	withPrimaryKey(String hashKeyName, Object hashKeyValue) Convenient method to set the attributes of this item from the given hash-only primary key name and value.
Item	withPrimaryKey(String hashKeyName, Object hashKeyValue, String rangeKeyName, Object rangeKeyValue) Convenient method to set the attributes of this item from the given hash and range primary key.
Item	withShort(String attrName, short val) Sets the value of the specified attribute in the current item to the given value.
Item	withString(String attrName, String val) Sets the value of the specified attribute in the current item to the given string value.
Item	withStringSet(String attrName, Set<String> val) Sets the value of the specified attribute in the current item to the given value.
Item	withStringSet(String attrName, String... val) Sets the value of the specified attribute in the current item to the given value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Item

public Item()

Method Detail

isNull

public boolean isNull(String attrName)

Returns true if the specified attribute exists with a null value; false otherwise.

isPresent

public boolean isPresent(String attrName)

Returns true if this item contains the specified attribute; false otherwise.

getString

public String getString(String attrName)

Returns the value of the specified attribute in the current item as a string; or null if the attribute either doesn't exist or the attribute value is null.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withString

public Item withString(String attrName,
              String val)

Sets the value of the specified attribute in the current item to the given string value.

getNumber

public BigDecimal getNumber(String attrName)

Returns the value of the specified attribute in the current item as a BigDecimal; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

NumberFormatException - if the attribute value is not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getBigInteger

public BigInteger getBigInteger(String attrName)

Returns the value of the specified attribute in the current item as an BigInteger; or null if the attribute doesn't exist.

Throws:

NumberFormatException - if the attribute value is null or not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getShort

public short getShort(String attrName)

Returns the value of the specified attribute in the current item as a short.

Throws:

NumberFormatException - if the attribute value is null or not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getInt

public int getInt(String attrName)

Returns the value of the specified attribute in the current item as an int.

Throws:

NumberFormatException - if the attribute value is null or not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getLong

public long getLong(String attrName)

Returns the value of the specified attribute in the current item as an long.

Throws:

NumberFormatException - if the attribute value is null or not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getFloat

public float getFloat(String attrName)

Returns the value of the specified attribute in the current item as a float.

Throws:

NumberFormatException - if the attribute value is null or not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getDouble

public double getDouble(String attrName)

Returns the value of the specified attribute in the current item as a double.

Throws:

NumberFormatException - if the attribute value is null or not a valid representation of a BigDecimal.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withNumber

public Item withNumber(String attrName,
              BigDecimal val)

Sets the value of the specified attribute in the current item to the given value.

withNumber

public Item withNumber(String attrName,
              Number val)

Sets the value of the specified attribute in the current item to the given value.

withInt

public Item withInt(String attrName,
           int val)

Sets the value of the specified attribute in the current item to the given value.

withBigInteger

public Item withBigInteger(String attrName,
                  BigInteger val)

Sets the value of the specified attribute in the current item to the given value.

withShort

public Item withShort(String attrName,
             short val)

Sets the value of the specified attribute in the current item to the given value.

withFloat

public Item withFloat(String attrName,
             float val)

Sets the value of the specified attribute in the current item to the given value.

withDouble

public Item withDouble(String attrName,
              double val)

Sets the value of the specified attribute in the current item to the given value.

withLong

public Item withLong(String attrName,
            long val)

Sets the value of the specified attribute in the current item to the given value.

getBinary

public byte[] getBinary(String attrName)

Returns the value of the specified attribute in the current item as a byte array; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

UnsupportedOperationException - If the attribute value involves a byte buffer which is not backed by an accessible array

IncompatibleTypeException - if the attribute value cannot be converted into a byte array

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getByteBuffer

public ByteBuffer getByteBuffer(String attrName)

Returns the value of the specified attribute in the current item as a ByteBuffer; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

IncompatibleTypeException - if the attribute value cannot be converted into a byte array

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withBinary

public Item withBinary(String attrName,
              byte[] val)

Sets the value of the specified attribute in the current item to the given value.

withBinary

public Item withBinary(String attrName,
              ByteBuffer val)

Sets the value of the specified attribute in the current item to the given value.

getStringSet

public Set<String> getStringSet(String attrName)

Returns the value of the specified attribute in the current item as a set of strings; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

IncompatibleTypeException - if the attribute value cannot be converted into a set of strings because of duplicate elements

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withStringSet

public Item withStringSet(String attrName,
                 Set<String> val)

Sets the value of the specified attribute in the current item to the given value.

withStringSet

public Item withStringSet(String attrName,
                 String... val)

Sets the value of the specified attribute in the current item to the given value.

getNumberSet

public Set<BigDecimal> getNumberSet(String attrName)

Returns the value of the specified attribute in the current item as a set of BigDecimal's; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

NumberFormatException - if the attribute involves a value that is not a valid representation of a BigDecimal.

IncompatibleTypeException - if the attribute value cannot be converted into a set of BigDecimal's because of duplicate elements

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withBigDecimalSet

public Item withBigDecimalSet(String attrName,
                     Set<BigDecimal> val)

Sets the value of the specified attribute in the current item to the given value.

withBigDecimalSet

public Item withBigDecimalSet(String attrName,
                     BigDecimal... vals)

Sets the value of the specified attribute in the current item to the given value.

withNumberSet

public Item withNumberSet(String attrName,
                 Number... vals)

Sets the value of the specified attribute in the current item to the given value.

withNumberSet

public Item withNumberSet(String attrName,
                 Set<Number> vals)

Sets the value of the specified attribute in the current item to the given value.

getBinarySet

public Set<byte[]> getBinarySet(String attrName)

Returns the value of the specified attribute in the current item as a set of byte arrays; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

IncompatibleTypeException - if the attribute value cannot be converted into a set of byte arrays

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getByteBufferSet

public Set<ByteBuffer> getByteBufferSet(String attrName)

Returns the value of the specified attribute in the current item as a set of ByteBuffer; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

IncompatibleTypeException - if the attribute value cannot be converted into a set of ByteBuffer

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withBinarySet

public Item withBinarySet(String attrName,
                 Set<byte[]> val)

Sets the value of the specified attribute in the current item to the given value.

withByteBufferSet

public Item withByteBufferSet(String attrName,
                     Set<ByteBuffer> val)

Sets the value of the specified attribute in the current item to the given value.

withBinarySet

public Item withBinarySet(String attrName,
                 byte[]... vals)

Sets the value of the specified attribute in the current item to the given value.

withBinarySet

public Item withBinarySet(String attrName,
                 ByteBuffer... vals)

Sets the value of the specified attribute in the current item to the given value.

getList

public <T> List<T> getList(String attrName)

Returns the value of the specified attribute in the current item as a set of T's.; or null if the attribute either doesn't exist or the attribute value is null.

Throws:

ClassCastException - if the attribute involves a value that cannot be casted to T

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withList

public Item withList(String attrName,
            List<?> val)

Sets the value of the specified attribute in the current item to the given value.

withList

public Item withList(String attrName,
            Object... vals)

Sets the value of the specified attribute in the current item to the given values as a list.

getMap

public <T> Map<String,T> getMap(String attrName)

Returns the value of the specified attribute in the current item as a map of string-to-T's; or null if the attribute either doesn't exist or the attribute value is null. Note that any numeric type of a map is always canonicalized into BigDecimal, and therefore if T referred to a Number type, it would need to be BigDecimal to avoid a class cast exception.

Throws:

ClassCastException - if the attribute is not a map of string to T

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getMapOfNumbers

public <T extends Number> Map<String,T> getMapOfNumbers(String attrName,
                                               Class<T> valueType)

Convenient method to return the specified attribute in the current item as a (copy of) map of string-to-T's where T must be a subclass of Number; or null if the attribute doesn't exist.

Parameters:

attrName - the attribute name

valueType - the specific number type of the value to be returned. Currently, only

• Short
• Integer
• Long
• Float
• Double
• Number
• BigDecimal
• BigInteger

are supported.

Throws:

UnsupportedOperationException - if the value type is not supported

ClassCastException - if the attribute is not a map of string to numbers

getRawMap

public Map<String,Object> getRawMap(String attrName)

Convenient method to return the value of the specified attribute in the current item as a map of string-to-Object's; or null if the attribute either doesn't exist or the attribute value is null. Note that any numeric type of the map will be returned as BigDecimal.

Throws:

ClassCastException - if the attribute is not a map

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

withMap

public Item withMap(String attrName,
           Map<String,?> val)

Sets the value of the specified attribute in the current item to the given value.

withJSON

public Item withJSON(String attrName,
            String json)

Sets the value of the specified attribute in the current item to the given JSON document in the form of a string.

getJSON

public String getJSON(String attrName)

Returns the value of the specified attribute in the current item as a JSON string; or null if the attribute either doesn't exist or the attribute value is null.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getJSONPretty

public String getJSONPretty(String attrName)

Returns the value of the specified attribute in the current item as a JSON string with pretty indentation; or null if the attribute either doesn't exist or the attribute value is null.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getBOOL

public Boolean getBOOL(String attrName)

Returns the value of the specified attribute in the current item as a non-null Boolean.

Throws:

IncompatibleTypeException - if either the attribute doesn't exist or if the attribute value cannot be converted into a non-null Boolean value

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getBoolean

public boolean getBoolean(String attrName)

Returns the value of the specified attribute in the current item as a primitive boolean.

Throws:

IncompatibleTypeException - if either the attribute doesn't exist or if the attribute value cannot be converted into a boolean value

withBoolean

public Item withBoolean(String attrName,
               boolean val)

Sets the value of the specified attribute in the current item to the boolean value.

withNull

public Item withNull(String attrName)

Sets the value of the specified attribute to null.

with

public Item with(String attrName,
        Object val)

Sets the value of the specified attribute to the given value. An attribute value can be a

• Number
• String
• binary (ie byte array or byte buffer)
• boolean
• null
• list (of any of the types on this list)
• map (with string key to value of any of the types on this list)
• set (of any of the types on this list)

withPrimaryKey

public Item withPrimaryKey(PrimaryKey primaryKey)

Convenient methods - sets the attributes of this item from the given key attributes.

withPrimaryKey

public Item withPrimaryKey(String hashKeyName,
                  Object hashKeyValue)

Convenient method to set the attributes of this item from the given hash-only primary key name and value.

withPrimaryKey

public Item withPrimaryKey(String hashKeyName,
                  Object hashKeyValue,
                  String rangeKeyName,
                  Object rangeKeyValue)

Convenient method to set the attributes of this item from the given hash and range primary key.

withKeyComponents

public Item withKeyComponents(KeyAttribute... components)

Convenient methods - sets the attributes of this item from the specified key components.

withKeyComponent

public Item withKeyComponent(String keyAttrName,
                    Object keyAttrValue)

Convenient methods - sets an attribute of this item for the specified key attribute name and value.

get

public Object get(String attrName)

Returns the value of the specified attribute in the current item as an object; or null if the attribute either doesn't exist or the attribute value is null.

An attribute value can be a

• Number
• String
• binary (ie byte array or byte buffer)
• boolean
• null
• list (of any of the types on this list)
• map (with string key to value of any of the types on this list)
• set (of any of the types on this list)

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

getTypeOf

public Class<?> getTypeOf(String attrName)

Returns the type of the specified attribute in the current item; or null if the attribute either doesn't exist or the attribute value is null.

See Also:

#isNull(String) to check if the attribute value is null., #isPresent(String) to check if the attribute value is present.

removeAttribute

public Item removeAttribute(String attrName)

Removes the specified attribute from the current item.

attributes

public Iterable<Map.Entry<String,Object>> attributes()

Returns all attributes of the current item.

asMap

public Map<String,Object> asMap()

Returns all attributes of the current item as a map.

numberOfAttributes

public int numberOfAttributes()

Returns the number of attributes of this item.

fromMap

public static Item fromMap(Map<String,Object> attributes)

Convenient factory method - instantiates an Item from the given map.

Parameters:

attributes - simple Java types; not the DyanmoDB types

fromJSON

public static Item fromJSON(String json)

Convenient factory method - instantiates an Item from the given JSON string.

Returns:

an Item initialized from the given JSON document; or null if the input is null.

toJSON

public String toJSON()

Returns this item as a JSON string. Note all binary data will become base-64 encoded in the resultant string.

base64Decode

public Item base64Decode(String... binaryAttrNames)

Utility method to decode the designated binary attributes from base-64 encoding; converting binary lists into binary sets.

Parameters:

binaryAttrNames - names of binary attributes or binary set attributes currently base-64 encoded (typically when converted from a JSON string.)

See Also:

fromJSON(String)

convertListsToSets

public Item convertListsToSets(String... listAttrNames)

Utility method to converts the designated attributes from List into Set, throwing IllegalArgumentException should there be duplicate elements.

Parameters:

listAttrNames - names of attributes to be converted.

See Also:

fromJSON(String)

toJSONPretty

public String toJSONPretty()

Returns this item as a pretty JSON string. Note all binary data will become base-64 encoded in the resultant string.

toString

public String toString()

Overrides:

toString in class Object