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
Itemto be successfully persisted in DynamoDB, at a minimum the respective attributes for the primary key must be specified.
-
-
Constructor Summary
Constructors Constructor Description Item()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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.Itembase64Decode(String... binaryAttrNames)Utility method to decode the designated binary attributes from base-64 encoding; converting binary lists into binary sets.ItemconvertListsToSets(String... listAttrNames)Utility method to converts the designated attributes fromListintoSet, throwingIllegalArgumentExceptionshould there be duplicate elements.booleanequals(Object in)static ItemfromJSON(String json)Convenient factory method - instantiates anItemfrom the given JSON string.static ItemfromMap(Map<String,Object> attributes)Convenient factory method - instantiates anItemfrom the given map.Objectget(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.BigIntegergetBigInteger(String attrName)Returns the value of the specified attribute in the current item as anBigInteger; 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.BooleangetBOOL(String attrName)Returns the value of the specified attribute in the current item as a non-null Boolean.booleangetBoolean(String attrName)Returns the value of the specified attribute in the current item as a primitive boolean.ByteBuffergetByteBuffer(String attrName)Returns the value of the specified attribute in the current item as aByteBuffer; 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 ofByteBuffer; or null if the attribute either doesn't exist or the attribute value is null.doublegetDouble(String attrName)Returns the value of the specified attribute in the current item as adouble.floatgetFloat(String attrName)Returns the value of the specified attribute in the current item as afloat.intgetInt(String attrName)Returns the value of the specified attribute in the current item as anint.StringgetJSON(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.StringgetJSONPretty(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 ofT's.; or null if the attribute either doesn't exist or the attribute value is null.longgetLong(String attrName)Returns the value of the specified attribute in the current item as anlong.<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 ofNumber; or null if the attribute doesn't exist.BigDecimalgetNumber(String attrName)Returns the value of the specified attribute in the current item as aBigDecimal; 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.shortgetShort(String attrName)Returns the value of the specified attribute in the current item as ashort.StringgetString(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.booleanhasAttribute(String attrName)Returns true if this item has the specified attribute; false otherwise.inthashCode()booleanisNull(String attrName)Returns true if the specified attribute exists with a null value; false otherwise.booleanisPresent(String attrName)Returns true if this item contains the specified attribute; false otherwise.intnumberOfAttributes()Returns the number of attributes of this item.ItemremoveAttribute(String attrName)Removes the specified attribute from the current item.StringtoJSON()Returns this item as a JSON string.StringtoJSONPretty()Returns this item as a pretty JSON string.StringtoString()Itemwith(String attrName, Object val)Sets the value of the specified attribute to the given value.ItemwithBigDecimalSet(String attrName, BigDecimal... vals)Sets the value of the specified attribute in the current item to the given value.ItemwithBigDecimalSet(String attrName, Set<BigDecimal> val)Sets the value of the specified attribute in the current item to the given value.ItemwithBigInteger(String attrName, BigInteger val)Sets the value of the specified attribute in the current item to the given value.ItemwithBinary(String attrName, byte[] val)Sets the value of the specified attribute in the current item to the given value.ItemwithBinary(String attrName, ByteBuffer val)Sets the value of the specified attribute in the current item to the given value.ItemwithBinarySet(String attrName, byte[]... vals)Sets the value of the specified attribute in the current item to the given value.ItemwithBinarySet(String attrName, ByteBuffer... vals)Sets the value of the specified attribute in the current item to the given value.ItemwithBinarySet(String attrName, Set<byte[]> val)Sets the value of the specified attribute in the current item to the given value.ItemwithBoolean(String attrName, boolean val)Sets the value of the specified attribute in the current item to the boolean value.ItemwithByteBufferSet(String attrName, Set<ByteBuffer> val)Sets the value of the specified attribute in the current item to the given value.ItemwithDouble(String attrName, double val)Sets the value of the specified attribute in the current item to the given value.ItemwithFloat(String attrName, float val)Sets the value of the specified attribute in the current item to the given value.ItemwithInt(String attrName, int val)Sets the value of the specified attribute in the current item to the given value.ItemwithJSON(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.ItemwithKeyComponent(String keyAttrName, Object keyAttrValue)Convenient methods - sets an attribute of this item for the specified key attribute name and value.ItemwithKeyComponents(KeyAttribute... components)Convenient methods - sets the attributes of this item from the specified key components.ItemwithList(String attrName, Object... vals)Sets the value of the specified attribute in the current item to the given values as a list.ItemwithList(String attrName, List<?> val)Sets the value of the specified attribute in the current item to the given value.ItemwithLong(String attrName, long val)Sets the value of the specified attribute in the current item to the given value.ItemwithMap(String attrName, Map<String,?> val)Sets the value of the specified attribute in the current item to the given value.ItemwithNull(String attrName)Sets the value of the specified attribute to null.ItemwithNumber(String attrName, Number val)Sets the value of the specified attribute in the current item to the given value.ItemwithNumber(String attrName, BigDecimal val)Sets the value of the specified attribute in the current item to the given value.ItemwithNumberSet(String attrName, Number... vals)Sets the value of the specified attribute in the current item to the given value.ItemwithNumberSet(String attrName, Set<Number> vals)Sets the value of the specified attribute in the current item to the given value.ItemwithPrimaryKey(PrimaryKey primaryKey)Convenient methods - sets the attributes of this item from the given key attributes.ItemwithPrimaryKey(String hashKeyName, Object hashKeyValue)Convenient method to set the attributes of this item from the given hash-only primary key name and value.ItemwithPrimaryKey(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.ItemwithShort(String attrName, short val)Sets the value of the specified attribute in the current item to the given value.ItemwithString(String attrName, String val)Sets the value of the specified attribute in the current item to the given string value.ItemwithStringSet(String attrName, String... val)Sets the value of the specified attribute in the current item to the given value.ItemwithStringSet(String attrName, Set<String> val)Sets the value of the specified attribute in the current item to the given value.
-
-
-
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.
-
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 aBigDecimal; 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 aBigDecimal.- 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 anBigInteger; or null if the attribute doesn't exist.- Throws:
NumberFormatException- if the attribute value is null or not a valid representation of aBigDecimal.- 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 ashort.- Throws:
NumberFormatException- if the attribute value is null or not a valid representation of aBigDecimal.- 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 anint.- Throws:
NumberFormatException- if the attribute value is null or not a valid representation of aBigDecimal.- 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 anlong.- Throws:
NumberFormatException- if the attribute value is null or not a valid representation of aBigDecimal.- 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 afloat.- Throws:
NumberFormatException- if the attribute value is null or not a valid representation of aBigDecimal.- 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 adouble.- Throws:
NumberFormatException- if the attribute value is null or not a valid representation of aBigDecimal.- 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 arrayIncompatibleTypeException- 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 aByteBuffer; 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 aBigDecimal.IncompatibleTypeException- if the attribute value cannot be converted into a set ofBigDecimal'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 ofByteBuffer; 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 ofByteBuffer- 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 ofT'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 toT- 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 intoBigDecimal, and therefore ifTreferred to aNumbertype, it would need to beBigDecimalto avoid a class cast exception.- Throws:
ClassCastException- if the attribute is not a map of string toT- 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 ofNumber; or null if the attribute doesn't exist.- Parameters:
attrName- the attribute namevalueType- the specific number type of the value to be returned. Currently, onlyShortIntegerLongFloatDoubleNumberBigDecimalBigInteger
- Throws:
UnsupportedOperationException- if the value type is not supportedClassCastException- 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 asBigDecimal.- 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.
-
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.
-
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.
-
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)
-
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.
-
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.
-
hasAttribute
public boolean hasAttribute(String attrName)
Returns true if this item has the specified attribute; false otherwise.
-
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 anItemfrom the given map.- Parameters:
attributes- simple Java types; not the DyanmoDB types
-
fromJSON
public static Item fromJSON(String json)
Convenient factory method - instantiates anItemfrom the given JSON string.- Returns:
- an
Iteminitialized 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 fromListintoSet, throwingIllegalArgumentExceptionshould 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.
-
-