net.rim.device.api.util
Class TLEUtilities

java.lang.Object
  |
  +--net.rim.device.api.util.TLEUtilities

public final class TLEUtilities
extends Object

Utility methods for manipulating type-length encoded (TLE) fields.


Method Summary
static boolean findType(DataBuffer buffer, int type)
          Determines if a specific type is contained in the encoding from the current position to the end of the buffer.
static int getFieldSize(int dataSize)
          Determines the number of bytes required to write a byte field.
static int getIntegerFieldSize(int i)
          Determines the number of bytes required to write an integer type field.
static String getStringFromBuffer(DataBuffer buf, int length)
          Retrieves string from provided buffer.
static void parseBuffer(DataBuffer db, TLEFieldController con)
          Parses a DataBuffer using the given TLE field controller.
static void parseField(DataBuffer db, TLEFieldController con, int length)
          Parses a field within a data buffer using the given TLE field controller.
static byte[] readDataField(DataBuffer buf)
          Reads a field containing a sequence of bytes into a byte array.
static byte[] readDataField(DataBuffer buf, int type)
          Reads a field containing a sequence of bytes into a byte array.
static int readIntegerField(DataBuffer buf)
          Reads an integer field from the data buffer.
static int readIntegerField(DataBuffer buf, int type)
          Reads an integer field from the data buffer.
static int readIntegerFieldWithLength(DataBuffer buf, int length)
          Reads an integer field from the data buffer.
static String readStringField(DataBuffer buf, boolean stripNull)
          Reads a field containing a sequence of bytes into a string.
static String readStringField(DataBuffer buf, int type)
          Reads a field containing a sequence of bytes into a string.
static String readStringField(DataBuffer buf, int type, boolean stripNull)
          Reads a field containing a sequence of bytes into a string.
static void skipField(DataBuffer buffer)
          Skips over the next field in the DataBuffer.
static void writeDataField(DataBuffer buf, int type, byte[] data)
          Writes a byte array field to the data buffer with the specified type.
static void writeDataField(DataBuffer buf, int type, byte[] data, int offset, int length)
          Writes section of byte array field to the data buffer with the specified type.
static void writeDataField(DataBuffer buf, int type, String value, int start, int len, boolean addNull)
          Writes section of String field to the data buffer with the specified type.
static void writeField(DataBuffer db, int type, TLEFieldController con)
          Writes a TLE field into the DataBuffer.
static void writeIntegerField(DataBuffer buf, int type, int value, boolean fixed)
          Writes an integer field to the data buffer with the specified type.
static void writeStringField(DataBuffer buf, int type, String value)
          Writes a string field to the data buffer with the specified type.
static void writeStringField(DataBuffer buf, int type, String value, boolean addNull)
          Writes a string field (with optional terminating null) to the data buffer with the specified type.
static void writeStringField(DataBuffer buf, int type, String value, int offset, int length)
          Writes section of string field to the data buffer with the specified type.
static void writeStringField(DataBuffer buf, int type, String value, int offset, int len, boolean addNull)
          Writes section of string field (with optional terminating null) to the data buffer with the specified type.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

findType

public static boolean findType(DataBuffer buffer,
                               int type)
Determines if a specific type is contained in the encoding from the current position to the end of the buffer. If the type is found then the position of the buffer is updated to have that type as the next type.
Parameters:
buffer - the DataBuffer to examine.
type - the type to search for.
Returns:
a boolean indicating whether or not the type was found.
Since:
JDE 4.0.0

getFieldSize

public static final int getFieldSize(int dataSize)
Determines the number of bytes required to write a byte field.

Parameters:
dataSize - Number of bytes you want to write.
Returns:
Required field size to write your data bytes.

getIntegerFieldSize

public static int getIntegerFieldSize(int i)
Determines the number of bytes required to write an integer type field.

Parameters:
i - Integer you want to write.
Returns:
Required field size for provided integer.

getStringFromBuffer

public static String getStringFromBuffer(DataBuffer buf,
                                         int length)
Retrieves string from provided buffer.

Used by TLEFieldControllers for getting Strings from data buffers (primarily with their TLEFieldController.processField(int, int, net.rim.device.api.util.DataBuffer) methods).

Parameters:
buf - Data buffer containing the string that you want to extract
length - Length of the string to be extracted, as passed into TLEFieldController.processField(int, int, net.rim.device.api.util.DataBuffer).
Returns:
String extracted from buffer.
Since:
JDE 4.0.0

parseBuffer

public static void parseBuffer(DataBuffer db,
                               TLEFieldController con)
                        throws IllegalArgumentException,
                               EOFException
Parses a DataBuffer using the given TLE field controller.

Parameters:
db - Data buffer to parse.
con - Controller to use during parsing.

parseField

public static void parseField(DataBuffer db,
                              TLEFieldController con,
                              int length)
                       throws IllegalArgumentException,
                              EOFException
Parses a field within a data buffer using the given TLE field controller.

Before parsing begins the data buffer's size is set to be the size of the field. The original size is then restored once parsing is finished. This routine is used to parse nested fields.

Parameters:
db - Data buffer to parse.
con - Controller to use during parsing.
length - Length of the field.

readDataField

public static byte[] readDataField(DataBuffer buf)
                            throws EOFException
Reads a field containing a sequence of bytes into a byte array.

A new byte array is created to hold the data. The type in the data buffer must match the specified type.

Parameters:
buf - Databuffer containing the data bytes.
Returns:
Byte array containing data.
Since:
JDE 4.0.0

readDataField

public static byte[] readDataField(DataBuffer buf,
                                   int type)
                            throws IllegalArgumentException,
                                   EOFException
Reads a field containing a sequence of bytes into a byte array.

A new byte array is created to hold the data. The type in the data buffer must match the specified type.

Parameters:
buf - Databuffer containing the data bytes.
type - Expected type.
Returns:
Byte array containing data.
Throws:
IllegalArgumentException - if the types do not match.

readIntegerField

public static int readIntegerField(DataBuffer buf)
                            throws EOFException,
                                   IllegalArgumentException
Reads an integer field from the data buffer.

An integer field will be either 1, 2 or 4 bytes in size. A 1 or 2-byte field is assumed to contain an unsigned value while the 4 byte field is signed.

Parameters:
buf - Data buffer containing the integer field.
Returns:
Integer read from field.
Throws:
IllegalArgumentException - if buf parameter does not read a proper compressed integer value.
Since:
JDE 4.0.0

readIntegerField

public static int readIntegerField(DataBuffer buf,
                                   int type)
                            throws IllegalArgumentException,
                                   EOFException
Reads an integer field from the data buffer.

The type in the data buffer must match the specified type. An integer field will be either 1, 2 or 4 bytes in size. A 1 or 2-byte field is assumed to contain an unsigned value while the 4 byte field is signed.

Parameters:
buf - Data buffer containing the integer field.
type - Expected type.
Returns:
Integer read from field.
Throws:
IllegalArgumentException - if the types do not match, or if a suitable compressedInt value is not read from buf.

readIntegerFieldWithLength

public static int readIntegerFieldWithLength(DataBuffer buf,
                                             int length)
                                      throws EOFException,
                                             IllegalArgumentException
Reads an integer field from the data buffer.

An integer field will be either 1, 2 or 4 bytes in size. A 1 or 2-byte field is assumed to contain an unsigned value while the 4 byte field is signed.

Primarily intended for use by TLEFieldController.processField(int, int, net.rim.device.api.util.DataBuffer) methods.

Parameters:
buf - Data buffer containing the integer field.
length - the size of the contained integer. Should be one of: 1, 2 or 4.
Returns:
Integer read from field.
Throws:
IllegalArgumentException - if buf parameter does not read a proper compressed integer value.
Since:
JDE 4.0.0

readStringField

public static String readStringField(DataBuffer buf,
                                     boolean stripNull)
                              throws EOFException
Reads a field containing a sequence of bytes into a string.

Parameters:
buf - Data buffer containing the data bytes.
stripNull - Indicates if the null-terminator, if it exists, is to be stripped from the data stream before the string is made.
Returns:
String containing data.
Since:
JDE 4.0.0

readStringField

public static String readStringField(DataBuffer buf,
                                     int type)
                              throws IllegalArgumentException,
                                     EOFException
Reads a field containing a sequence of bytes into a string.

