net.rim.device.api.util
Class DataBuffer

java.lang.Object
  net.rim.device.api.util.DataBuffer

All Implemented Interfaces:

DataInput, DataOutput, Persistable

Direct Known Subclasses:

DatagramBase

public class DataBuffer
extends Object
implements DataInput, DataOutput, Persistable

Single, random-access data stream.

Behaviour
This data buffer supports reading and writing of primitive types, and automatically grows the buffer as required to hold the data.

Note: you can build a data buffer, or prompt it with setData, to use an existing byte array or data buffer as the underlying data store for this buffer. If you do so, you must realize that this buffer "owns" the right to modify the underlying data store's contents, and resize it as necessary.

You can indicate whether numeric data (char, short, int, long) is written to the buffer in big or little endian form. By default, data buffers are constructed to store numeric data in big endian form.

There are functions to read and write compressed integers, which will write an integer in as few bytes as possible (in big endian form only). A simple more-bit technique is employed, whereby the top bit is set if the next byte contains more of the integer. Each byte contains seven bits of the integer.

Constructor Summary

DataBuffer()
Constructs a new, empty, big endian DataBuffer instance.

DataBuffer(boolean bigEndianFlag)
Constructs a new, emtpy DataBuffer instance.

DataBuffer(byte[] contents, int offset, int numBytes, boolean bigEndianFlag)
Constructs a new DataBuffer instance using provided byte array as backing store.

DataBuffer(int bufferSize, boolean bigEndianFlag)
Constructs a new, empty DataBuffer instance of provided initial size.

DataBuffer(DataBuffer contentBuffer, int numBytes)
Constructs a new DataBuffer instance using provided data buffer as backing store.

Method Summary
int	available() Retrieves number of elements left in the buffer beyond the read/write position.
protected void	ensureBuffer(int newLength) Ensures the buffer is of a particular total length.
void	ensureCapacity(int dataLength) Ensures the buffer has sufficient data capacity left.
void	ensureLength(int newLength) Ensures the buffer has a data area of specified size.
boolean	eof() Determines if the read/write position is at the end of the buffer.
byte[]	getArray() Retrieves underlying store.
int	getArrayLength() Retrieves length of this buffer's underlying store.
int	getArrayPosition() Retrieves index in store holding this buffer's current read/write position.
int	getArrayStart() Retrieves index in store holding first element of buffer's data area.
static int	getCompressedIntSize(int i) Retrieves the number of bytes needed to compress an integer value.
int	getLength() Returns the length of this buffer's data area.
int	getPosition() Retrieves current read/write position.
boolean	isBigEndian() Determines if this buffer writes numeric data in big endian form.
int	read(byte[] outputBuffer) Attempts to read to fill provided output buffer.
int	read(byte[] outputBuffer, int outputBufferOffset, int outputBufferLength) Attempts to read to fill section of provided output buffer.
int	read(OutputStream outputStream) Reads this DataBuffer into the provided output stream.
int	read(OutputStream outputStream, int length) Reads a section of this DataBuffer into the provided output stream.
boolean	readBoolean() Determine if next byte is non-zero.
byte	readByte() Retrives next byte from this buffer.
byte[]	readByteArray() Reads byte array from this buffer.
char	readChar() Reads next two bytes mashed together into a character.
int	readCompressedInt() Reads compressed integer.
long	readCompressedLong() Reads compressed long integer.
double	readDouble() Reads next eight bytes as a double value.
float	readFloat() Reads next four bytes as a float value.
void	readFully(byte[] outputBuffer) Reads to fill provided output buffer.
void	readFully(byte[] outputBuffer, int outputBufferOffset, int outputBufferLength) Reads to fill section of provided output buffer.
int	readInt() Reads next four bytes as an integer.
String	readLine() Reads the next line of text from the input stream.
long	readLong() Reads next eight bytes as a long integer.
short	readShort() Reads next two bytes as a short integer.
String	readUTF() Reads UTF-8 string.
int	readUnsignedByte() Reads next single byte as an unsigned byte value.
int	readUnsignedShort() Reads next two bytes as an unsigned short value.
void	reset() Flushes and resets buffer.
void	rewind() Sets read/write position to start of this buffer's data area.
void	setBigEndian(boolean flag) Sets numeric data form for this buffer.
void	setData(byte[] contents, int offset, int numBytes) Sets the data store for this buffer.
void	setData(byte[] contents, int offset, int numBytes, boolean bigEndianFlag) Sets the data store for this buffer.
void	setLength(int newLength) Sets the length of the data area for this buffer.
void	setPosition(int newPosition) Sets current read/write position.
int	skipBytes(int n) Attempts to skip over some bytes in this buffer.
byte[]	toArray() Retrieves buffer data into an array.
void	trim() Trims the tail of the underlying data store.
void	trim(boolean resize) Trims the tail of the underlying data store.
void	write(byte[] b) Writes byte array to this buffer.
void	write(byte[] b, int off, int len) Writes section of byte array to this buffer.
void	write(int b) Writes single byte to this buffer.
void	write(DataInput input, int length) Writes some data from data input to this buffer.
void	write(InputStream input) Writes input stream data to this buffer.
void	write(InputStream input, int length) Writes some data from input stream to this buffer.
void	write(DataBuffer dataBuffer, int length) Writes section of data buffer to this buffer.
void	writeBoolean(boolean v) Writes boolean to this buffer.
void	writeByte(int v) Writes single byte to this buffer.
void	writeByteArray(byte[] b) Writes byte array to this buffer.
void	writeByteArray(byte[] b, int offset, int length) Writes section of byte array to this buffer.
void	writeByteArray(byte[] b, int offset, int length, boolean writeLength) Writes section of byte array to this buffer.
void	writeBytes(String s) Writes a string to the output stream.
void	writeChar(int v) Writes character to this buffer.
void	writeChars(String s) Writes characters in string to this buffer.
void	writeCompressedInt(int i) Writes compressed integer to this buffer.
void	writeCompressedLong(long i) Writes compressed long integer to this buffer.
void	writeDouble(double v) Writes double value to this buffer.
void	writeFloat(float v) Writes float value to this buffer.
void	writeInt(int i) Writes integer to this buffer.
void	writeLong(long v) Writes long integer to this buffer.
void	writeShort(int v) Writes short integer to this buffer.
void	writeUTF(String str) Writes UTF-8 string to this buffer.
void	zero() Writes zeros over every byte in this buffer, only if the device is currently set to perform memory cleaning.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DataBuffer

