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
Item
to 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.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 fromList
intoSet
, throwingIllegalArgumentException
should there be duplicate elements.boolean
equals(Object in)
static Item
fromJSON(String json)
Convenient factory method - instantiates anItem
from the given JSON string.static Item
fromMap(Map<String,Object> attributes)
Convenient factory method - instantiates anItem
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 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.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 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.double
getDouble(String attrName)
Returns the value of the specified attribute in the current item as adouble
.float
getFloat(String attrName)
Returns the value of the specified attribute in the current item as afloat
.int
getInt(String attrName)
Returns the value of the specified attribute in the current item as anint
.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 ofT
'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 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.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.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 ashort
.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
hasAttribute(String attrName)
Returns true if this item has the specified attribute; false otherwise.int
hashCode()
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, Object... vals)
Sets the value of the specified attribute in the current item to the given values as a list.Item
withList(String attrName, List<?> val)
Sets the value of the specified attribute in the current item to the given value.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, Number val)
Sets the value of the specified attribute in the current item to the given value.Item
withNumber(String attrName, BigDecimal 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, String... val)
Sets the value of the specified attribute in the current item to the given value.Item
withStringSet(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 ifT
referred to aNumber
type, it would need to beBigDecimal
to 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, onlyShort
Integer
Long
Float
Double
Number
BigDecimal
BigInteger
- 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 anItem
from the given map.- Parameters:
attributes
- simple Java types; not the DyanmoDB types
-
fromJSON
public static Item fromJSON(String json)
Convenient factory method - instantiates anItem
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 fromList
intoSet
, throwingIllegalArgumentException
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.
-
-