The bytes may or may not be null-terminated. The null-terminator will be stripped from the data stream before the string is made.

Parameters:
buf - Data buffer containing the data bytes.
type - Expected type.
Returns:
String containing data.
Throws:
IllegalArgumentException - if the types do not match.

readStringField

public static String readStringField(DataBuffer buf,
                                     int type,
                                     boolean stripNull)
                              throws IllegalArgumentException,
                                     EOFException
Reads a field containing a sequence of bytes into a string.

Parameters:
buf - Data buffer containing the data bytes.
type - Expected type.
stripNull - Indicates if the null-terminator, if it exists, is to be stripped from the data stream before the string is made.
Returns:
String containing data.
Throws:
IllegalArgumentException - if the types do not match.
Since:
JDE 3.6.0

skipField

public static void skipField(DataBuffer buffer)
                      throws EOFException
Skips over the next field in the DataBuffer. This method asumes that the type is currently lined up as the next part to be read in the encoding.
Parameters:
buffer - the DataBuffer to skip the next field in.
Throws:
EOFException - if there is not enough data left in the buffer to skip.
Since:
JDE 4.0.0

writeDataField

public static void writeDataField(DataBuffer buf,
                                  int type,
                                  byte[] data)
Writes a byte array field to the data buffer with the specified type.

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
data - Byte array containing bytes to write.

writeDataField

public static void writeDataField(DataBuffer buf,
                                  int type,
                                  byte[] data,
                                  int offset,
                                  int length)
Writes section of byte array field to the data buffer with the specified type.

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
data - Byte array containing bytes to write.
start - First byte to write.
len - Number of bytes to write.

writeDataField

public static void writeDataField(DataBuffer buf,
                                  int type,
                                  String value,
                                  int start,
                                  int len,
                                  boolean addNull)
Writes section of String field to the data buffer with the specified type.

The string is written as a sequence of ASCII bytes so this routine will not handle characters with values > 255. This differs from writeStringField which handles values > 255. Use this when a byte string *must* be written (eg. protocol headers, ...)

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
value - Value to write.
offset - First character of string value to write in the buffer.
len - Number of characters from string to write in the buffer.
addNull - If true, the field will be null terminated; if false, the field will not be null terminated.
Since:
JDE 3.7.0

writeField

public static void writeField(DataBuffer db,
                              int type,
                              TLEFieldController con)
Writes a TLE field into the DataBuffer.

Use this method when you don't know how big the field will be beforehand as it will automatically calculate the size once it is finished.

Parameters:
db - Data buffer to contain the written field.
type - Type of the field.
con - Controller to use to write the data.

writeIntegerField

public static void writeIntegerField(DataBuffer buf,
                                     int type,
                                     int value,
                                     boolean fixed)
Writes an integer field to the data buffer with the specified type.

A fixed integer field will always be 4 bytes, otherwise it can be either 1, 2 or 4 bytes in size(the smallest size field will be used to contain the given value).

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
value - Value to write.
fixed - If true, the field should have a fixed size of 4 bytes.

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value)
Writes a string field to the data buffer with the specified type.

The string written is not null terminated.

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
value - Value to write.
Since:
JDE 3.6.0

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    boolean addNull)
Writes a string field (with optional terminating null) to the data buffer with the specified type.

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
value - Value to write.
addNull - If true, the field will be null terminated; if false, the field will not be null terminated.

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    int offset,
                                    int length)
Writes section of string field to the data buffer with the specified type.

The string is not null terminated.

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
value - Value to write.
Since:
JDE 3.6.0

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    int offset,
                                    int len,
                                    boolean addNull)
Writes section of string field (with optional terminating null) to the data buffer with the specified type.

If all the characters are less than 255, then the substring is written in Latin-1. Otherwise, the bytes 0xFE 0xFF are written and the string is written in UCS-2(big endian). The encoded version may optionally be null-terminated (null termination in UCS-2 is 2 NUL bytes).

Parameters:
buf - Data buffer to contain the written field.
type - Type of the field.
value - Value to write.
offset - First character of string value to write in the buffer.
len - Number of characters from string to write in the buffer.
addNull - If true, the field will be null terminated; if false, the field will not be null terminated.



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.