com.google.iot.cbor

Class CborArray

java.lang.Object

com.google.iot.cbor.CborObject

com.google.iot.cbor.CborArray

All Implemented Interfaces:

Iterable<CborObject>

public abstract class CborArray
extends CborObject
implements Iterable<CborObject>

Class for representing CBOR array data items.

This class is used to represent data items of major type 4 (CborMajorType.ARRAY).

Method Summary

Modifier and Type	Method and Description
void	add(CborObject cborObject) Appends the given object to this CborArray.
void	clear() Removes all items from this CborArray.
CborArray	copy() Creates an independent, deep copy of this object.
static CborArray	create() Creates an untagged empty CborArray.
static CborArray	create(int tag) Creates a tagged empty CborArray.
static CborArray	create(Iterable<CborObject> objs) Creates an untagged CborArray populated with the given CborObjects.
static CborArray	create(Iterable<CborObject> objs, int tag) Creates a tagged CborArray populated with the given CborObjects.
static CborArray	create(Iterable<CborObject> objs, int tag, boolean isIndefiniteLength) Creates a tagged CborArray populated with the given CborObjects.
static CborArray	createFromJavaObject(boolean[] obj) Converts a boolean array to a CborArray of CborSimple objects.
static CborArray	createFromJavaObject(double[] obj) Converts a double array to a CborArray of CborFloat objects.
static CborArray	createFromJavaObject(float[] obj) Converts a float array to a CborArray of CborFloat objects.
static CborArray	createFromJavaObject(int[] obj) Converts an integer array to a CborArray of CborInteger objects.
static CborArray	createFromJavaObject(Iterable<?> obj) Converts an Iterable of Java objects to an untagged CborArray.
static CborArray	createFromJavaObject(long[] obj) Converts a long array to a CborArray of CborInteger objects.
static CborArray	createFromJavaObject(Object[] obj) Converts an object array to an untagged CborArray.
static CborArray	createFromJavaObject(short[] obj) Converts a short array to a CborArray of CborInteger objects.
static CborArray	createFromJSONArray(org.json.JSONArray jsonArray) Creates a CborArray from a given JSONArray.
boolean	equals(Object obj)
int	getAdditionalInformation() Returns the object's "additional information" value.
int	getMajorType() Always returns CborMajorType.ARRAY.
int	hashCode()
boolean	isEmpty() Determines if this array is empty or not.
abstract boolean	isIndefiniteLength()
boolean	isValidJson() Indicates if this data item can be losslessly converted to a JSON fragment.
@NonNull Iterator<CborObject>	iterator()
abstract List<CborObject>	listValue() Returns the underlying List object backing this CborArray.
boolean	remove(CborObject cborObject) Removes the given object from this CborArray.
int	size() Indicates the number of items in this array.
List<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.
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

createFromCborByteArray, createFromCborByteArray, createFromJavaObject, getTag, toCborByteArray, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

create

public static CborArray create()

Creates an untagged empty CborArray.

Returns:

new CborArray instance

create

public static CborArray create(int tag)

Creates a tagged empty CborArray.

Parameters:

tag - the integer value of the tag

Returns:

new CborArray instance

create

public static CborArray create(Iterable<CborObject> objs)

Creates an untagged CborArray populated with the given CborObjects. The given CborObjects are used directly and not deep-copied.

Parameters:

objs - iterable object (like a Collection)

Returns:

new CborArray instance

create

public static CborArray create(Iterable<CborObject> objs,
                               int tag)

Creates a tagged CborArray populated with the given CborObjects. The given CborObjects are used directly and not deep-copied.

Parameters:

objs - iterable object (like a Collection)

tag - the integer value of the tag

Returns:

new CborArray instance

create

public static CborArray create(Iterable<CborObject> objs,
                               int tag,
                               boolean isIndefiniteLength)

Creates a tagged CborArray populated with the given CborObjects. The given CborObjects are used directly and not deep-copied.

