Class DittoCborSerializable

java.lang.Object
com.ditto.java.serialization.DittoCborSerializable
Direct Known Subclasses:
DittoCborSerializable.Array, DittoCborSerializable.BooleanValue, DittoCborSerializable.ByteString, DittoCborSerializable.Dictionary, DittoCborSerializable.DoubleValue, DittoCborSerializable.FloatValue, DittoCborSerializable.NegativeInteger, DittoCborSerializable.NullValue, DittoCborSerializable.Tagged, DittoCborSerializable.UnsignedInteger, DittoCborSerializable.Utf8String
public abstract sealed class DittoCborSerializable extends Object permits DittoCborSerializable.UnsignedInteger, DittoCborSerializable.NegativeInteger, DittoCborSerializable.ByteString, DittoCborSerializable.Utf8String, DittoCborSerializable.Array, DittoCborSerializable.Dictionary, DittoCborSerializable.Tagged, DittoCborSerializable.BooleanValue, DittoCborSerializable.NullValue, DittoCborSerializable.FloatValue, DittoCborSerializable.DoubleValue

Represents a value that can be serialized to CBOR format.

CBOR (Concise Binary Object Representation) is a data format used by Ditto for efficient serialization of document data. This class provides methods for creating and manipulating CBOR-serializable values and using them to interact with Ditto APIs.

Values can be created using the static factory methods:

- [#of(String)] - for standard Java types
- [#buildArray()] - for creating CBOR arrays
- [#buildDictionary()] - for creating CBOR dictionaries
- [#nullValue()] - for null values

Values can be converted back to Java types using the various as* methods, such as asString(), asInt(), asDictionary(), etc.

  • Constructor Details

    • DittoCborSerializable

      protected DittoCborSerializable(@NonNull com.ditto.internal.serialization.InternalDittoCborSerializable implementation)
      Protected constructor for internal use.
      Parameters:
      implementation - the internal CBOR serializable implementation.

  • Method Details

    • getImplementation

      protected @NonNull com.ditto.internal.serialization.InternalDittoCborSerializable getImplementation()
      Returns the internal CBOR serializable implementation.
      Returns:
      the internal implementation.

    • isNull

      public boolean isNull()
      Checks if this value represents null.
      Returns:
      true if this is a null value, false otherwise.

    • asAttachmentToken

      public @NonNull DittoAttachmentToken asAttachmentToken() throws DittoException
      Converts this value to a DittoAttachmentToken.
      Returns:
      the attachment token.
      Throws:
      DittoException - if this value is not an attachment token.

    • asAttachmentTokenOrNull

      public @Nullable DittoAttachmentToken asAttachmentTokenOrNull()
      Converts this value to a DittoAttachmentToken, or returns null if conversion fails.
      Returns:
      the attachment token, or null if this value cannot be converted.

    • asBoolean

      public boolean asBoolean() throws DittoException
      Converts this value to a boolean.
      Returns:
      the boolean value.
      Throws:
      DittoException - if this value is not a boolean.

    • asBooleanOrNull

      public @Nullable Boolean asBooleanOrNull()
      Converts this value to a boolean, or returns null if conversion fails.
      Returns:
      the boolean value, or null if this value cannot be converted.

    • asNullableBoolean

      public @Nullable Boolean asNullableBoolean() throws DittoException
      Converts this value to a nullable boolean.
      Returns:
      the boolean value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a boolean nor a CBOR null.

    • asByte

      public byte asByte() throws DittoException
      Converts this value to a byte.
      Returns:
      the byte value.
      Throws:
      DittoException - if this value is not a byte.

    • asByteOrNull

      public @Nullable Byte asByteOrNull()
      Converts this value to a byte, or returns null if conversion fails.
      Returns:
      the byte value, or null if this value cannot be converted.

    • asNullableByte

      public @Nullable Byte asNullableByte() throws DittoException
      Converts this value to a nullable byte.
      Returns:
      the byte value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a byte nor a CBOR null.

    • asUnsignedByte

      public int asUnsignedByte() throws DittoException
      Converts this value to an unsigned byte as an int (range 0-255).
      Returns:
      the unsigned byte value as an int.
      Throws:
      DittoException - if this value is not an unsigned byte.

    • asUnsignedByteOrNull

      public @Nullable Integer asUnsignedByteOrNull()
      Converts this value to an unsigned byte as an int, or returns null if conversion fails.
      Returns:
      the unsigned byte value as an int, or null if this value cannot be converted.

    • asNullableUnsignedByte

      public @Nullable Integer asNullableUnsignedByte() throws DittoException
      Converts this value to a nullable unsigned byte as an int.
      Returns:
      the unsigned byte value as an int, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither an unsigned byte nor a CBOR null.

    • asShort

      public short asShort() throws DittoException
      Converts this value to a short.
      Returns:
      the short value.
      Throws:
      DittoException - if this value is not a short.

    • asShortOrNull

      public @Nullable Short asShortOrNull()
      Converts this value to a short, or returns null if conversion fails.
      Returns:
      the short value, or null if this value cannot be converted.

    • asNullableShort

      public @Nullable Short asNullableShort() throws DittoException
      Converts this value to a nullable short.
      Returns:
      the short value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a short nor a CBOR null.

    • asUnsignedShort

      public int asUnsignedShort() throws DittoException
      Converts this value to an unsigned short as an int (range 0-65535).
      Returns:
      the unsigned short value as an int.
      Throws:
      DittoException - if this value is not an unsigned short.

    • asUnsignedShortOrNull

      public @Nullable Integer asUnsignedShortOrNull()
      Converts this value to an unsigned short as an int, or returns null if conversion fails.
      Returns:
      the unsigned short value as an int, or null if this value cannot be converted.

    • asNullableUnsignedShort

      public @Nullable Integer asNullableUnsignedShort() throws DittoException
      Converts this value to a nullable unsigned short as an int.
      Returns:
      the unsigned short value as an int, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither an unsigned short nor a CBOR null.

    • asInt

      public int asInt() throws DittoException
      Converts this value to an int.
      Returns:
      the int value.
      Throws:
      DittoException - if this value is not an int.

    • asIntOrNull

      public @Nullable Integer asIntOrNull()
      Converts this value to an int, or returns null if conversion fails.
      Returns:
      the int value, or null if this value cannot be converted.

    • asNullableInt

      public @Nullable Integer asNullableInt() throws DittoException
      Converts this value to a nullable int.
      Returns:
      the int value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither an int nor a CBOR null.

    • asUnsignedInt

      public long asUnsignedInt() throws DittoException
      Converts this value to an unsigned int as a long.
      Returns:
      the unsigned int value as a long.
      Throws:
      DittoException - if this value is not an unsigned int.

    • asUnsignedIntOrNull

      public @Nullable Long asUnsignedIntOrNull()
      Converts this value to an unsigned int as a long, or returns null if conversion fails.
      Returns:
      the unsigned int value as a long, or null if this value cannot be converted.

    • asNullableUnsignedInt

      public @Nullable Long asNullableUnsignedInt() throws DittoException
      Converts this value to a nullable unsigned int as a long.
      Returns:
      the unsigned int value as a long, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither an unsigned int nor a CBOR null.

    • asLong

      public long asLong() throws DittoException
      Converts this value to a long.
      Returns:
      the long value.
      Throws:
      DittoException - if this value is not a long.

    • asLongOrNull

      public @Nullable Long asLongOrNull()
      Converts this value to a long, or returns null if conversion fails.
      Returns:
      the long value, or null if this value cannot be converted.

    • asNullableLong

      public @Nullable Long asNullableLong() throws DittoException
      Converts this value to a nullable long.
      Returns:
      the long value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a long nor a CBOR null.

    • asUnsignedLong

      public @NonNull DittoULong asUnsignedLong() throws DittoException
      Converts this value to an unsigned long as a DittoULong.
      Returns:
      the unsigned long value.
      Throws:
      DittoException - if this value is not an unsigned long.

    • asUnsignedLongOrNull

      public @Nullable DittoULong asUnsignedLongOrNull()
      Converts this value to an unsigned long, or returns null if conversion fails.
      Returns:
      the unsigned long value, or null if this value cannot be converted.

    • asNullableUnsignedLong

      public @Nullable DittoULong asNullableUnsignedLong() throws DittoException
      Converts this value to a nullable unsigned long.
      Returns:
      the unsigned long value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither an unsigned long nor a CBOR null.

    • asBigInteger

      public @NonNull BigInteger asBigInteger() throws DittoException
      Converts this value to a BigInteger.
      Returns:
      the BigInteger value.
      Throws:
      DittoException - if this value is not a BigInteger.

    • asBigIntegerOrNull

      public @Nullable BigInteger asBigIntegerOrNull()
      Converts this value to a BigInteger, or returns null if conversion fails.
      Returns:
      the BigInteger value, or null if this value cannot be converted.

    • asNullableBigInteger

      public @Nullable BigInteger asNullableBigInteger() throws DittoException
      Converts this value to a nullable BigInteger.
      Returns:
      the BigInteger value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a BigInteger nor a CBOR null.

    • asFloat

      public float asFloat() throws DittoException
      Converts this value to a float.
      Returns:
      the float value.
      Throws:
      DittoException - if this value is not a float.

    • asFloatOrNull

      public @Nullable Float asFloatOrNull()
      Converts this value to a float, or returns null if conversion fails.
      Returns:
      the float value, or null if this value cannot be converted.

    • asNullableFloat

      public @Nullable Float asNullableFloat() throws DittoException
      Converts this value to a nullable float.
      Returns:
      the float value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a float nor a CBOR null.

    • asDouble

      public double asDouble() throws DittoException
      Converts this value to a double.
      Returns:
      the double value.
      Throws:
      DittoException - if this value is not a double.

    • asDoubleOrNull

      public @Nullable Double asDoubleOrNull()
      Converts this value to a double, or returns null if conversion fails.
      Returns:
      the double value, or null if this value cannot be converted.

    • asNullableDouble

      public @Nullable Double asNullableDouble() throws DittoException
      Converts this value to a nullable double.
      Returns:
      the double value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a double nor a CBOR null.

    • asString

      public @NonNull String asString() throws DittoException
      Converts this value to a String.
      Returns:
      the string value.
      Throws:
      DittoException - if this value is not a string.

    • asStringOrNull

      public @Nullable String asStringOrNull()
      Converts this value to a String, or returns null if conversion fails.
      Returns:
      the string value, or null if this value cannot be converted.

    • asNullableString

      public @Nullable String asNullableString() throws DittoException
      Converts this value to a nullable String.
      Returns:
      the string value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a string nor a CBOR null.

    • asDictionary

      public @NonNull DittoCborSerializable.Dictionary asDictionary() throws DittoException
      Converts this value to a DittoCborSerializable.Dictionary.
      Returns:
      the dictionary value.
      Throws:
      DittoException - if this value is not a dictionary.

    • asDictionaryOrNull

      public @Nullable DittoCborSerializable.Dictionary asDictionaryOrNull()
      Converts this value to a DittoCborSerializable.Dictionary, or returns null if conversion fails.
      Returns:
      the dictionary value, or null if this value cannot be converted.

    • asNullableDictionary

      public @Nullable DittoCborSerializable.Dictionary asNullableDictionary() throws DittoException
      Converts this value to a nullable DittoCborSerializable.Dictionary.
      Returns:
      the dictionary value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a dictionary nor a CBOR null.

    • asList

      public @NonNull DittoCborSerializable.Array asList() throws DittoException
      Converts this value to an DittoCborSerializable.Array.
      Returns:
      the array value.
      Throws:
      DittoException - if this value is not an array.

    • asListOrNull

      public @Nullable DittoCborSerializable.Array asListOrNull()
      Converts this value to an DittoCborSerializable.Array, or returns null if conversion fails.
      Returns:
      the array value, or null if this value cannot be converted.

    • asNullableList

      public @Nullable DittoCborSerializable.Array asNullableList() throws DittoException
      Converts this value to a nullable DittoCborSerializable.Array.
      Returns:
      the array value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither an array nor a CBOR null.

    • asTagged

      public @NonNull DittoCborSerializable.Tagged asTagged() throws DittoException
      Converts this value to a DittoCborSerializable.Tagged CBOR value.
      Returns:
      the tagged value.
      Throws:
      DittoException - if this value is not a tagged value.

    • asTaggedOrNull

      public @Nullable DittoCborSerializable.Tagged asTaggedOrNull()
      Converts this value to a DittoCborSerializable.Tagged CBOR value, or returns null if conversion fails.
      Returns:
      the tagged value, or null if this value cannot be converted.

    • asNullableTagged

      public @Nullable DittoCborSerializable.Tagged asNullableTagged() throws DittoException
      Converts this value to a nullable DittoCborSerializable.Tagged CBOR value.
      Returns:
      the tagged value, or null if this value is a CBOR null.
      Throws:
      DittoException - if this value is neither a tagged value nor a CBOR null.

    • get

      public @NonNull DittoCborSerializable get(int index)
      Gets the value at the specified index if this is an array.
      Parameters:
      index - the array index.
      Returns:
      the value at the specified index.

    • get

      public @NonNull DittoCborSerializable get(@NonNull String key)
      Gets the value for the specified key if this is a dictionary.
      Parameters:
      key - the dictionary key.
      Returns:
      the value for the specified key.

    • get

      public @NonNull DittoCborSerializable get(@NonNull DittoCborSerializable key)
      Gets the value for the specified CBOR key if this is a dictionary.
      Parameters:
      key - the dictionary key as a CBOR-serializable value.
      Returns:
      the value for the specified key.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public final boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • of

      public static @NonNull DittoCborSerializable.Utf8String of(@NonNull String value)
      Creates a CBOR-serializable value from a string.
      Parameters:
      value - the string value.
      Returns:
      a DittoCborSerializable.Utf8String containing the value.

    • of

      public static @NonNull DittoCborSerializable.ByteString of(byte @NonNull [] value)
      Creates a CBOR-serializable value from a byte array.
      Parameters:
      value - the byte array value.
      Returns:
      a DittoCborSerializable.ByteString containing the value.

    • of

      public static @NonNull DittoCborSerializable.BooleanValue of(boolean value)
      Creates a CBOR-serializable value from a boolean.
      Parameters:
      value - the boolean value.
      Returns:
      a DittoCborSerializable.BooleanValue containing the value.

    • of

      public static @NonNull DittoCborSerializable.DoubleValue of(double value)
      Creates a CBOR-serializable value from a double.
      Parameters:
      value - the double value.
      Returns:
      a DittoCborSerializable.DoubleValue containing the value.

    • of

      public static @NonNull DittoCborSerializable.FloatValue of(float value)
      Creates a CBOR-serializable value from a float.
      Parameters:
      value - the float value.
      Returns:
      a DittoCborSerializable.FloatValue containing the value.

    • of

      public static @NonNull DittoCborSerializable of(byte value)
      Creates a CBOR-serializable value from a byte.
      Parameters:
      value - the byte value.
      Returns:
      a CBOR-serializable value containing the byte.

    • of

      public static @NonNull DittoCborSerializable of(short value)
      Creates a CBOR-serializable value from a short.
      Parameters:
      value - the short value.
      Returns:
      a CBOR-serializable value containing the short.

    • of

      public static @NonNull DittoCborSerializable of(int value)
      Creates a CBOR-serializable value from an int.
      Parameters:
      value - the int value.
      Returns:
      a CBOR-serializable value containing the int.

    • of

      public static @NonNull DittoCborSerializable of(long value)
      Creates a CBOR-serializable value from a long.
      Parameters:
      value - the long value.
      Returns:
      a CBOR-serializable value containing the long.

    • of

      public static @NonNull DittoCborSerializable of(@NonNull BigInteger value)
      Creates a CBOR-serializable value from a BigInteger.
      Parameters:
      value - the BigInteger value.
      Returns:
      a CBOR-serializable value containing the BigInteger.

    • tagged

      public static @NonNull DittoCborSerializable.Tagged tagged(long tag, DittoCborSerializable value)

      Creates a tagged CBOR value.

      CBOR tags are used to associate semantic information with CBOR data items.

      Parameters:
      tag - the numeric tag identifier.
      value - the CBOR value to tag.
      Returns:
      a DittoCborSerializable.Tagged CBOR value.

    • nullValue

      public static @NonNull DittoCborSerializable.NullValue nullValue()
      Returns a CBOR null value.
      Returns:
      the singleton DittoCborSerializable.NullValue instance.

    • buildArray

      public static @NonNull DittoCborSerializable.Array.Builder buildArray()
      Creates a new builder for constructing a CBOR array.
      Returns:
      a new DittoCborSerializable.Array.Builder instance.

    • buildDictionary

      public static @NonNull DittoCborSerializable.Dictionary.Builder buildDictionary()
      Creates a new builder for constructing a CBOR dictionary.
      Returns:
      a new DittoCborSerializable.Dictionary.Builder instance.