com.google.iot.cbor

Class CborMap

java.lang.Object

com.google.iot.cbor.CborObject

com.google.iot.cbor.CborMap

public abstract class CborMap
extends CborObject

Class for representing CBOR map data items.

This class is used to represent data items of major type 5 (CborMajorType.MAP).

Method Summary

Modifier and Type	Method and Description
boolean	areAllKeysStrings() Determines if all of the keys in this map are CborTextString instances.
void	clear()
boolean	containsKey(String key) Convenience test method to allow the use of standard String objects when the keys in the map are all CborTextString.
CborMap	copy() Creates an independent, deep copy of this CborMap.
static CborMap	create() Creates an empty, untagged CborMap object.
static CborMap	create(int tag) Creates an empty, tagged CborMap object.
static CborMap	create(Map<CborObject,CborObject> map) Creates a CborMap object populated with the keys and values from map.
static CborMap	create(Map<CborObject,CborObject> map, int tag) Creates a tagged CborMap object populated with the keys and values from map .
static CborMap	create(Map<CborObject,CborObject> map, int tag, boolean isIndefiniteLength) Creates a tagged CborMap object populated with the keys and values from map .
static CborMap	createFromCborByteArray(byte[] input) Parses the given CBOR byte array into a CborMap object.
static CborMap	createFromCborByteArray(byte[] input, int offset, int length) Parses the given CBOR byte array into a CborMap object.
static CborMap	createFromJavaObject(Map<?,?> obj) Converts the given Java Map into a CborMap object.
static CborMap	createFromJSONObject(org.json.JSONObject obj) Creates a untagged CborMap object from the given JSONObject.
Set<Map.Entry<CborObject,CborObject>>	entrySet()
boolean	equals(Object obj)
CborObject	get(CborObject key)
CborObject	get(String key) Convenience getter method to allow the use of standard String objects when the keys in the map are all CborTextString.
int	getAdditionalInformation() Returns the object's "additional information" value.
int	getMajorType() Returns the object's "Major Type", as defined by RFC7049.
int	hashCode()
boolean	isEmpty()
abstract boolean	isIndefiniteLength()
boolean	isValidJson() Indicates if this data item can be losslessly converted to a JSON fragment.
Set<CborObject>	keySet()
Set<String>	keySetAsStrings() Returns the key set as standard String objects instead of CborObject instances.
abstract Map<CborObject,CborObject>	mapValue()
CborObject	put(String key, CborObject value) Convenience setter method to allow the use of standard String objects when the keys in the map are all CborTextString.
CborObject	remove(CborObject key)
CborObject	remove(String key) Convenience removal method to allow the use of standard String objects when the keys in the map are all CborTextString.
int	size()
Map<Object,Object>	toJavaObject() Converts the given data item into a standard java object representation.
<T> T	toJavaObject(Class<T> clazz) Attempts to convert this data item to a java object with a specific class.
String	toJsonString() Returns a representation of this data item as JSON text.
Map<String,Object>	toNormalMap() Converts the CborMap into a standard Java Map<String,Object> that is guaranteed to use String objects for keys.
String	toString(int indentLevel) Describes this data item using CBOR diagnostic notation at the given indentation level.

Methods inherited from class com.google.iot.cbor.CborObject

createFromJavaObject, getTag, toCborByteArray, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

createFromCborByteArray

public static CborMap createFromCborByteArray(byte[] input,
                                              int offset,
                                              int length)
                                       throws CborParseException

Parses the given CBOR byte array into a CborMap object. If the data in the byte array is corrupted or if the type of object represented in the byte array isn't a CBOR Map, CborParseException is thrown. This method is similar to CborObject.createFromCborByteArray(byte[], int, int), except that it is CborMap-specific.

Parameters:

input - CBOR-encoded byte array. Must be a CBOR Map.

offset - Offset into input to start parsing.

length - the number of bytes to parse

Returns:

the created CborMap object

Throws:

CborParseException - if the input data is corrupt or if the input data doesn't represent a CborMap.

IndexOutOfBoundsException - if offset ois out of bounds

See Also:

createFromCborByteArray(byte[]), CborObject.createFromCborByteArray(byte[], int, int)

createFromCborByteArray

public static CborMap createFromCborByteArray(byte[] input)
                                       throws CborParseException

Parses the given CBOR byte array into a CborMap object. If the data in the byte array is corrupted or if the type of object represented in the byte array isn't a CBOR Map, CborParseException is thrown. This method is similar to CborObject.createFromCborByteArray(byte[]), except that it is CborMap-specific.

Parameters:

input - CBOR-encoded byte array. Must be a CBOR Map.

Returns:

the created CborMap object

Throws:

CborParseException - if the input data is corrupt or if the input data doesn't represent a CborMap.

See Also:

createFromCborByteArray(byte[], int, int), CborObject.createFromCborByteArray(byte[])