public DataBuffer()

Constructs a new, empty, big endian DataBuffer instance.

DataBuffer

public DataBuffer(boolean bigEndianFlag)

Constructs a new, emtpy DataBuffer instance.

Parameters:

bigEndianFlag - If true, use big endian form for numeric data; otherwise, use little endian form.

DataBuffer

public DataBuffer(int bufferSize,
                  boolean bigEndianFlag)

Constructs a new, empty DataBuffer instance of provided initial size.

Parameters:

bufferSize - Initial size of the underlying buffer.

bigEndianFlag - If true, use big endian form for numeric data; otherwise, use little endian form.

DataBuffer

public DataBuffer(byte[] contents,
                  int offset,
                  int numBytes,
                  boolean bigEndianFlag)

Constructs a new DataBuffer instance using provided byte array as backing store.

Note: The specified byte array may contain more elements than is specified by the numBytes parameter. The numBytes parameter cannot be relied on as an accurate count.

Parameters:

contents - Data store to use for this buffer.

offset - Start of data area for the buffer; you will not be able to read or write contents[i] where i < offset.

numBytes - Length of the valid data area for the buffer; you will not be able to read or write beyond offset + numBytes (this could be less than contents.length).

bigEndianFlag - If true, use big endian form for numeric data; otherwise, use little endian form.

DataBuffer

public DataBuffer(DataBuffer contentBuffer,
                  int numBytes)

Constructs a new DataBuffer instance using provided data buffer as backing store.

This method builds a new data buffer on top of an existing one. The start of the valid data area is assumed to be the current read/write position of the provided content buffer. By the same token, this new data buffer uses the same endian form as the provided content buffer.

Parameters:

contentBuffer - Data store to use for this buffer.

numBytes - Length of the valid data area for the buffer; you will not be able to read or write beyond contentBuffer.getArrayPosition + numBytes.

Method Detail

setData

public void setData(byte[] contents,
                    int offset,
                    int numBytes)

Sets the data store for this buffer.

This method assumes the buffer will continue to use the endian form already established for this buffer.

Parameters:

