javax.bluetooth
Class DataElement

java.lang.Object
  extended by javax.bluetooth.DataElement

public class DataElement
extends Object

The DataElement class defines the various data types that a Bluetooth service attribute value may have. The following table describes the data types and valid values that a DataElement object can store.

Data TypeValid Values
NULLrepresents a null value
U_INT_1 long value range [0, 255]
U_INT_2long value range [0, 216-1]
U_INT_4 long value range [0, 232-1]
U_INT_8 byte[] value range [0, 264-1]
U_INT_16 byte[] value range [0, 2128-1]
INT_1long value range [-128, 127]
INT_2long value range [-215, 215-1]
INT_4long value range [-231, 231-1]
INT_8long value range [-263, 263-1]
INT_16byte[] value range [-2127, 2127-1]
URL java.lang.String
UUID javax.bluetooth.UUID
BOOLboolean
STRING java.lang.String
DATSEQ java.util.Enumeration
DATALT java.util.Enumeration

Since:
BlackBerry API 4.2.1

Field Summary
static int BOOL
          Defines data of type BOOL.
static int DATALT
          Defines data of type DATALT.
static int DATSEQ
          Defines data of type DATSEQ.
static int INT_1
          Defines a signed integer of size one byte.
static int INT_16
          Defines a signed integer of size sixteen bytes.
static int INT_2
          Defines a signed integer of size two bytes.
static int INT_4
          Defines a signed integer of size four bytes.
static int INT_8
          Defines a signed integer of size eight bytes.
static int NULL
          Defines data of type NULL.
static int STRING
          Defines data of type STRING.
static int URL
          Defines data of type URL.
static int UUID
          Defines data of type UUID.
static int U_INT_1
          Defines an unsigned integer of size one byte.
static int U_INT_16
          Defines an unsigned integer of size sixteen bytes.
static int U_INT_2
          Defines an unsigned integer of size two bytes.
static int U_INT_4
          Defines an unsigned integer of size four bytes.
static int U_INT_8
          Defines an unsigned integer of size eight bytes.
 
Constructor Summary
DataElement(boolean bool)
          Creates a DataElement whose data type is BOOL and whose value is equal to bool
DataElement(int valueType)
          Creates a DataElement of type NULL, DATALT, or DATSEQ.
DataElement(int valueType, Object value)
          Creates a DataElement whose data type is given by valueType and whose value is specified by the argument value.
DataElement(int valueType, long value)
          Creates a DataElement that encapsulates an integer value of size U_INT_1, U_INT_2, U_INT_4, INT_1, INT_2, INT_4, and INT_8.
 
Method Summary
 void addElement(DataElement elem)
          Adds a DataElement to this DATALT or DATSEQ DataElement object.
 boolean getBoolean()
          Returns the value of the DataElement if it is represented as a boolean.
 int getDataType()
          Returns the data type of the object this DataElement represents.
 long getLong()
          Returns the value of the DataElement if it can be represented as a long.
 int getSize()
          Returns the number of DataElements that are present in this DATALT or DATSEQ object.
 Object getValue()
          Returns the value of this DataElement as an Object.
 void insertElementAt(DataElement elem, int index)
          Inserts a DataElement at the specified location.
 boolean removeElement(DataElement elem)
          Removes the first occurrence of the DataElement from this object.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

NULL

public static final int NULL
Defines data of type NULL. The value for data type DataElement.NULL is implicit, i.e., there is no representation of it. Accordingly there is no method to retrieve it, and attempts to retrieve the value will throw an exception.

The value of NULL is 0x00 (0).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

U_INT_1

public static final int U_INT_1
Defines an unsigned integer of size one byte.

The value of the constant U_INT_1 is 0x08 (8).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

U_INT_2

public static final int U_INT_2
Defines an unsigned integer of size two bytes.

The value of the constant U_INT_2 is 0x09 (9).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

U_INT_4

public static final int U_INT_4
Defines an unsigned integer of size four bytes.

The value of the constant U_INT_4 is 0x0A (10).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

U_INT_8

public static final int U_INT_8
Defines an unsigned integer of size eight bytes.

The value of the constant U_INT_8 is 0x0B (11).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

U_INT_16

public static final int U_INT_16
Defines an unsigned integer of size sixteen bytes.

The value of the constant U_INT_16 is 0x0C (12).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

INT_1

public static final int INT_1
Defines a signed integer of size one byte.

The value of the constant INT_1 is 0x10 (16).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

INT_2

public static final int INT_2
Defines a signed integer of size two bytes.

The value of the constant INT_2 is 0x11 (17).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

INT_4

