DmtData
Date: 2016-06-25

org.osgi.service.dmt

## Class DmtData

- java.lang.Object
- - org.osgi.service.dmt.DmtData

-     public final class DmtData
      extends java.lang.Object

  An immutable data structure representing the contents of a leaf or interior node. This structure represents only the value and the format property of the node, all other properties (like MIME type) can be set and read using the `DmtSession` interface.

  Different constructors are available to create nodes with different formats. Nodes of `null` format can be created using the static `NULL_VALUE` constant instance of this class.

  `FORMAT_RAW_BINARY` and `FORMAT_RAW_STRING` enable the support of future data formats. When using these formats, the actual format name is specified as a `String`. The application is responsible for the proper encoding of the data according to the specified format.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static DmtData` | `FALSE_VALUE` Constant instance representing a boolean `false` value.
    `static int` | `FORMAT_BASE64` The node holds an OMA DM `b64` value.
    `static int` | `FORMAT_BINARY` The node holds an OMA DM `bin` value.
    `static int` | `FORMAT_BOOLEAN` The node holds an OMA DM `bool` value.
    `static int` | `FORMAT_DATE` The node holds an OMA DM `date` value.
    `static int` | `FORMAT_DATE_TIME` The node holds a Date object.
    `static int` | `FORMAT_FLOAT` The node holds an OMA DM `float` value.
    `static int` | `FORMAT_INTEGER` The node holds an OMA DM `int` value.
    `static int` | `FORMAT_LONG` The node holds a long value.
    `static int` | `FORMAT_NODE` Format specifier of an internal node.
    `static int` | `FORMAT_NULL` The node holds an OMA DM `null` value.
    `static int` | `FORMAT_RAW_BINARY` The node holds raw protocol data encoded in binary format.
    `static int` | `FORMAT_RAW_STRING` The node holds raw protocol data encoded as `String`.
    `static int` | `FORMAT_STRING` The node holds an OMA DM `chr` value.
    `static int` | `FORMAT_TIME` The node holds an OMA DM `time` value.
    `static int` | `FORMAT_XML` The node holds an OMA DM `xml` value.
    `static DmtData` | `NULL_VALUE` Constant instance representing a leaf node of `null` format.
    `static DmtData` | `TRUE_VALUE` Constant instance representing a boolean `true` value.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DmtData(boolean bool)` Create a `DmtData` instance of `bool` format and set its value.
    `DmtData(byte[] bytes)` Create a `DmtData` instance of `bin` format and set its value.
    `DmtData(byte[] bytes, boolean base64)` Create a `DmtData` instance of `bin` or `b64` format and set its value.
    `DmtData(byte[] bytes, int format)` Create a `DmtData` instance of the specified format and set its value based on the given `byte[]`.
    `DmtData(java.util.Date date)` Create a `DmtData` instance of `dateTime` format with the given Date value.
    `DmtData(float flt)` Create a `DmtData` instance of `float` format and set its value.
    `DmtData(int integer)` Create a `DmtData` instance of `int` format and set its value.
    `DmtData(long lng)` Create a `DmtData` instance of `long` format and set its value.
    `DmtData(java.lang.Object complex)` Create a `DmtData` instance of `node` format with the given object value.
    `DmtData(java.lang.String string)` Create a `DmtData` instance of `chr` format with the given string value.
    `DmtData(java.lang.String formatName, byte[] data)` Create a `DmtData` instance in `FORMAT_RAW_BINARY` format.
    `DmtData(java.lang.String value, int format)` Create a `DmtData` instance of the specified format and set its value based on the given string.
    `DmtData(java.lang.String formatName, java.lang.String data)` Create a `DmtData` instance in `FORMAT_RAW_STRING` format.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(java.lang.Object obj)` Compares the specified object with this `DmtData` instance.
    `byte[]` | `getBase64()` Gets the value of a node with base 64 (`b64`) format.
    `byte[]` | `getBinary()` Gets the value of a node with binary (`bin`) format.
    `boolean` | `getBoolean()` Gets the value of a node with boolean (`bool`) format.
    `java.lang.String` | `getDate()` Gets the value of a node with date format.
    `java.util.Date` | `getDateTime()` Gets the value of a node with `dateTime` format.
    `float` | `getFloat()` Gets the value of a node with `float` format.
    `int` | `getFormat()` Get the node's format, expressed in terms of type constants defined in this class.
    `java.lang.String` | `getFormatName()` Returns the format of this `DmtData` as `String`.
    `int` | `getInt()` Gets the value of a node with integer (`int`) format.
    `long` | `getLong()` Gets the value of a node with long format.
    `java.lang.Object` | `getNode()` Gets the complex data associated with an interior node (`node` format).
    `byte[]` | `getRawBinary()` Gets the value of a node in raw binary (`FORMAT_RAW_BINARY`) format.
    `java.lang.String` | `getRawString()` Gets the value of a node in raw `String` ( `FORMAT_RAW_STRING`) format.
    `int` | `getSize()` Get the size of the data.
    `java.lang.String` | `getString()` Gets the value of a node with string (`chr`) format.
    `java.lang.String` | `getTime()` Gets the value of a node with time format.
    `java.lang.String` | `getXml()` Gets the value of a node with `xml` format.
    `int` | `hashCode()` Returns the hash code value for this `DmtData` instance.
    `java.lang.String` | `toString()` Gets the string representation of the `DmtData`.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### FORMAT_INTEGER

          public static final int FORMAT_INTEGER

      The node holds an OMA DM `int` value.
      See Also:
        Constant Field Values

    - #### FORMAT_FLOAT

          public static final int FORMAT_FLOAT

      The node holds an OMA DM `float` value.
      See Also:
        Constant Field Values

    - #### FORMAT_STRING

          public static final int FORMAT_STRING

      The node holds an OMA DM `chr` value.
      See Also:
        Constant Field Values

    - #### FORMAT_BOOLEAN

          public static final int FORMAT_BOOLEAN

      The node holds an OMA DM `bool` value.
      See Also:
        Constant Field Values

    - #### FORMAT_DATE

          public static final int FORMAT_DATE

      The node holds an OMA DM `date` value.
      See Also:
        Constant Field Values

    - #### FORMAT_TIME

          public static final int FORMAT_TIME

      The node holds an OMA DM `time` value.
      See Also:
        Constant Field Values

    - #### FORMAT_BINARY

          public static final int FORMAT_BINARY

      The node holds an OMA DM `bin` value. The value of the node corresponds to the Java `byte[]` type.
      See Also:
        Constant Field Values

    - #### FORMAT_BASE64

          public static final int FORMAT_BASE64

      The node holds an OMA DM `b64` value. Like `FORMAT_BINARY`, this format is also represented by the Java `byte[]` type, the difference is only in the corresponding OMA DM format. This format does not affect the internal storage format of the data as `byte[]`. It is intended as a hint for the external representation of this data. Protocol Adapters can use this hint for their further processing.
      See Also:
        Constant Field Values

    - #### FORMAT_XML

          public static final int FORMAT_XML

      The node holds an OMA DM `xml` value.
      See Also:
        Constant Field Values

    - #### FORMAT_NULL

          public static final int FORMAT_NULL

      The node holds an OMA DM `null` value. This corresponds to the Java `null` type.
      See Also:
        Constant Field Values

    - #### FORMAT_NODE

          public static final int FORMAT_NODE

      Format specifier of an internal node. An interior node can hold a Java object as value (see `DmtData(Object)` and `getNode()`). This value can be used by Java programs that know a specific URI understands the associated Java type. This type is further used as a return value of the `MetaNode.getFormat()` method for interior nodes.
      See Also:
        Constant Field Values

    - #### FORMAT_RAW_STRING

          public static final int FORMAT_RAW_STRING

      The node holds raw protocol data encoded as `String`. The `getFormatName()` method can be used to get the actual format name.
      See Also:
        Constant Field Values

    - #### FORMAT_RAW_BINARY

          public static final int FORMAT_RAW_BINARY

      The node holds raw protocol data encoded in binary format. The `getFormatName()` method can be used to get the actual format name.
      See Also:
        Constant Field Values

    - #### FORMAT_LONG

          public static final int FORMAT_LONG

      The node holds a long value. The `getFormatName()` method can be used to get the actual format name.
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### FORMAT_DATE_TIME

          public static final int FORMAT_DATE_TIME

      The node holds a Date object. If the getTime() equals zero then the date time is not known. If the getTime() is negative it must be interpreted as a relative number of milliseconds.
      Since:
        2.0
      See Also:
        Constant Field Values

    - #### NULL_VALUE

          public static final DmtData NULL_VALUE

      Constant instance representing a leaf node of `null` format.

    - #### TRUE_VALUE

          public static final DmtData TRUE_VALUE

      Constant instance representing a boolean `true` value.
      Since:
        2.0

    - #### FALSE_VALUE

          public static final DmtData FALSE_VALUE

      Constant instance representing a boolean `false` value.
      Since:
        2.0

  - ### Constructor Detail

    - #### DmtData

          public DmtData(java.lang.String string)

      Create a `DmtData` instance of `chr` format with the given string value. The `null` string argument is valid.
      Parameters:
        `string` - the string value to set

    - #### DmtData

          public DmtData(java.util.Date date)

      Create a `DmtData` instance of `dateTime` format with the given Date value. The given Date value must be a non-null `Date` object.
      Parameters:
        `date` - the Date object to set

    - #### DmtData

          public DmtData(java.lang.Object complex)

      Create a `DmtData` instance of `node` format with the given object value. The value represents complex data associated with an interior node.

      Certain interior nodes can support access to their subtrees through such complex values, making it simpler to retrieve or update all leaf nodes in a subtree.

      The given value must be a non-`null` immutable object.

      Parameters:
        `complex` - the complex data object to set

    - #### DmtData

          public DmtData(java.lang.String value,
                 int format)

      Create a `DmtData` instance of the specified format and set its value based on the given string. Only the following string-based formats can be created using this constructor:
      - `FORMAT_STRING` - value can be any string
      - `FORMAT_XML` - value must contain an XML fragment (the validity is not checked by this constructor)
      - `FORMAT_DATE` - value must be parsable to an ISO 8601 calendar date in complete representation, basic format (pattern `CCYYMMDD`)
      - `FORMAT_TIME` - value must be parsable to an ISO 8601 time of day in either local time, complete representation, basic format (pattern `hhmmss`) or Coordinated Universal Time, basic format (pattern `hhmmssZ`)
      * The `null` string argument is only valid if the format is string or XML.
      Parameters:
        `value` - the string, XML, date, or time value to set
        `format` - the format of the `DmtData` instance to be created, must be one of the formats specified above
      Throws:
        `java.lang.IllegalArgumentException` - if `format` is not one of the allowed formats, or `value` is not a valid string for the given format
        `java.lang.NullPointerException` - if a string, XML, date, or time is constructed and `value` is `null`

    - #### DmtData

          public DmtData(int integer)

      Create a `DmtData` instance of `int` format and set its value.
      Parameters:
        `integer` - the integer value to set

    - #### DmtData

          public DmtData(float flt)

      Create a `DmtData` instance of `float` format and set its value.
      Parameters:
        `flt` - the float value to set

    - #### DmtData

          public DmtData(long lng)

      Create a `DmtData` instance of `long` format and set its value.
      Parameters:
        `lng` - the long value to set
      Since:
        2.0

    - #### DmtData

          public DmtData(boolean bool)

      Create a `DmtData` instance of `bool` format and set its value.
      Parameters:
        `bool` - the boolean value to set

    - #### DmtData

          public DmtData(byte[] bytes)

      Create a `DmtData` instance of `bin` format and set its value.
      Parameters:
        `bytes` - the byte array to set, must not be `null`
      Throws:
        `java.lang.NullPointerException` - if `bytes` is `null`

    - #### DmtData

          public DmtData(byte[] bytes,
                 boolean base64)

      Create a `DmtData` instance of `bin` or `b64` format and set its value. The chosen format is specified by the `base64` parameter.
      Parameters:
        `bytes` - the byte array to set, must not be `null`
        `base64` - if `true`, the new instance will have `b64` format, if `false`, it will have `bin` format
      Throws:
        `java.lang.NullPointerException` - if `bytes` is `null`

    - #### DmtData

          public DmtData(byte[] bytes,
                 int format)

      Create a `DmtData` instance of the specified format and set its value based on the given `byte[]`. Only the following `byte[]` based formats can be created using this constructor:
      - `FORMAT_BINARY`
      - `FORMAT_BASE64`
      Parameters:
        `bytes` - the byte array to set, must not be `null`
        `format` - the format of the DmtData instance to be created, must be one of the formats specified above
      Throws:
        `java.lang.IllegalArgumentException` - if format is not one of the allowed formats
        `java.lang.NullPointerException` - if `bytes` is `null`

    - #### DmtData

          public DmtData(java.lang.String formatName,
                 java.lang.String data)

      Create a `DmtData` instance in `FORMAT_RAW_STRING` format. The data is provided encoded as a `String`. The actual data format is specified in `formatName`. The encoding used in `data` must conform to this format.
      Parameters:
        `formatName` - the name of the format, must not be `null`
        `data` - the data encoded according to the specified format, must not be `null`
      Throws:
        `java.lang.NullPointerException` - if `formatName` or `data` is `null`

    - #### DmtData

          public DmtData(java.lang.String formatName,
                 byte[] data)

      Create a `DmtData` instance in `FORMAT_RAW_BINARY` format. The data is provided encoded as binary. The actual data format is specified in `formatName`. The encoding used in `data` must conform to this format.
      Parameters:
        `formatName` - the name of the format, must not be `null`
        `data` - the data encoded according to the specified format, must not be `null`
      Throws:
        `java.lang.NullPointerException` - if `formatName` or `data` is `null`

  - ### Method Detail

    - #### getString

          public java.lang.String getString()

      Gets the value of a node with string (`chr`) format.
      Returns:
        the string value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not string

    - #### getDate

          public java.lang.String getDate()

      Gets the value of a node with date format. The returned date string is formatted according to the ISO 8601 definition of a calendar date in complete representation, basic format (pattern `CCYYMMDD`).
      Returns:
        the date value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not date

    - #### getTime

          public java.lang.String getTime()

      Gets the value of a node with time format. The returned time string is formatted according to the ISO 8601 definition of the time of day. The exact format depends on the value the object was initialized with: either local time, complete representation, basic format (pattern `hhmmss` ) or Coordinated Universal Time, basic format (pattern `hhmmssZ`).
      Returns:
        the time value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not time

    - #### getDateTime

          public java.util.Date getDateTime()

      Gets the value of a node with `dateTime` format.
      Returns:
        the Date value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not time
      Since:
        2.0

    - #### getXml

          public java.lang.String getXml()

      Gets the value of a node with `xml` format.
      Returns:
        the XML value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not `xml`

    - #### getInt

          public int getInt()

      Gets the value of a node with integer (`int`) format.
      Returns:
        the integer value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not integer

    - #### getLong

          public long getLong()

      Gets the value of a node with long format.
      Returns:
        the long value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not long
      Since:
        2.0

    - #### getFloat

          public float getFloat()

      Gets the value of a node with `float` format.
      Returns:
        the float value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not `float`

    - #### getBoolean

          public boolean getBoolean()

      Gets the value of a node with boolean (`bool`) format.
      Returns:
        the boolean value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not boolean

    - #### getBinary

          public byte[] getBinary()

      Gets the value of a node with binary (`bin`) format.
      Returns:
        the binary value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not binary

    - #### getRawBinary

          public byte[] getRawBinary()

      Gets the value of a node in raw binary (`FORMAT_RAW_BINARY`) format.
      Returns:
        the data value in raw binary format
      Throws:
        `DmtIllegalStateException` - if the format of the node is not raw binary

    - #### getRawString

          public java.lang.String getRawString()

      Gets the value of a node in raw `String` ( `FORMAT_RAW_STRING`) format.
      Returns:
        the data value in raw `String` format
      Throws:
        `DmtIllegalStateException` - if the format of the node is not raw `String`

    - #### getBase64

          public byte[] getBase64()

      Gets the value of a node with base 64 (`b64`) format.
      Returns:
        the binary value
      Throws:
        `DmtIllegalStateException` - if the format of the node is not base 64.

    - #### getNode

          public java.lang.Object getNode()

      Gets the complex data associated with an interior node (`node` format).

      Certain interior nodes can support access to their subtrees through complex values, making it simpler to retrieve or update all leaf nodes in the subtree.

      Returns:
        the data object associated with an interior node
      Throws:
        `DmtIllegalStateException` - if the format of the data is not `node`

    - #### getFormat

          public int getFormat()

      Get the node's format, expressed in terms of type constants defined in this class. Note that the 'format' term is a legacy from OMA DM, it is more customary to think of this as 'type'.
      Returns:
        the format of the node

    - #### getFormatName

          public java.lang.String getFormatName()

      Returns the format of this `DmtData` as `String`. For the predefined data formats this is the OMA DM defined name of the format. For `FORMAT_RAW_STRING` and `FORMAT_RAW_BINARY` this is the format specified when the object was created.
      Returns:
        the format name as `String`

    - #### getSize

          public int getSize()

      Get the size of the data. The returned value depends on the format of data in the node:
      - `FORMAT_STRING`, `FORMAT_XML`, `FORMAT_BINARY`, `FORMAT_BASE64`, `FORMAT_RAW_STRING`, and `FORMAT_RAW_BINARY`: the length of the stored data, or 0 if the data is `null`
      - `FORMAT_INTEGER` and `FORMAT_FLOAT`: 4
      - `FORMAT_LONG` and `FORMAT_DATE_TIME`: 8
      - `FORMAT_DATE` and `FORMAT_TIME`: the length of the date or time in its string representation
      - `FORMAT_BOOLEAN`: 1
      - `FORMAT_NODE`: -1 (unknown)
      - `FORMAT_NULL`: 0
      Returns:
        the size of the data stored by this object

    - #### toString

          public java.lang.String toString()

      Gets the string representation of the `DmtData`. This method works for all formats.

      For string format data - including `FORMAT_RAW_STRING` - the string value itself is returned, while for XML, date, time, integer, float, boolean, long and node formats the string form of the value is returned. Binary - including `FORMAT_RAW_BINARY` - base64 data is represented by two-digit hexadecimal numbers for each byte separated by spaces. The `NULL_VALUE` data has the string form of " `null`". Data of string or XML format containing the Java `null` value is represented by an empty string. DateTime data is formatted as `yyyy-MM-dd'T'HH:mm:SS'Z'`).

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the string representation of this `DmtData` instance

    - #### equals

          public boolean equals(java.lang.Object obj)

      Compares the specified object with this `DmtData` instance. Two `DmtData` objects are considered equal if their format is the same, and their data (selected by the format) is equal.

      In case of `FORMAT_RAW_BINARY` and `FORMAT_RAW_STRING` the textual name of the data format - as returned by `getFormatName()` - must be equal as well.

      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `obj` - the object to compare with this `DmtData`
      Returns:
        true if the argument represents the same `DmtData` as this object

    - #### hashCode

          public int hashCode()

      Returns the hash code value for this `DmtData` instance. The hash code is calculated based on the data (selected by the format) of this object.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code value for this object