contents - Data store to use for this buffer; if null, then this method sets the buffer to use a new emtpy store.

offset - Start of data area for the buffer; you will be not be able to read or write contents[i] where i < offset.

numBytes - Length of the valid data area for the buffer; you will not be able to read or write beyond offset + numBytes (this could be less than contents.length).

setData

public void setData(byte[] contents,
                    int offset,
                    int numBytes,
                    boolean bigEndianFlag)

Sets the data store for this buffer.

Parameters:

contents - Data store to use for this buffer; if null, then this method sets the buffer to use a new emtpy store.

offset - Start of data area for the buffer; you will be not be able to read or write contents[i] where i < offset.

numBytes - Length of the valid data area for the buffer; you will not be able to read or write beyond offset + numBytes (this could be less than contents.length).

bigEndianFlag - If true, use big endian form for numeric data; otherwise, use little endian form.

reset

public void reset()

Flushes and resets buffer.

This method discards its handle on the underlying data store, and resets the data buffer length, data start position, and read/write position to zero. It does not affect the actual contents of the underlying store (unless this class was the last to hold an open handle to the store).

getPosition

public int getPosition()

Retrieves current read/write position.

Note: The read/write position is relative to the first read/writeable element in the stream; this may not be the first element in the underlying data store.

Returns:

Current read/write position in this buffer.

setPosition

public void setPosition(int newPosition)

Sets current read/write position.

Note: The read/write position is relative to the first read/writeable element in the stream; this may not be the first element in the underlying data store.

Parameters:

newPosition - Sets the new read/write position for this stream; the position value gets clamped between the current start and end of this buffer.

skipBytes

public int skipBytes(int n)

Attempts to skip over some bytes in this buffer.

Invoke this method to skip the read/write position over a number of bytes in the buffer without reading or writing to them.

Specified by:

skipBytes in interface DataInput

Parameters:

n - Number of bytes to skip over.

Returns:

Number of bytes actually skipped; could be less than the number wanted to skip if the end of the buffer's data area is reached first.

getLength

public int getLength()

Returns the length of this buffer's data area.

Returns:

Number of bytes in this buffer's data area.

setLength

public void setLength(int newLength)

Sets the length of the data area for this buffer.

The buffer grows or shrinks as necessary to accomodate the new length; if the buffer shrinks past the current read/write position, it's reset to sit on the last element of the new length.

Note: This method does not affect the size of the underlying data store, unless the store needs to grow to meet the new larger size of the buffer. In this case, the underlying store gets resized to match the need.

Parameters:

newLength - New number of data bytes this buffer should contain; must not be less than zero.

ensureLength

public void ensureLength(int newLength)

Ensures the buffer has a data area of specified size.

Parameters:

newLength - New number of data bytes this buffer should contain; if this new length is less than the buffer's current length, this method does nothing.

ensureCapacity

public void ensureCapacity(int dataLength)

Ensures the buffer has sufficient data capacity left.

Warning if the entire capacity ensured is not used, you should invoke trim(false) so that the buffer length does not exceed the size of the data it contains -- functions assume that the data is the size of DataBuffer.getLength(), not the final DataBuffer.getPosition().

Parameters:

dataLenght - Number of bytes past the read/write position that this buffer should contain; if this amount is less than the buffer's current remaining amount, this method does nothing.

ensureBuffer

protected void ensureBuffer(int newLength)

Ensures the buffer is of a particular total length.

Parameters:

newLength - Desired total length of buffer (relative to element zero of the underlying store, not the read/writeable data area in the buffer). If this length is less than the current length of the underlying store, this method does nothing.

trim

public void trim()

Trims the tail of the underlying data store.

Invoke this method to trim both the buffer and the underlying store so that the last element is the current read/write position.

trim

public void trim(boolean resize)

Trims the tail of the underlying data store.

Invoke this method to trim both the buffer, and optionally the underlying store so that the last element is the current read/write position.

Parameters:

resize - True to truncate the underlying store; false to leave underlying store the same size.

Since:

BlackBerry API 4.2.0

available

public int available()

Retrieves number of elements left in the buffer beyond the read/write position.

Returns:

Number of data elements left before the end of the buffer.

eof

public boolean eof()

Determines if the read/write position is at the end of the buffer.

Returns:

True if the current read/write position is at the end of the buffer.

rewind

public void rewind()