public static final int INT_4
Defines a signed integer of size four bytes.

The value of the constant INT_4 is 0x12 (18).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

INT_8

public static final int INT_8
Defines a signed integer of size eight bytes.

The value of the constant INT_8 is 0x13 (19).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

INT_16

public static final int INT_16
Defines a signed integer of size sixteen bytes.

The value of the constant INT_16 is 0x14 (20).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

URL

public static final int URL
Defines data of type URL.

The value of the constant URL is 0x40 (64).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

UUID

public static final int UUID
Defines data of type UUID.

The value of the constant UUID is 0x18 (24).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

BOOL

public static final int BOOL
Defines data of type BOOL.

The value of the constant BOOL is 0x28 (40).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

STRING

public static final int STRING
Defines data of type STRING.

The value of the constant STRING is 0x20 (32).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

DATSEQ

public static final int DATSEQ
Defines data of type DATSEQ. The service attribute value whose data has this type must consider all the elements of the list, i.e. the value is the whole set and not a subset. The elements of the set can be of any type defined in this class, including DATSEQ.

The value of the constant DATSEQ is 0x30 (48).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

DATALT

public static final int DATALT
Defines data of type DATALT. The service attribute value whose data has this type must consider only one of the elements of the set, i.e., the value is the not the whole set but only one element of the set. The user is free to choose any one element. The elements of the set can be of any type defined in this class, including DATALT.

The value of the constant DATALT is 0x38 (56).

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1


Constructor Detail

DataElement

public DataElement(int valueType)
Creates a DataElement of type NULL, DATALT, or DATSEQ.

Parameters:
valueType - the type of DataElement to create: NULL, DATALT, or DATSEQ
Throws:
IllegalArgumentException - if valueType is not NULL, DATALT, or DATSEQ
See Also:
DataElement.NULL, DataElement.DATALT, DataElement.DATSEQ
Since:
BlackBerry API 4.2.1

DataElement

public DataElement(boolean bool)
Creates a DataElement whose data type is BOOL and whose value is equal to bool

Parameters:
bool - the value of the DataElement of type BOOL.
See Also:
DataElement.BOOL
Since:
BlackBerry API 4.2.1

DataElement

public DataElement(int valueType,
                   long value)
Creates a DataElement that encapsulates an integer value of size U_INT_1, U_INT_2, U_INT_4, INT_1, INT_2, INT_4, and INT_8. The legal values for the valueType and the corresponding attribute values are:
Value TypeValue Range
U_INT_1 [0, 28-1]
U_INT_2 [0, 216-1]
U_INT_4 [0, 232-1]
INT_1 [-27, 27-1]
INT_2 [-215, 215-1]
INT_4 [-231, 231-1]
INT_8 [-263, 263-1]
All other pairings are illegal and will cause an IllegalArgumentException to be thrown.

Parameters:
valueType - the data type of the object that is being created; must be one of the following: U_INT_1, U_INT_2, U_INT_4, INT_1, INT_2, INT_4, or INT_8
value - the value of the object being created; must be in the range specified for the given valueType
Throws:
IllegalArgumentException - if the valueType is not valid or the value for the given legal valueType is outside the valid range
See Also:
DataElement.U_INT_1, DataElement.U_INT_2, DataElement.U_INT_4, DataElement.INT_1, DataElement.INT_2, DataElement.INT_4, DataElement.INT_8
Since:
BlackBerry API 4.2.1

DataElement

public DataElement(int valueType,
                   Object value)
Creates a DataElement whose data type is given by valueType and whose value is specified by the argument value. The legal values for the valueType and the corresponding attribute values are:
Value TypeJava Type / Value Range
URLjava.lang.String
UUID javax.bluetooth.UUID
STRING java.lang.String
INT_16 [-2127, 2127-1] as a byte array whose length must be 16
U_INT_8 [0, 264-1] as a byte array whose length must be 8
U_INT_16 [0, 2128-1] as a byte array whose length must be 16
All other pairings are illegal and would cause an IllegalArgumentException exception.

Parameters:
valueType - the data type of the object that is being created; must be one of the following: URL, UUID, STRING, INT_16, U_INT_8, or U_INT_16
value - the value for the DataElement being created of type valueType
Throws:
IllegalArgumentException - if the value is not of the valueType type or is not in the range specified or is null
See Also:
DataElement.URL, DataElement.UUID, DataElement.STRING, DataElement.U_INT_8, DataElement.INT_16, DataElement.U_INT_16
Since:
BlackBerry API 4.2.1


Method Detail

addElement

public void addElement(DataElement elem)
Adds a DataElement to this DATALT or DATSEQ DataElement object. The elem will be added at the end of the list. The elem can be of any DataElement type, i.e., URL, NULL, BOOL, UUID, STRING, DATSEQ, DATALT, and the various signed and unsigned integer types. The same object may be added twice. If the object is successfully added the size of the DataElement is increased by one.

Parameters:
elem - the DataElement object to add
Throws:
ClassCastException - if the method is invoked on a DataElement whose type is not DATALT or DATSEQ
NullPointerException - if elem is null
Since:
BlackBerry API 4.2.1

insertElementAt

public void insertElementAt(DataElement elem,
                            int index)
Inserts a DataElement at the specified location. This method can be invoked only on a DATALT or DATSEQ DataElement. elem can be of any DataElement type, i.e., URL, NULL, BOOL, UUID, STRING, DATSEQ, DATALT, and the various signed and unsigned integers. The same object may be added twice. If the object is successfully added the size will be increased by one. Each element with an index greater than or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

The index must be greater than or equal to 0 and less than or equal to the current size. Therefore, DATALT and DATSEQ are zero-based objects.

Parameters:
elem - the DataElement object to add
index - the location at which to add the DataElement
Throws:
ClassCastException - if the method is invoked on an instance of DataElement whose type is not DATALT or DATSEQ
IndexOutOfBoundsException - if index is negative or greater than the size of the DATALT or DATSEQ
NullPointerException - if elem is null
Since:
BlackBerry API 4.2.1

getSize

public int getSize()
Returns the number of DataElements that are present in this DATALT or DATSEQ object. It is possible that the number of elements is equal to zero.

Returns:
the number of elements in this DATALT or DATSEQ
Throws:
ClassCastException - if this object is not of type DATALT or DATSEQ
Since:
BlackBerry API 4.2.1

removeElement

public boolean removeElement(DataElement elem)
Removes the first occurrence of the DataElement from this object. elem may be of any type, i.e., URL, NULL, BOOL, UUID, STRING, DATSEQ, DATALT, or the variously sized signed and unsigned integers. Only the first object in the list that is equal to elem will be removed. Other objects, if present, are not removed. Since this class doesn’t override the equals() method of the Object class, the remove method compares only the references of objects. If elem is successfully removed the size of this DataElement is decreased by one. Each DataElement in the DATALT or DATSEQ with an index greater than the index of elem is shifted downward to have an index one smaller than the value it had previously.

Parameters:
elem - the DataElement to be removed
Returns:
true if the input value was found and removed; else false
Throws:
ClassCastException - if this object is not of type DATALT or DATSEQ
NullPointerException - if elem is null
Since:
BlackBerry API 4.2.1

getDataType

public int getDataType()
Returns the data type of the object this DataElement represents.

Returns:
the data type of this DataElement object; the legal return values are: URL, NULL, BOOL, UUID, STRING, DATSEQ, DATALT, U_INT_1, U_INT_2, U_INT_4, U_INT_8, U_INT_16, INT_1, INT_2, INT_4, INT_8, or INT_16
Since:
BlackBerry API 4.2.1

getLong

public long getLong()
Returns the value of the DataElement if it can be represented as a long. The data type of the object must be U_INT_1, U_INT_2, U_INT_4, INT_1, INT_2, INT_4, or INT_8.

Returns:
the value of the DataElement as a long
Throws:
ClassCastException - if the data type of the object is not U_INT_1, U_INT_2, U_INT_4, INT_1, INT_2, INT_4, or INT_8
Since:
BlackBerry API 4.2.1

getBoolean

public boolean getBoolean()
Returns the value of the DataElement if it is represented as a boolean.

Returns:
the boolean value of this DataElement object
Throws:
ClassCastException - if the data type of this object is not of type BOOL
Since:
BlackBerry API 4.2.1

getValue

public Object getValue()
Returns the value of this DataElement as an Object. This method returns the appropriate Java object for the following data types: URL, UUID, STRING, DATSEQ, DATALT, U_INT_8, U_INT_16, and INT_16. Modifying the returned Object will not change this DataElement. The following are the legal pairs of data type and Java object type being returned.
DataElement Data Type Java Data Type
URLjava.lang.String
UUID javax.bluetooth.UUID
STRINGjava.lang.String
DATSEQ java.util.Enumeration
DATALT java.util.Enumeration
U_INT_8 byte[] of length 8
U_INT_16 byte[] of length 16
INT_16 byte[] of length 16

Returns:
the value of this object
Throws:
ClassCastException - if the object is not a URL, UUID, STRING, DATSEQ, DATALT, U_INT_8, U_INT_16, or INT_16
Since:
BlackBerry API 4.2.1





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.