com.google.iot.cbor

Class CborObject

java.lang.Object

com.google.iot.cbor.CborObject

Direct Known Subclasses:

CborArray, CborByteString, CborFloat, CborInteger, CborMap, CborSimple, CborTextString

public abstract class CborObject
extends Object

Base class for CBOR data items.

See Also:

CborArray, CborFloat, CborInteger, CborNumber, CborMap, CborByteString, CborSimple, CborTextString, RFC7049

Method Summary

Modifier and Type	Method and Description
abstract CborObject	copy() Creates an independent, deep copy of this data item.
static CborObject	createFromCborByteArray(byte[] input) Creates a new CborObject from a CBOR-encoded byte array.
static CborObject	createFromCborByteArray(byte[] input, int offset, int length) Creates a new CborObject from a CBOR-encoded byte array starting at a given offset.
static CborObject	createFromJavaObject(@Nullable Object obj) Creates a new CborObject based on the given Java object.
abstract int	getAdditionalInformation() Returns the object's "additional information" value.
abstract int	getMajorType() Returns the object's "Major Type", as defined by RFC7049.
int	getTag() Returns the tag for this object.
abstract boolean	isValidJson() Indicates if this data item can be losslessly converted to a JSON fragment.
byte[]	toCborByteArray() Convenience method to quickly obtaining a CBOR byte-encoding of this data item.
abstract @Nullable Object	toJavaObject() Converts the given data item into a standard java object representation.
abstract <T> T	toJavaObject(Class<T> clazz) Attempts to convert this data item to a java object with a specific class.
abstract String	toJsonString() Returns a representation of this data item as JSON text.
String	toString() Describes this data item using CBOR diagnostic notation.
abstract String	toString(int indentLevel) Describes this data item using CBOR diagnostic notation at the given indentation level.

Methods inherited from class java.lang.Object

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

Method Detail

createFromCborByteArray

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

Creates a new CborObject from a CBOR-encoded byte array starting at a given offset.

Provided as convenient alternative to using CborReader.

Parameters:

input - byte array to parse

offset - index of first byte to start parsing

length - the number of bytes to parse

Returns:

finished CborObject.

Throws:

CborParseException - if the input data could not be parsed correctly or if there was extra data present at the end of input

IndexOutOfBoundsException - if offset is out of bounds

See Also:

createFromCborByteArray(byte[]), CborReader

createFromCborByteArray

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

Creates a new CborObject from a CBOR-encoded byte array.

Provided as convenient alternative to using CborReader.

Parameters:

input - byte array to parse

Returns:

finished CborObject.

Throws:

CborParseException - if the input data could not be parsed correctly

See Also:

createFromCborByteArray(byte[], int, int), CborReader

createFromJavaObject

public static CborObject createFromJavaObject(@Nullable Object obj)
                                       throws CborConversionException

Creates a new CborObject based on the given Java object. Supported Java class types include:

• null → CborSimple.NULL
• Float/Double → CborFloat
• Integer/Long/Short → CborInteger
• String → CborTextString
• Boolean → CborSimple.TRUE/CborSimple.FALSE
• Map → CborMap
• Iterable → CborArray
• URI → CborTag.URI + CborTextString
• BigInteger → CborTag.BIGNUM_POS/CborTag.BIGNUM_NEG + CborByteString
• byte[] → CborByteString
• int[]/short[]/long[] → CborArray
• float[]/double[] → CborArray
• String[] → CborArray

Parameters:

obj - the Java object to convert. May be null.

Returns:

the constructed CborObject representing obj

Throws:

CborConversionException - if the object cannot be converted

See Also:

toJavaObject()

getTag

public int getTag()

Returns the tag for this object.

If the object is not tagged, returns CborTag.UNTAGGED.

Returns:

a number identifying the tag for this object, or CborTag.UNTAGGED if untagged.

See Also:

CborTag

getMajorType

public abstract int getMajorType()

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

See Also:

CborMajorType, getAdditionalInformation()

getAdditionalInformation

public abstract int getAdditionalInformation()

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.

See Also:

getMajorType()

isValidJson

public abstract boolean isValidJson()

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 toJsonString() will strip out tags anyway.

Returns:

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

toJsonString

public abstract String toJsonString()

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

Returns:

a String containing representation of this data item as JSON text

See Also:

isValidJson(), RFC8259

toJavaObject

public abstract @Nullable Object toJavaObject()

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.

See Also:

createFromJavaObject(Object)

toJavaObject

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

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

Unlike 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

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 abstract CborObject copy()

Creates an independent, deep copy of this data item. If the object that is being copied is immutable, this method may simple return a reference to the object.

Returns:

new CborObject

toCborByteArray

public final byte[] toCborByteArray()

Convenience method to quickly obtaining a CBOR byte-encoding of this data item.

Depending on your needs it may be more appropriate to directly use CborWriter, which allows for the use of OutputStream and ByteBuffer objects.

See Also:

CborWriter

toString

public String toString()

Describes this data item using CBOR diagnostic notation.

No additional whitespace is added for readability.

The output is similar to that of 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.

Overrides:

toString in class Object

Returns:

a String describing the data item.

See Also:

CBOR Diagnostic Notation, toString(int)

toString

public abstract String toString(int indentLevel)

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

The output is similar to that of 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.

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