net.rim.device.api.synchronization.ConverterUtilities
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public final class ConverterUtilities
A set of static utility methods used when formatting or parsing data used during serial synchronization with the RIM desktop.
All data used by the RIM desktop is structured as a sequence of fields, each in the following format, where n is the length specified in the first short:
Length<2> Type<1> Data<n>
Note that the type of a field is restricted to be an integer between
-128 and 127. Setting a type to n
for any integer n is equivalent to setting a type to r
where r is an integer between -128 and 127, and such that
n = q * 256 + r, q an integer.
Data communication to or from the desktop must be in this format. Records that are not may either cause errors or may cause the data to be lost.
There are two ways that these utilities will typically be used. The first is to iterate over all fields in the buffer:
buffer.rewind();
try {
for (;;) {
int type;
try {
type = ConverterUtilities.getType( buffer );
} catch (EOFException e) {
// at end of buffer
break;
}
switch (type) {
case 1:
// do something with ConverterUtilities.readString( buffer )
break;
case 2:
// do something with ConverterUtilities.readString( buffer )
break;
default:
// Unrecognised tag, so ConverterUtilities.skipField( buffer )
break;
}
}
// do something with the result.
} catch (EOFException e) {
// an error occurred
}
The second is to search for specific fields in the buffer:
try {
buffer.rewind();
while (ConverterUtilities.findType( buffer, 1 )) {
// do something with ConverterUtilities.readString( buffer )
}
buffer.rewind();
while (ConverterUtilities.findType( buffer, 2 )) {
// do something with ConverterUtilities.readString( buffer )
}
// do something with the result.
} catch (EOFException e) {
// an error occurred
}
Note that at any point where one might call ConverterUtilities.readString(net.rim.device.api.util.DataBuffer),
you may also perform special processing to extract the next field,
provided that the read/write pointer of the data buffer is advanced
to the next field.
SyncConverter| Field Summary | ||
|---|---|---|
|
static int |
CONSUMED_FIELD
Marker indicates that the field has been consumed. |
| Method Summary | ||
|---|---|---|
|
static boolean |
findType(DataBuffer buffer,
int type)
Finds the next field in the data buffer of the specified type. |
|
static int |
getType(DataBuffer buffer)
Extracts the type of the next field in the data buffer. |
|
static boolean |
isType(DataBuffer buffer,
int type)
Determines whether the next field in the data buffer matches a specified type. |
|
static byte[] |
readByteArray(DataBuffer buffer)
Extracts a byte array from a data buffer. |
|
static byte[] |
readByteArray(DataBuffer buffer,
boolean markConsumed)
Extracts a byte array from a data buffer. |
|
static void |
readByteStream(DataBuffer buffer,
boolean markConsumed,
OutputStream out)
Extracts a byte array from a data buffer. |
|
static int |
readInt(DataBuffer buffer)
Extracts an integer from a data buffer. |
|
static int |
readInt(DataBuffer buffer,
boolean markConsumed)
Extracts an integer from a data buffer. |
|
static int[] |
readIntArray(DataBuffer buffer)
Extracts an integer array from a data buffer. |
|
static int[][] |
readIntArrayArray(DataBuffer buffer,
boolean allowNulls)
Extracts an array of integer arrays from a data buffer. |
|
static long |
readLong(DataBuffer buffer)
Extracts a long integer from a data buffer. |
|
static long |
readLong(DataBuffer buffer,
boolean markConsumed)
Extracts a long integer from a data buffer. |
|
static long[] |
readLongArray(DataBuffer buffer)
Extracts a long array from a data buffer. |
|
static short |
readShort(DataBuffer buffer)
Extracts a short integer from a data buffer. |
|
static short |
readShort(DataBuffer buffer,
boolean markConsumed)
Extracts a short integer from a data buffer. |
|
static short[] |
readShortArray(DataBuffer buffer)
Extracts a short array from a data buffer. |
|
static String |
readString(DataBuffer buffer)
Extracts a string from a data buffer without consuming the field. |
|
static String |
readString(DataBuffer buffer,
boolean markConsumed)
Extracts a string from a DataBuffer. |
|
static void |
skipField(DataBuffer buffer)
Skips over the next field in the data buffer. |
|
static void |
writeByteArray(DataBuffer buffer,
int type,
byte[] s)
Writes a binary string with the specified type in the provided data buffer. |
|
static void |
writeByteStream(DataBuffer buffer,
int type,
InputStream stream,
long length)
Writes a binary stream with the specified type in the provided data buffer. |
|
static void |
writeCharArrayArray(DataBuffer buffer,
int type,
char[][] array)
Writes an array of character arrays with the specified type in the provided data buffer. |
|
static void |
writeEmptyField(DataBuffer buffer,
int type)
Writes an empty field of the specified type in the provided data buffer. |
|
static void |
writeInt(DataBuffer buffer,
int type,
int value)
Writes an integer scalar in the provided data buffer as 8 bytes. |
|
static void |
writeIntArray(DataBuffer buffer,
int type,
int[] array)
Writes an array of integers with the specified type in the provided data buffer. |
|
static void |
writeIntArrayArray(DataBuffer buffer,
int type,
int[][] array)
Writes an array of integer arrays with the specified type in the provided data buffer. |
|
static void |
writeLong(DataBuffer buffer,
int type,
long value)
Writes a long scalar in the provided data buffer as 8 bytes. |
|
static void |
writeLongArray(DataBuffer buffer,
int type,
long[] array)
Writes an array of longs with the specified type in the provided data buffer. |
|
static void |
writeShort(DataBuffer buffer,
int type,
short value)
Writes a short scalar in the provided data buffer as 8 bytes. |
|
static void |
writeShortArray(DataBuffer buffer,
int type,
short[] array)
Writes an array of shorts with the specified type in the provided data buffer. |
|
static void |
writeString(DataBuffer buffer,
int type,
String text)
Writes an encoded string into the provided data buffer. |
| Methods inherited from class java.lang.Object |
|---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final int CONSUMED_FIELD
| Method Detail |
|---|
public static String readString(DataBuffer buffer)
throws EOFException
This method advances the read/write position of the data buffer to
the next field in the buffer, but does not mark the read field as
consumed: that is, it invokes
readString(buffer,false).
buffer - The buffer from which to extract a null-terminated string.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing a string.
NullPointerException - if buffer
is null.
public static String readString(DataBuffer buffer,
boolean markConsumed)
throws EOFException
DataBuffer.
This method advances the read/write position of the data buffer to the next field in the buffer. The maximum data size is 65535B.
The buffer is expected to be in one of the following formats:
If the first bytes are 0xFE 0xFF, then the buffer is encoded in
UTF-16 big endian.
The BOM 0xFE 0xFF is removed and the remaining bytes are interpreted as
UTF-16 big endian. Newlines are assumed to be 0x000A.
If the first bytes are 0xEF 0xBB 0xBF, then the buffer is encoded
in UTF-8. Otherwise, the buffer is encoded in ISO-8859-1.
The BOM 0xEF 0xBB 0xBF is removed and the remaining bytes are interpreted
as UTF-8. Newlines are assumed to be 0x000A.
In all other cases, the buffer is encoded in ISO-8859-1.
The buffer may have an extra byte 0x00 appended to the end (for a string
with n 0x00 bytes at the end, n+1 are written so either 0 or 1 0x00
indicate this characters must not be included with the string).
The control region (0x80-0xA0) is enterpreted as on Windows and mapped into the Unicode character set. The character 0x000D is converted to 0x000A.
buffer - The data buffer from which to extract a null-terminated
string.markConsumed - Write a ConverterUtilities.CONSUMED_FIELD marker to the field's
type element. This can be used to see if the field has already been
processed.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing a string.
NullPointerException - if buffer
is null.
public static void writeString(DataBuffer buffer,
int type,
String text)
In general, no transformations other than encoding take place. Newlines are kept as newlines (not converted to CRLF). No null termination is added. Other behaviour depends on the encoding of the buffer:
If the String contains Unicode
The bytes 0xFE 0xFF are written followed by the 16 bit chars in big
endian UTF-16. The right of writing UTF-8 is reserved: compliant readers
must handle the case where the buffer contains bytes 0xEF 0xBB 0xBF
followed by the string in UTF-8.
If the String contains only ISO-8859-1
The string is written without a Unicode BOM, only a series of bytes
ISO-8859-1 encoded. For legacy reasons, if the string is encoded as
Latin-1 bytes and the string ends in 0x00, then an extra 0x00 is appended
to the end.
buffer - Data buffer to contain written string.type - Type byte to write into buffer before string.text - String to write into buffer.
NullPointerException - if buffer
is null.
public static void writeByteArray(DataBuffer buffer,
int type,
byte[] s)
buffer - Data buffer to receive the string.type - Type to tag the string.s - Byte array to encode.
IllegalArgumentException - if length of s cannot be represented
NullPointerException - if either buffer or
s is null.
public static void writeByteStream(DataBuffer buffer,
int type,
InputStream stream,
long length)
buffer - Data buffer to receive the stream.type - Type to tag the stream.stream - Stream to encode.length - Number of bytes from stream to write.
IllegalArgumentException - if length is negative
NullPointerException - if buffer
is null.ConverterUtilities.readByteStream(net.rim.device.api.util.DataBuffer, boolean, java.io.OutputStream)
public static void writeCharArrayArray(DataBuffer buffer,
int type,
char[][] array)
buffer - Data buffer to receive the array.type - Type to tag the array.array - Array to encode.
NullPointerException - if either buffer or
array is null.
public static void writeInt(DataBuffer buffer,
int type,
int value)
buffer - Data buffer to receive the data.type - Type to tag the data.value - Integer to encode.
NullPointerException - if buffer
is null.
public static void writeIntArray(DataBuffer buffer,
int type,
int[] array)
buffer - Data buffer to receive the array.type - Type to tag the array.array - Array whose bytes to encode.
NullPointerException - if either buffer or
array is null.
public static void writeIntArrayArray(DataBuffer buffer,
int type,
int[][] array)
buffer - Data buffer to receive the array.type - Type to tag the array.array - Array whose bytes to encode.
NullPointerException - if either buffer or
array is null.
public static void writeShort(DataBuffer buffer,
int type,
short value)
buffer - Data buffer to receive the data.type - Type to tag the data.value - Short integer to encode.
NullPointerException - if buffer
is null.
public static void writeShortArray(DataBuffer buffer,
int type,
short[] array)
buffer - Data buffer to receive the array.type - Type to tag the array.array - Array whose bytes to encode.
NullPointerException - if either buffer or
array is null.
public static void writeLong(DataBuffer buffer,
int type,
long value)
buffer - Data buffer to receive the data.type - Type to tag the data.value - Long integer value to encode.
NullPointerException - if buffer
is null.
public static void writeLongArray(DataBuffer buffer,
int type,
long[] array)
buffer - Data buffer to receive the array.type - Type to tag the array.array - Array whose bytes to encode
NullPointerException - if either buffer or
array is null.
public static void writeEmptyField(DataBuffer buffer,
int type)
buffer - Data buffer to receive the empty field.type - Type to tag the empty field.
NullPointerException - if buffer
is null.
public static int getType(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is not affected by this method.
buffer - Buffer to examine.
EOFException - If there is insufficient data in the data buffer to
extract a type field.
NullPointerException - if buffer
is null.
public static void skipField(DataBuffer buffer)
throws EOFException
buffer - Buffer to advance.
EOFException - If there is insufficient data in the data buffer to
advance past the field.
NullPointerException - if buffer
is null.
public static boolean isType(DataBuffer buffer,
int type)
The read/write position of the data buffer is not affected by this method.
buffer - Data buffer to examine.type - Type to be matched.
true if the next field in the data buffer has the specified type;
false if the next field does not have the specified type or if there is
insufficient data in the data buffer to determine a field type.
NullPointerException - if buffer
is null.
public static byte[] readByteArray(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract a binary string.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing a string.
NullPointerException - if buffer
is null.
public static byte[] readByteArray(DataBuffer buffer,
boolean markConsumed)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract a string.markConsumed - If true, writes a ConverterUtilities.CONSUMED_FIELD marker to the
field's type element. This can be used to see if the field has already
been processed.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing a string.
NullPointerException - if buffer
is null.
public static void readByteStream(DataBuffer buffer,
boolean markConsumed,
OutputStream out)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract a string.markConsumed - If true, writes a ConverterUtilities.CONSUMED_FIELD marker to
the field's type element. This can be used to see if the field has
already been processed.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing a string.
NullPointerException - if buffer
is null.ConverterUtilities.writeByteStream(net.rim.device.api.util.DataBuffer, int, java.io.InputStream, long)
public static short[] readShortArray(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract an array.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing an array.
NullPointerException - if buffer
is null.
public static int[] readIntArray(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - The data buffer from which to extract an array.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing an array.
NullPointerException - if buffer
is null.
public static int[][] readIntArrayArray(DataBuffer buffer,
boolean allowNulls)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract.allowNulls - If false, forces allocation of zero length member
arrays, if true sets zero length members to null.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing an array.
NullPointerException - if buffer
is null.
public static long[] readLongArray(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - The data buffer from which to extract an array.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed field containing an array.
NullPointerException - if buffer
is null.
public static boolean findType(DataBuffer buffer,
int type)
The read/write position of the data buffer is advanced to the beginning of the next field if possible. If not, the read/write position is left at the same place it started at.
buffer - Data buffer to examine.type - Type to look for.
true if a field of the specified type could be found;
false otherwise.
NullPointerException - if buffer
is null.
public static short readShort(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract the short integer.
EOFException - If there is insufficient data in the data buffer
to correctly extract a short integer.
NullPointerException - if buffer
is null.
public static short readShort(DataBuffer buffer,
boolean markConsumed)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - The data buffer from which to extract a short integer.markConsumed - If true, writes a ConverterUtilities.CONSUMED_FIELD marker to
the field's type element. This can be used to see if the field has
already been processed.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed short integer.
NullPointerException - if buffer
is null.
public static int readInt(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract the integer.
EOFException - If there is insufficient data in the data buffer
to correctly extract an integer.
NullPointerException - if buffer
is null.
public static int readInt(DataBuffer buffer,
boolean markConsumed)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - The data buffer from which to extract an integer.markConsumed - If true, writes a ConverterUtilities.CONSUMED_FIELD marker to
the field's type element. This can be used to see if the field has
already been processed.
EOFException - If there is insufficient data in the data buffer to
correctly extract a well-formed integer.
NullPointerException - if buffer
is null.
public static long readLong(DataBuffer buffer)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - The data buffer from which to extract the long integer.
EOFException - If there is insufficient data in the data buffer to
correctly extract a long integer.
NullPointerException - if buffer
is null.
public static long readLong(DataBuffer buffer,
boolean markConsumed)
throws EOFException
The read/write position of the data buffer is advanced to the next field in the data buffer.
buffer - Data buffer from which to extract a long integermarkConsumed - If true, write a ConverterUtilities.CONSUMED_FIELD marker to
the field's type element. This can be used to see if the field has
already been processed.
EOFException - If there is insufficient data in the data buffer
to correctly extract a well-formed long integer.
NullPointerException - if buffer
is null.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal