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 int	getFieldSize(int dataSize) Determines the number of bytes required to write a field that contains the given number of bytes.
static int	getIntegerFieldSize(int i) Determines the number of bytes required to write an integer type field for the given integer.
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, int type) Reads a field containing a sequence of bytes into a byte array.
static int	readIntegerField(DataBuffer buf, int type) Reads an integer field from the data buffer.
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	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 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 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

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.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.

Since:

JDE 3.7.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.

Since:

JDE 3.7.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.

Since:

JDE 3.7.0

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.7.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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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 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.7.0

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    boolean addNull)

Writes a String field 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.

Since:

JDE 3.7.0

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.7.0

writeStringField

public static void writeStringField(DataBuffer buf,
                                    int type,
                                    String value,
                                    int offset,
                                    int len,
                                    boolean addNull)

Writes section of String field to the data buffer with the specified type.

If all the characters are < 255, then then 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.

Since:

JDE 3.7.0

getIntegerFieldSize

public static int getIntegerFieldSize(int i)

Determines the number of bytes required to write an integer type field for the given integer.

Parameters:

i - Integer you want to write.

Returns:

Required field size for provided integer.

Since:

JDE 3.7.0

getFieldSize

public static final int getFieldSize(int dataSize)

Determines the number of bytes required to write a field that contains the given number of bytes.

Parameters:

dataSize - Number of bytes you want to write.

Returns:

Required field size to write your data bytes.

Since:

JDE 3.7.0