createFromJavaObject

public static CborMap createFromJavaObject(Map<?,?> obj)
                                    throws CborConversionException

Converts the given Java Map into a CborMap object. If the map contains keys or values that cannot be converted to CborObject instances, then CborConversionException is thrown. The returned CborMap will be untagged.

Parameters:

obj - the map to convert to a CborMap.

Returns:

the created CborMap object

Throws:

CborConversionException - if any of the map's keys or values cannot be represented as a CborObject.

create

public static CborMap create(int tag)

Creates an empty, tagged CborMap object.

Parameters:

tag - the tag to use on the new CborMap object

Returns:

the created CborMap object

create

public static CborMap create(Map<CborObject,CborObject> map,
                             int tag)

Creates a tagged CborMap object populated with the keys and values from map . The keys and values from map are used directly (they are not deep-copied).

Parameters:

map - the Map to use to pre-populate the entries in the new CborMap.

tag - the tag to use on the new CborMap object

Returns:

the created CborMap object

create

public static CborMap create(Map<CborObject,CborObject> map,
                             int tag,
                             boolean isIndefiniteLength)

Creates a tagged CborMap object populated with the keys and values from map . The keys and values from map are used directly (they are not deep-copied).

Parameters:

map - the Map to use to pre-populate the entries in the new CborMap.

tag - the tag to use on the new CborMap object

Returns:

the created CborMap object

create

public static CborMap create(Map<CborObject,CborObject> map)

Creates a CborMap object populated with the keys and values from map. The keys and values from map are used directly (they are not deep-copied).

Parameters:

map - the Map to use to pre-populate the entries in the new CborMap.

Returns:

the created CborMap object

createFromJSONObject

public static CborMap createFromJSONObject(org.json.JSONObject obj)

Creates a untagged CborMap object from the given JSONObject.

Parameters:

obj - the JSONObject used to pre-populate the entries in the new CborMap.

Returns:

the created CborMap object

create

public static CborMap create()

Creates an empty, untagged CborMap object.

Returns:

the created CborMap object

mapValue

public abstract Map<CborObject,CborObject> mapValue()

size

public int size()

isEmpty

public boolean isEmpty()

remove

@CanIgnoreReturnValue
public CborObject remove(CborObject key)

clear

public void clear()

entrySet

public Set<Map.Entry<CborObject,CborObject>> entrySet()

keySet

public Set<CborObject> keySet()

get

public CborObject get(CborObject key)

get

public final CborObject get(String key)

Convenience getter method to allow the use of standard String objects when the keys in the map are all CborTextString. The given key WILL NOT match tagged CborTextString objects, only untagged objects will match.

Parameters:

key - the string value to use as a key. i * @return The CborObject value, if found. null otherwise.

See Also:

put(String, CborObject), containsKey(String), remove(String), keySetAsStrings()

containsKey

public final boolean containsKey(String key)

Convenience test method to allow the use of standard String objects when the keys in the map are all CborTextString. The given key WILL NOT match tagged CborTextString objects, only untagged objects will match.

Parameters:

key - the string value to use as a key.

Returns:

true if there is a corresponding CborTextString object, false otherwise.

See Also:

put(String, CborObject), get(String), remove(String), keySetAsStrings()

put

@CanIgnoreReturnValue
public final CborObject put(String key,
                                                  CborObject value)

Convenience setter method to allow the use of standard String objects when the keys in the map are all CborTextString. The given key WILL NOT match tagged CborTextString objects, only untagged objects will match.

Parameters:

key - the string value to use as a key.

value - the CborObject to associate with this key.

Returns:

the previous value associated with key, or null if there was no mapping for key.

See Also:

get(String), containsKey(String), remove(String), keySetAsStrings()

remove

@CanIgnoreReturnValue
public final CborObject remove(String key)

Convenience removal method to allow the use of standard String objects when the keys in the map are all CborTextString. The given key WILL NOT match tagged CborTextString objects, only untagged objects will match.

Parameters:

key - the string value to use as a key.

Returns:

the previous value associated with key, or null if there was no mapping for key.

See Also:

get(String), containsKey(String), keySetAsStrings()

keySetAsStrings

public final Set<String> keySetAsStrings()
                                  throws CborConversionException

Returns the key set as standard String objects instead of CborObject instances. areAllKeysStrings() must return true in order for this method to be usable.

Throws:

CborConversionException - if there are keys in this map which are not CborTextString instances.

See Also:

put(String, CborObject), get(String), containsKey(String)

areAllKeysStrings

public final boolean areAllKeysStrings()

Determines if all of the keys in this map are CborTextString instances.

Returns:

true if all of the keys in this map are CborTextString instances or if there are no entries in this map; false otherwise.

See Also:

keySetAsStrings()

toNormalMap

public final Map<String,Object> toNormalMap()
                                     throws CborConversionException