Parameters:

objs - iterable object (like a Collection)

tag - the integer value of the tag

isIndefiniteLength - The array should be serialized as indefinite length

Returns:

new CborArray instance

createFromJavaObject

public static CborArray createFromJavaObject(Iterable<?> obj)
                                      throws CborConversionException

Converts an Iterable of Java objects to an untagged CborArray. Note that this method differs from create(Iterable) in that this method converts standard Java objects (like String, Integer, etc) into CborObjects.

Parameters:

obj - the iterable of java objects to convert

Returns:

new CborArray instance

Throws:

CborConversionException - if one or more of the contained objects cannot be converted

createFromJavaObject

public static CborArray createFromJavaObject(Object[] obj)
                                      throws CborConversionException

Converts an object array to an untagged CborArray.

Parameters:

obj - the object array to convert

Returns:

new CborArray instance

Throws:

CborConversionException - if one or more of the contained objects cannot be converted

createFromJavaObject

public static CborArray createFromJavaObject(int[] obj)

Converts an integer array to a CborArray of CborInteger objects.

Parameters:

obj - the integer array to convert

Returns:

new CborArray instance

createFromJavaObject

public static CborArray createFromJavaObject(short[] obj)

Converts a short array to a CborArray of CborInteger objects.

Parameters:

obj - the short array to convert

Returns:

new CborArray instance

createFromJavaObject

public static CborArray createFromJavaObject(long[] obj)

Converts a long array to a CborArray of CborInteger objects.

Parameters:

obj - the long array to convert

Returns:

new CborArray instance

createFromJavaObject

public static CborArray createFromJavaObject(boolean[] obj)

Converts a boolean array to a CborArray of CborSimple objects.

Parameters:

obj - the boolean array to convert

Returns:

new CborArray instance

createFromJavaObject

public static CborArray createFromJavaObject(float[] obj)

Converts a float array to a CborArray of CborFloat objects.

Parameters:

obj - the float array to convert

Returns:

new CborArray instance

createFromJavaObject

public static CborArray createFromJavaObject(double[] obj)

Converts a double array to a CborArray of CborFloat objects.

Parameters:

obj - the double array to convert

Returns:

new CborArray instance

createFromJSONArray

public static CborArray createFromJSONArray(org.json.JSONArray jsonArray)

Creates a CborArray from a given JSONArray. The resulting CborArray is wholly independent from the given JSONArray.

Returns:

new CborArray instance

listValue

public abstract List<CborObject> listValue()

Returns the underlying List object backing this CborArray.

Returns:

the backing List of CborObject instances.

size

public int size()

Indicates the number of items in this array. This is functionally equivalent to calling listValue().size().

Returns:

the number of items in this array

isEmpty

public boolean isEmpty()

Determines if this array is empty or not. This is functionally equivalent to calling listValue().isEmpty().

Returns:

true if this array is empty, false otherwise

add

public void add(CborObject cborObject)

Appends the given object to this CborArray. This is functionally equivalent to calling listValue().add(cborObject).

Parameters:

cborObject - the object to append

remove

@CanIgnoreReturnValue
public boolean remove(CborObject cborObject)

Removes the given object from this CborArray. This is functionally equivalent to calling listValue().remove(o).

Parameters:

cborObject - the object to remove

Returns:

true if the object was successfully removed, false otherwise

clear

public void clear()

Removes all items from this CborArray. This is functionally equivalent to calling listValue().clear().

getMajorType

public final int getMajorType()

Always returns CborMajorType.ARRAY.

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()

isValidJson

public 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

toJavaObject

public List<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 CborArray copy()

Creates an independent, deep copy of this object.

Specified by:

copy in class CborObject

Returns:

new CborObject

iterator

public @NonNull Iterator<CborObject> iterator()

Specified by:

iterator in interface Iterable<CborObject>

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public final 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()