Top Description Fields Constructors Methods
org.osgi.service.dmt

public final Class DmtData

extends Object
Class Inheritance
Imports
java.text.SimpleDateFormat, java.util.Arrays, .Date, .HashMap, .Map, .TimeZone
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.

Author
$Id: 182df9389afa4c4670d16bb5fbf79d69649b8969 $

Field Summary

Modifier and TypeField and Description
public static final DmtData
FALSE_VALUE

Constant instance representing a boolean false value.

private final int
format

public static final int
FORMAT_BASE64

The node holds an OMA DM b64 value.

public static final int
FORMAT_BINARY

The node holds an OMA DM bin value.

public static final int
FORMAT_BOOLEAN

The node holds an OMA DM bool value.

public static final int
FORMAT_DATE

The node holds an OMA DM date value.

public static final int
FORMAT_DATE_TIME

The node holds a Date object.

public static final int
FORMAT_FLOAT

The node holds an OMA DM float value.

public static final int
FORMAT_INTEGER

The node holds an OMA DM int value.

public static final int
FORMAT_LONG

The node holds a long value.

private static final Map<Integer, String>
FORMAT_NAMES

public static final int
FORMAT_NODE

Format specifier of an internal node.

public static final int
FORMAT_NULL

The node holds an OMA DM null value.

public static final int
FORMAT_RAW_BINARY

The node holds raw protocol data encoded in binary format.

public static final int
FORMAT_RAW_STRING

The node holds raw protocol data encoded as String.

public static final int
FORMAT_STRING

The node holds an OMA DM chr value.

public static final int
FORMAT_TIME

The node holds an OMA DM time value.

public static final int
FORMAT_XML

The node holds an OMA DM xml value.

private String
formatName

private static char[]
hex

public static final DmtData
NULL_VALUE

Constant instance representing a leaf node of null format.

public static final DmtData
TRUE_VALUE

Constant instance representing a boolean true value.

private final Object
value

Constructor Summary

AccessConstructor and Description
private
DmtData()

Create a DmtData instance of null format.

public
DmtData(String
the string value to set
string)

Create a DmtData instance of chr format with the given string value.

public
DmtData(Date
the Date object to set
date)

Create a DmtData instance of dateTime format with the given Date value.

public
DmtData(Object
the complex data object to set
complex)

Create a DmtData instance of node format with the given object value.

public
DmtData(String
the string, XML, date, or time value to set
value, int
the format of the DmtData instance to be created, must be one of the formats specified above
format)

Create a DmtData instance of the specified format and set its value based on the given string.

public
DmtData(int
the integer value to set
integer)

Create a DmtData instance of int format and set its value.

public
DmtData(float
the float value to set
flt)

Create a DmtData instance of float format and set its value.

public
DmtData(long
the long value to set
lng)

Create a DmtData instance of long format and set its value.

public
DmtData(boolean
the boolean value to set
bool)

Create a DmtData instance of bool format and set its value.

public
DmtData(byte[]
the byte array to set, must not be null
bytes)

Create a DmtData instance of bin format and set its value.

public
DmtData(byte[]
the byte array to set, must not be null
bytes, boolean
if true, the new instance will have b64 format, if false, it will have bin format
base64)

Create a DmtData instance of bin or b64 format and set its value.

public
DmtData(byte[]
the byte array to set, must not be null
bytes, int
the format of the DmtData instance to be created, must be one of the formats specified above
format)

Create a DmtData instance of the specified format and set its value based on the given byte[].

public
DmtData(String
the name of the format, must not be null
formatName, String
the data encoded according to the specified format, must not be null
data)

Create a DmtData instance in FORMAT_RAW_STRING format.

private
DmtData(Object value, int format, String formatName)

public
DmtData(String
the name of the format, must not be null
formatName, byte[]
the data encoded according to the specified format, must not be null
data)

Create a DmtData instance in FORMAT_RAW_BINARY format.

Method Summary

Modifier and TypeMethod and Description
private static void
appendHexByte(StringBuilder buf, byte b)

private static void
checkDateFormat(String value)

private static int
checkNumber(String value, String name, int from, int length, int min, int max)

private static void
checkTimeFormat(String value)

private byte[]
copyBytes()

public boolean

Returns:

true if the argument represents the same DmtData as this object
equals(Object
the object to compare with this DmtData
obj)

Overrides java.lang.Object.equals.

Compares the specified object with this DmtData instance.

public byte[]

Returns:

the binary value
getBase64()

Gets the value of a node with base 64 (b64) format.

public byte[]

Returns:

the binary value
getBinary()

Gets the value of a node with binary (bin) format.

public boolean

Returns:

the boolean value
getBoolean()

Gets the value of a node with boolean (bool) format.

public String

Returns:

the date value
getDate()

Gets the value of a node with date format.

public Date

Returns:

the Date value
getDateTime()

Gets the value of a node with dateTime format.

public float

Returns:

the float value
getFloat()

Gets the value of a node with float format.

public int

Returns:

the format of the node
getFormat()

Get the node's format, expressed in terms of type constants defined in this class.

public String

Returns:

the format name as String
getFormatName()

Returns the format of this DmtData as String.

private static String
getFormatName(int format)

private static String
getHexDump(byte[] bytes)

public int

Returns:

the integer value
getInt()

Gets the value of a node with integer (int) format.

public long

Returns:

the long value
getLong()

Gets the value of a node with long format.

public Object

Returns:

the data object associated with an interior node
getNode()

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

public byte[]

Returns:

the data value in raw binary format
getRawBinary()

Gets the value of a node in raw binary (FORMAT_RAW_BINARY) format.

public String

Returns:

the data value in raw String format
getRawString()

Gets the value of a node in raw String ( FORMAT_RAW_STRING) format.

public int

Returns:

the size of the data stored by this object
getSize()

Get the size of the data.

public String

Returns:

the string value
getString()

Gets the value of a node with string (chr) format.

public String

Returns:

the time value
getTime()

Gets the value of a node with time format.

public String

Returns:

the XML value
getXml()

Gets the value of a node with xml format.

public int

Returns:

the hash code value for this object
hashCode()

Overrides java.lang.Object.hashCode.

Returns the hash code value for this DmtData instance.

public String

Returns:

the string representation of this DmtData instance
toString()

Overrides java.lang.Object.toString.

Gets the string representation of the DmtData.

private void
validate()

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

FALSE_VALUEback to summary
public static final DmtData FALSE_VALUE

Constant instance representing a boolean false value.

Since
2.0
formatback to summary
private final int format
FORMAT_BASE64back to summary
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.

FORMAT_BINARYback to summary
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.

FORMAT_BOOLEANback to summary
public static final int FORMAT_BOOLEAN

The node holds an OMA DM bool value.

FORMAT_DATEback to summary
public static final int FORMAT_DATE

The node holds an OMA DM date value.

FORMAT_DATE_TIMEback to summary
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
FORMAT_FLOATback to summary
public static final int FORMAT_FLOAT

The node holds an OMA DM float value.

FORMAT_INTEGERback to summary
public static final int FORMAT_INTEGER

The node holds an OMA DM int value.

FORMAT_LONGback to summary
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
FORMAT_NAMESback to summary
private static final Map<Integer, String> FORMAT_NAMES
FORMAT_NODEback to summary
public static final int FORMAT_NODE