Converts the CborMap into a standard Java Map<String,Object> that is guaranteed to use String objects for keys. This method differs from CborObject.toJavaObject() in that this method is guaranteed to return a map that is keyed only with String objects.

Throws:

CborConversionException - if not all of the keys are CborTextString objects.

getMajorType

public final int getMajorType()

Description copied from class: CborObject

Returns the object's "Major Type", as defined by RFC7049. See RFC7049 section 2 for more information.

Specified by:

getMajorType in class CborObject

See Also:

CborMajorType, CborObject.getAdditionalInformation()

getAdditionalInformation

public final int getAdditionalInformation()

Description copied from class: CborObject

Returns the object's "additional information" value. The meaning of this field is dependent on the major type. See RFC7049 section 2 for more information.

Specified by:

getAdditionalInformation in class CborObject

See Also:

CborObject.getMajorType()

isIndefiniteLength

public abstract boolean isIndefiniteLength()

toJavaObject

public final Map<Object,Object> toJavaObject()

Description copied from class: CborObject

Converts the given data item into a standard java object representation.

Tags are largely ignored, except in cases where the tag itself has defined behavior when converting to JSON, like CborTag.EXPECTED_BASE16 and CborTag.EXPECTED_BASE64.

The resulting object type is dependent on the data item:

• CborMap → Map<Object,Object>
• CborArray → Collection<Object>
• CborFloat → Float/Double
• CborInteger → Integer/Long
• CborTextString → String
• CborByteString → byte[]
• CborSimple.TRUE/CborSimple.FALSE → Boolean
• Other CborSimple values → null

The returned value is a wholly independent copy.

Specified by:

toJavaObject in class CborObject

See Also:

CborObject.createFromJavaObject(Object)

toJavaObject

public <T> T toJavaObject(Class<T> clazz)
                   throws CborConversionException

Description copied from class: CborObject

Attempts to convert this data item to a java object with a specific class.

Unlike CborObject.toJavaObject(), this method will introspect into tags to figure out conversions to BigInteger and URI. Unknown tags are ignored.

This method will return the most expressive result that satisfies the clazz parameter. For example, if the data item is a CborByteString tagged CborTag.BIGNUM_POS, calling this method with different classes will lead to different results:

• toJavaObject(byte[].class would return a byte[]
• toJavaObject(Object.class would return a BigInteger
• toJavaObject(BigInteger.class would return a BigInteger
• toJavaObject(URI.class would throw CborConversionException

Whereas this method called an untagged CborByteString would behave like this:

• toJavaObject(byte[].class would return a byte[]
• toJavaObject(Object.class would return a byte[]
• toJavaObject(BigInteger.class would throw CborConversionException
• toJavaObject(URI.class would throw CborConversionException

Specified by:

toJavaObject in class CborObject

Parameters:

clazz - The desired class of the returned object

Returns:

a reference to an object of class clazz or null if this data item was CborSimple.NULL or CborSimple.UNDEFINED.

Throws:

CborConversionException - if the underlying data item could not be represented as an instance of clazz.

copy

public final CborMap copy()

Creates an independent, deep copy of this CborMap.

Specified by:

copy in class CborObject

Returns:

the new CborMap object.

isValidJson

public final boolean isValidJson()

Description copied from class: CborObject

Indicates if this data item can be losslessly converted to a JSON fragment.

Note that, with few exceptions, tags are not considered in this determination, since CborObject.toJsonString() will strip out tags anyway.

Specified by:

isValidJson in class CborObject

Returns:

true if this object could be rendered as JSON, false otherwise.

toJsonString

public final String toJsonString()

Description copied from class: CborObject

Returns a representation of this data item as JSON text.

The result is guaranteed to be syntactically-valid RFC8259 JSON text. In the event that there is no JSON text representation for the underlying data item, its value will be replaced with a placeholder JSON value (usually "null"). This condition can be detected beforehand using CborObject.isValidJson().

Note that, in some pre-RFC8259 contexts, this method could be described as returning a "JSON fragment" unless the data item was of the types CborMap (for a JSON object) or CborArray (for a JSON array).

Specified by:

toJsonString in class CborObject

Returns:

a String containing representation of this data item as JSON text

See Also:

CborObject.isValidJson(), RFC8259

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString(int indentLevel)

Description copied from class: CborObject

Describes this data item using CBOR diagnostic notation at the given indentation level.

The output is similar to that of CborObject.toJsonString() except that it also includes tag and encoding information that is CBOR-specific.

The returned string is intended as a diagnostic aid and not intended to be machine-readable.

Specified by:

toString in class CborObject

Parameters:

indentLevel - the indentation level of the string to output. A negative value indicates no newlines or whitespace should be added.

Returns:

a String describing the data item.

See Also:

CBOR Diagnostic Notation, CborObject.toString()