Sets read/write position to start of this buffer's data area.

isBigEndian

public boolean isBigEndian()

Determines if this buffer writes numeric data in big endian form.

Returns:

True if this buffer uses big endian form; otherwise, false.

setBigEndian

public void setBigEndian(boolean flag)

Sets numeric data form for this buffer.

Parameters:

flag - If true, this buffer will write numeric data in big endian form; otherwise, this buffer will use little endian form.

toArray

public byte[] toArray()

Retrieves buffer data into an array.

Returns:

Array containing this buffer's data (note that this method returns only the contents of the readable data area, not any header information from this buffer's underlying store). If this buffer is empty, this method returns a zero length array.

getArray

public byte[] getArray()

Retrieves underlying store.

Invoke this method to return a handle to the underlying data store for this buffer.

You can find this buffer's data area in the store by invoking DataBuffer.getArrayStart() and DataBuffer.getLength(). You can find the buffer's read/write position within the store by invoking DataBuffer.getPosition().

Note that this buffer's data area may not be aligned with either the first or last element in the underlying data store returned by this method.

Returns:

Data store used by this buffer.

getArrayStart

public int getArrayStart()

Retrieves index in store holding first element of buffer's data area.

Returns:

Index into the underlying store that contains the first element of this buffer's data area (may or may not be zero).

getArrayPosition

public int getArrayPosition()

Retrieves index in store holding this buffer's current read/write position.

Returns:

Index into the underlying store that contains this buffer's current read/write position.

getArrayLength

public int getArrayLength()

Retrieves length of this buffer's underlying store.

Returns:

Length of the underlying store.

readByte

public byte readByte()
              throws EOFException

Retrives next byte from this buffer.

Specified by:

readByte in interface DataInput

Returns:

Next byte of data.

Throws:

EOFException - If read would put read/write position past end of the buffer.

readBoolean

public boolean readBoolean()
                    throws EOFException

Determine if next byte is non-zero.

Specified by:

readBoolean in interface DataInput

Returns:

True if next byte is non-zero; this method reads the byte before determining (thus the read/write position is moved).

Throws:

EOFException - If read would put read/write position past end of the buffer.

readChar

public char readChar()
              throws EOFException

Reads next two bytes mashed together into a character.

Specified by:

readChar in interface DataInput

Returns:

Next two bytes of data combined into a character taking into account the endian flag.

Throws:

EOFException - If read would put read/write position past end of the buffer.

readFully

public void readFully(byte[] outputBuffer)
               throws EOFException

Reads to fill provided output buffer.

If this method cannot retrieve enough data from this buffer to fill the output buffer, then it reads no data and throws an EOFException.

Specified by:

readFully in interface DataInput

Parameters:

outputBuffer - Output buffer to fill.

Throws:

EOFException - If filling the output buffer would put read/write position past end of this buffer.

readFully

public void readFully(byte[] outputBuffer,
                      int outputBufferOffset,
                      int outputBufferLength)
               throws EOFException

Reads to fill section of provided output buffer.

If this method cannot retrieve enough data from this buffer to fill the section in the output buffer, then it reads no data and throws an EOFException.

Specified by:

readFully in interface DataInput

Parameters:

outputBuffer - Output buffer containing section to fill.

outputBufferOffset - First element in output buffer to fill.

outputBufferLength - Number of elements in output buffer to fill.

Throws:

EOFException - If filling the section in the output buffer would put read/write position past end of this buffer.

readLine

public String readLine()
                throws IOException

Reads the next line of text from the input stream. It reads successive bytes, converting each byte separately into a character, until it encounters a line terminator or end of file; the characters read are then returned as a String. Note that because this method processes bytes, it does not support input of the full Unicode character set.

If end of file is encountered before even one byte can be read, then null is returned. Otherwise, each byte that is read is converted to type char by zero-extension. If the character '\n' is encountered, it is discarded and reading ceases. If the character '\r' is encountered, it is discarded and, if the following byte converts to the character '\n', then that is discarded also; reading then ceases. If end of file is encountered before either of the characters '\n' and '\r' is encountered, reading ceases. Once reading has ceased, a String is returned that contains all the characters read and not discarded, taken in order. Note that every character in this string will have a value less than ?, that is, (char)256.

Returns:

the next line of text from the input stream, or null if the end of file is encountered before a byte can be read.

Throws:

IOException - - if an I/O error occurs.

Since:

BlackBerry API 5.0.0

read

public int read(byte[] outputBuffer)

Attempts to read to fill provided output buffer.

This method reads as many characters as it can from this buffer in order to fill the provided ouput buffer.

Parameters:

outputBuffer - Output buffer to fill.

Returns:

Actual number of bytes retrieved.

read

public int read(byte[] outputBuffer,
                int outputBufferOffset,
                int outputBufferLength)

Attempts to read to fill section of provided output buffer.

This method reads as many characters as it can from this buffer in order to fill the section of the provided ouput buffer.

Parameters:

outputBuffer - Output buffer to fill.

outputBufferOffset - First element in output buffer to fill.

outputBufferLength - Number of elements in output buffer to fill.

Returns:

Actual number of bytes retrieved.

read

public int read(OutputStream outputStream)
         throws IOException

Reads this DataBuffer into the provided output stream.

Parameters:

outputStream - Output buffer to fill.

Returns:

Actual number of bytes retrieved.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If outputStream is null.

Since:

BlackBerry API 4.2.0

read

public int read(OutputStream outputStream,
                int length)
         throws IOException

Reads a section of this DataBuffer into the provided output stream.

Parameters:

outputStream - Output buffer to fill.

length - Number of bytes to place in the output buffer. If length + current position exceeds this buffer's size, will read only to the end of buffer.

Returns:

Actual number of bytes retrieved.

Throws:

IOException - If an I/O error occurs.

IllegalArgumentException - If outputStream is null or length is negative

Since:

BlackBerry API 4.2.0

readByteArray

public byte[] readByteArray()
                     throws IOException

Reads byte array from this buffer.

This method expects the next data to read from the buffer is a byte array written with DataBuffer.writeByteArray(byte[]). That is, first the length of the array is read out as a compressed integer, and then the data of the array is read out of the buffer.

Returns:

Byte array stored in this buffer.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

IOException

readInt

public int readInt()
            throws EOFException

Reads next four bytes as an integer.

Specified by:

readInt in interface DataInput

Returns:

Integer value.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

readLong

public long readLong()
              throws EOFException

Reads next eight bytes as a long integer.

Specified by:

readLong in interface DataInput

Returns:

Long integer value.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

readFloat

public final float readFloat()
                      throws IOException

Reads next four bytes as a float value.

Specified by:

readFloat in interface DataInput

Returns:

Float value.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

IOException - if an I/O error occurs.

Since:

BlackBerry API 4.0.0

readDouble

public final double readDouble()
                        throws IOException

Reads next eight bytes as a double value.

Specified by:

readDouble in interface DataInput

Returns:

Double value.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

IOException - if an I/O error occurs.

Since:

BlackBerry API 4.0.0

readShort

public short readShort()
                throws EOFException

Reads next two bytes as a short integer.

Specified by:

readShort in interface DataInput

Returns:

Short integer value.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

readUnsignedByte

public int readUnsignedByte()
                     throws EOFException

Reads next single byte as an unsigned byte value.

Specified by:

readUnsignedByte in interface DataInput

Returns:

Zero extends read byte, thus returning an integer with a value between zero and 256.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

readUnsignedShort

public int readUnsignedShort()
                      throws EOFException

Reads next two bytes as an unsigned short value.

Specified by:

readUnsignedShort in interface DataInput

Returns:

Zero extends read bytes, thus returning an integer with a value between zero and 65535.

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

readUTF

public String readUTF()
               throws IOException

Reads UTF-8 string.

Expects to read a string written into this buffer with DataBuffer.writeUTF(String).

Specified by:

readUTF in interface DataInput

Returns:

Unicode string.

Throws:

IOException - if an I/O error occurs.

readCompressedInt

public int readCompressedInt()
                      throws EOFException

Reads compressed integer.

Expects to read a compressed integer written into this buffer with DataBuffer.writeCompressedInt(int).

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

readCompressedLong

public long readCompressedLong()
                        throws EOFException

Reads compressed long integer.

Expects to read a compressed long integer written into this buffer with DataBuffer.writeCompressedLong(long).

Throws:

EOFException - If the read would put the read/write position past the end of the buffer.

write

public void write(byte[] b)

Writes byte array to this buffer.

This method increases the size of this buffer as necessary to contain the data.

Specified by:

write in interface DataOutput

Parameters:

b - Byte array to write to this buffer.

write

public void write(byte[] b,
                  int off,
                  int len)

Writes section of byte array to this buffer.

This method increases the size of this buffer as necessary to contain the data.

Specified by:

write in interface DataOutput

Parameters:

b - Byte array containing section to write to this buffer.

off - First element of array to write.

length - Number of elements from array to write.

write

public void write(DataBuffer dataBuffer,
                  int length)

Writes section of data buffer to this buffer.

This method reads data from the provided data buffer, starting at its read/write position, and writes the data into this buffer.

Parameters:

dataBuffer - Source data buffer.

length - Number of bytes to read from the source buffer.

write

public void write(InputStream input)
           throws IOException

Writes input stream data to this buffer.

Parameters:

input - Source input stream.

Throws:

IOException - If an I/O error occurs.

write

public void write(InputStream input,
                  int length)
           throws IOException

Writes some data from input stream to this buffer.

Parameters:

input - Source input stream.

length - Number of bytes to read from input stream.

Throws:

IOException - If an I/O error occurs.

write

public void write(DataInput input,
                  int length)
           throws IOException

Writes some data from data input to this buffer.

Note that this is not an efficient method to use; you would be better off to employ DataBuffer.write(InputStream,int) if possible.

Parameters:

input - Source for data.

length - Number of bytes to read from source.

Throws:

IOException - If an I/O error occurs.

EOFException - If this method reached the end of file in the data buffer parameter before it could read the desired number of bytes.

write

public void write(int b)

Writes single byte to this buffer.

This method uses the eight low-order bits of the provided integer as the byte to write to this buffer.

Specified by:

write in interface DataOutput

Parameters:

b - Integer to use as source of data.

writeBoolean

public void writeBoolean(boolean v)

Writes boolean to this buffer.

Writing a boolean value adds one byte to this buffer.

Specified by:

writeBoolean in interface DataOutput

Parameters:

v - Boolean value to write.

writeByte

public void writeByte(int v)

Writes single byte to this buffer.

This method uses the eight low-order bits of the provided integer as the byte to write to this buffer.

Specified by:

writeByte in interface DataOutput

Parameters:

b - Integer to use as source of data.

writeBytes

public void writeBytes(String s)

Writes a string to the output stream. For every character in the string s, taken in order, one byte is written to the output stream. If s is null, a NullPointerException is thrown. If s.length is zero, then no bytes are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, one byte is written, the low-order byte, in exactly the manner of the writeByte method . The high-order eight bits of each character in the string are ignored.

Parameters:

s - the string of bytes to be written

Since:

BlackBerry API 5.0.0

writeChar

public void writeChar(int v)

Writes character to this buffer.

Writing a character adds two bytes to this buffer.

Specified by:

writeChar in interface DataOutput

Parameters:

v - Character value to write.

writeChars

public void writeChars(String s)

Writes characters in string to this buffer.

This method writes each character in the provided string to this buffer, one character at a time, two bytes per character.

Specified by:

writeChars in interface DataOutput

Parameters:

s - String to use as source of character data.

writeByteArray

public void writeByteArray(byte[] b)

Writes byte array to this buffer.

This method first adds a compressed integer into this buffer (with DataBuffer.writeCompressedInt(int)) that encodes the length of the byte array; then it writes the byte array itself into this buffer.

Use DataBuffer.readByteArray() to peel the byte array's data out of the buffer (that method also reads from the buffer, but does not return, the compressed int).

Parameters:

b - Byte array to write.

Throws:

IndexOutOfBounds - If offset + length is greater than the length of the byte array, the offset is less than 0, or the length is less than 0.

writeByteArray

public void writeByteArray(byte[] b,
                           int offset,
                           int length)

Writes section of byte array to this buffer.

This method first adds a compressed integer into this buffer (with DataBuffer.writeCompressedInt(int)) that encodes the length of the byte array section to write; then it writes the byte array section itself into this buffer.

Use DataBuffer.readByteArray() to peel the byte array's data out of the buffer (that method also reads from the buffer, but does not return, the compressed int).

Parameters:

b - Byte array to write.

offset - First element in the byte array to write.

length - Number of bytes to write.

Throws:

IndexOutOfBounds - If offset + length is greater than the length of the byte array, the offset is less than 0, or the length is less than 0.

writeByteArray

public void writeByteArray(byte[] b,
                           int offset,
                           int length,
                           boolean writeLength)

Writes section of byte array to this buffer.

When the writeLength parameter is true; This method first adds a compressed integer into this buffer (with DataBuffer.writeCompressedInt(int)) that encodes the length of the byte array section to write; then it writes the byte array section itself into this buffer.

When the writeLength parameter is false; the byte array is written into the buffer with no preceding values.

Use DataBuffer.readByteArray() to peel the byte array's data out of the buffer (that method also reads from the buffer, but does not return, the compressed int).

Parameters:

b - Byte array to write.

offset - First element in the byte array to write.

length - Number of bytes to write.

writeLength - true to write the length of the array into the buffer before the array, false otherwise

Throws:

IndexOutOfBounds - If offset + length is greater than the length of the byte array, the offset is less than 0, or the length is less than 0.

Since:

BlackBerry API 4.3.0

writeInt

public void writeInt(int i)

Writes integer to this buffer.

Writing an integer adds four bytes to this buffer.

Specified by:

writeInt in interface DataOutput

Parameters:

i - Integer value to write.

writeLong

public void writeLong(long v)

Writes long integer to this buffer.

Writing a long integer adds eight bytes to this buffer.

Specified by:

writeLong in interface DataOutput

Parameters:

v - Long integer value to write.

writeFloat

public final void writeFloat(float v)

Writes float value to this buffer.

Writing a float adds four bytes to this buffer.

Specified by:

writeFloat in interface DataOutput

Parameters:

v - Float value to write.

Since:

BlackBerry API 4.0.0

writeDouble

public final void writeDouble(double v)

Writes double value to this buffer.

Writing a double adds eight bytes to this buffer.

Specified by:

writeDouble in interface DataOutput

Parameters:

v - Double value to write.

Since:

BlackBerry API 4.0.0

writeShort

public void writeShort(int v)

Writes short integer to this buffer.

Writing a short integer adds two bytes to this buffer.

Specified by:

writeShort in interface DataOutput

Parameters:

v - SHort integer value to write.

writeUTF

public void writeUTF(String str)
              throws IOException

Writes UTF-8 string to this buffer.

This method writes two bytes of length information to this buffer, followed by the Java-modified UTF representation of every character in the string.

Specified by:

writeUTF in interface DataOutput

Parameters:

str - String used as source of character data.

Throws:

IOException - if an I/O error occurs.

writeCompressedInt

public void writeCompressedInt(int i)

Writes compressed integer to this buffer.

This method writes a variable number of bytes between one and five, depending on the amount of compression possible for the integer value. The value is built using big endian form. A simple more-bit technique is employed, whereby the top bit is set if the next byte contains more of the integer. Each byte contains seven bits of the integer.

Parameters:

i - Integer value to compress.

getCompressedIntSize

public static int getCompressedIntSize(int i)

Retrieves the number of bytes needed to compress an integer value.

Parameters:

i - Integer value to check.

Returns:

Number of bytes required to hold compressed form of provided integer: a simple more-bit technique is employed, whereby the top bit is set if the next byte contains more of the integer. Each byte contains seven bits of the integer. Storing a compressed integer, therefore, takes from one to five bytes.

writeCompressedLong

public void writeCompressedLong(long i)

Writes compressed long integer to this buffer.

This method writes a variable number of bytes between one and nine, depending on the amount of compression possible for the long integer value. The value is built using big endian form. A simple more-bit technique is employed, whereby the top bit is set if the next byte contains more of the long integer. Each byte contains seven bits of the long integer.

Parameters:

i - Long integer value to compress.

zero

public void zero()

Writes zeros over every byte in this buffer, only if the device is currently set to perform memory cleaning.

Note: Historically, this method would not always wipe this buffer; it would only do so under certain circumstances. First, the device must have had its memory cleaning mode activated; then, invoking this method would clean the buffer. If memory cleaning was not active, then invoking this method would explicitly do nothing.

This method's current implementation preserves that behaviour by now being a convenience method around zero(false).

If you want to zero out the contents of a buffer immediately upon invocation (regardless of the state of memory cleaning), then you should revise your code to invoke zero(true) instead.

Since:

BlackBerry API 4.0.0