Format specifier of an internal node. An interior node can hold a Java object as value (see DmtData#DmtData(Object) and DmtData#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.

FORMAT_NULLback to summary
public static final int FORMAT_NULL

The node holds an OMA DM null value. This corresponds to the Java null type.

FORMAT_RAW_BINARYback to summary
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.

FORMAT_RAW_STRINGback to summary
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.

FORMAT_STRINGback to summary
public static final int FORMAT_STRING

The node holds an OMA DM chr value.

FORMAT_TIMEback to summary
public static final int FORMAT_TIME

The node holds an OMA DM time value.

FORMAT_XMLback to summary
public static final int FORMAT_XML

The node holds an OMA DM xml value.

formatNameback to summary
private String formatName
hexback to summary
private static char[] hex
NULL_VALUEback to summary
public static final DmtData NULL_VALUE

Constant instance representing a leaf node of null format.

TRUE_VALUEback to summary
public static final DmtData TRUE_VALUE

Constant instance representing a boolean true value.

Since
2.0
valueback to summary
private final Object value

Constructor Detail

DmtDataback to summary
private DmtData()

Create a DmtData instance of null format. This constructor is private and used only to create the public NULL_VALUE constant.

DmtDataback to summary
public DmtData(String string)

Create a DmtData instance of chr format with the given string value. The null string argument is valid.

Parameters
string:String

the string value to set

DmtDataback to summary
public DmtData(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:Date

the Date object to set

DmtDataback to summary
public DmtData(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:Object

the complex data object to set

DmtDataback to summary
public DmtData(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:String

the string, XML, date, or time value to set

format:int

the format of the DmtData instance to be created, must be one of the formats specified above

Exceptions
IllegalArgumentException:
if format is not one of the allowed formats, or value is not a valid string for the given format
NullPointerException:
if a string, XML, date, or time is constructed and value is null
DmtDataback to summary
public DmtData(int integer)

Create a DmtData instance of int format and set its value.

Parameters
integer:int

the integer value to set

DmtDataback to summary
public DmtData(float flt)

Create a DmtData instance of float format and set its value.

Parameters
flt:float

the float value to set

DmtDataback to summary
public DmtData(long lng)

Create a DmtData instance of long format and set its value.

Parameters
lng:long

the long value to set

Since
2.0
DmtDataback to summary
public DmtData(boolean bool)

Create a DmtData instance of bool format and set its value.

Parameters
bool:boolean

the boolean value to set

DmtDataback to summary
public DmtData(byte[] bytes)

Create a DmtData instance of bin format and set its value.

Parameters
bytes:byte[]

the byte array to set, must not be null

Exceptions
NullPointerException:
if bytes is null
DmtDataback to summary
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:byte[]

the byte array to set, must not be null

base64:boolean

if true, the new instance will have b64 format, if false, it will have bin format

Exceptions
NullPointerException:
if bytes is null
DmtDataback to summary
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:

Parameters
bytes:byte[]

the byte array to set, must not be null

format:int

the format of the DmtData instance to be created, must be one of the formats specified above

Exceptions
IllegalArgumentException:
if format is not one of the allowed formats
NullPointerException:
if bytes is null
DmtDataback to summary
public DmtData(String formatName, 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:String

the name of the format, must not be null

data:String

the data encoded according to the specified format, must not be null

Exceptions
NullPointerException:
if formatName or data is null
DmtDataback to summary
private DmtData(Object value, int format, String formatName)
DmtDataback to summary
public DmtData(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:String

the name of the format, must not be null

data:byte[]

the data encoded according to the specified format, must not be null

Exceptions
NullPointerException:
if formatName or data is null

Method Detail

appendHexByteback to summary
private static void appendHexByte(StringBuilder buf, byte b)
checkDateFormatback to summary
private static void checkDateFormat(String value)
checkNumberback to summary
private static int checkNumber(String value, String name, int from, int length, int min, int max)
checkTimeFormatback to summary
private static void checkTimeFormat(String value)
copyBytesback to summary
private byte[] copyBytes()
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

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.

Parameters
obj:Object

the object to compare with this DmtData

Returns:boolean

true if the argument represents the same DmtData as this object

Annotations
@Override
getBase64back to summary
public byte[] getBase64()

Gets the value of a node with base 64 (b64) format.

Returns:byte[]

the binary value

Exceptions
DmtIllegalStateException:
if the format of the node is not base 64.
getBinaryback to summary
public byte[] getBinary()

Gets the value of a node with binary (bin) format.

Returns:byte[]

the binary value

Exceptions
DmtIllegalStateException:
if the format of the node is not binary
getBooleanback to summary
public boolean getBoolean()

Gets the value of a node with boolean (bool) format.

Returns:boolean

the boolean value

Exceptions
DmtIllegalStateException:
if the format of the node is not boolean
getDateback to summary
public 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:String

the date value

Exceptions
DmtIllegalStateException:
if the format of the node is not date
getDateTimeback to summary
public Date getDateTime()

Gets the value of a node with dateTime format.

Returns:Date

the Date value

Exceptions
DmtIllegalStateException:
if the format of the node is not time
Since
2.0
getFloatback to summary
public float getFloat()

Gets the value of a node with float format.

Returns:float

the float value

Exceptions
DmtIllegalStateException:
if the format of the node is not float
getFormatback to summary
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:int

the format of the node

getFormatNameback to summary
public 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:String

the format name as String

getFormatNameback to summary
private static String getFormatName(int format)
getHexDumpback to summary
private static String getHexDump(byte[] bytes)
getIntback to summary
public int getInt()

Gets the value of a node with integer (int) format.

Returns:int

the integer value

Exceptions
DmtIllegalStateException:
if the format of the node is not integer
getLongback to summary
public long getLong()

Gets the value of a node with long format.

Returns:long

the long value

Exceptions
DmtIllegalStateException:
if the format of the node is not long
Since
2.0
getNodeback to summary
public 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:Object

the data object associated with an interior node

Exceptions
DmtIllegalStateException:
if the format of the data is not node
getRawBinaryback to summary
public byte[] getRawBinary()

Gets the value of a node in raw binary (FORMAT_RAW_BINARY) format.

Returns:byte[]

the data value in raw binary format

Exceptions
DmtIllegalStateException:
if the format of the node is not raw binary
getRawStringback to summary
public String getRawString()

Gets the value of a node in raw String ( FORMAT_RAW_STRING) format.

Returns:String

the data value in raw String format

Exceptions
DmtIllegalStateException:
if the format of the node is not raw String
getSizeback to summary
public int getSize()

Get the size of the data. The returned value depends on the format of data in the node:

Returns:int

the size of the data stored by this object

getStringback to summary
public String getString()

Gets the value of a node with string (chr) format.

Returns:String

the string value

Exceptions
DmtIllegalStateException:
if the format of the node is not string
getTimeback to summary
public 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:String

the time value

Exceptions
DmtIllegalStateException:
if the format of the node is not time
getXmlback to summary
public String getXml()

Gets the value of a node with xml format.

Returns:String

the XML value

Exceptions
DmtIllegalStateException:
if the format of the node is not xml
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.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.

Returns:int

the hash code value for this object

Annotations
@Override
toStringback to summary
public String toString()

Overrides java.lang.Object.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').

Returns:String

the string representation of this DmtData instance

Annotations
@Override
validateback to summary
private void validate()