|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--net.rim.device.api.util.DataBuffer
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(DataBuffer contentBuffer,
int numBytes)
Constructs a new DataBuffer instance using provided data buffer as backing store. |
||
DataBuffer(int bufferSize,
boolean bigEndianFlag)
Constructs a new, empty DataBuffer instance of provided initial size. |
||
| 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 byte as 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. |
|
long |
readLong()
Reads next eight bytes as a long integer. |
|
short |
readShort()
Reads next two bytes as a short integer. |
|
int |
readUnsignedByte()
Reads next single byte as an unsigned byte value. |
|
int |
readUnsignedShort()
Reads next two bytes as an unsigned short value. |
|
String |
readUTF()
Reads UTF-8 string. |
|
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(DataBuffer dataBuffer,
int length)
Writes section of data buffer 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(int b)
Writes single byte 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 |
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()
Sets the contents of the DataBuffer to zero Bytes equal to the number retrieved from getLength() are converted to zeros. |
|
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public DataBuffer(boolean bigEndianFlag)
bigEndianFlag - If true, use big endian form for numeric data;
otherwise, use little endian form.
public DataBuffer(byte[] contents,
int offset,
int numBytes,
boolean bigEndianFlag)
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.
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.public DataBuffer(DataBuffer contentBuffer, int numBytes)
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.
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.
public DataBuffer(int bufferSize,
boolean bigEndianFlag)
bufferSize - Initial size of the underlying buffer.bigEndianFlag - If true, use big endian form for numeric data;
otherwise, use little endian form.| Method Detail |
public int available()
protected void ensureBuffer(int newLength)
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.public void ensureCapacity(int dataLength)
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 getLength(), not the final
getPosition().
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.public void ensureLength(int newLength)
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.public boolean eof()
public byte[] getArray()
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
getArrayStart() and getLength(). You can find the buffer's
read/write position within the store by invoking 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.
public int getArrayLength()
public int getArrayPosition()
public int getArrayStart()
public static int getCompressedIntSize(int i)
i - Integer value to check.public int getLength()
public int getPosition()
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.
public boolean isBigEndian()
public int read(byte[] outputBuffer)
This method reads as many characters as it can from this buffer in order to fill the provided ouput buffer.
outputBuffer - Output buffer to fill.
public int read(byte[] outputBuffer,
int outputBufferOffset,
int outputBufferLength)
This method reads as many characters as it can from this buffer in order to fill the section of the provided ouput buffer.
outputBuffer - Output buffer to fill.outputBufferOffset - First element in output buffer to fill.outputBufferLength - Number of elements in output buffer to fill.public int read(OutputStream outputStream) throws IOException
outputStream - Output buffer to fill.IOException - If an I/O error occurs.IllegalArgumentException - If outputStream is null.public int read(OutputStream outputStream, int length) throws IOException
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.IOException - If an I/O error occurs.IllegalArgumentException - If outputStream is null or length is negative
public boolean readBoolean()
throws EOFException
EOFException - If read would put read/write position past end of
the buffer.
public byte readByte()
throws EOFException
EOFException - If read would put read/write position past end of
the buffer.
public byte[] readByteArray()
throws IOException
This method expects the next data to read from the buffer is a byte
array written with 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.
EOFException - If the read would put the read/write position past
the end of the buffer.
public char readChar()
throws EOFException
EOFException - If read would put read/write position past end of
the buffer.
public int readCompressedInt()
throws EOFException
Expects to read a compressed integer written into this buffer with
writeCompressedInt(int).
EOFException - If the read would put the read/write position past
the end of the buffer.
public long readCompressedLong()
throws EOFException
Expects to read a compressed long integer written into this buffer with
writeCompressedLong(long).
EOFException - If the read would put the read/write position past
the end of the buffer.
public final double readDouble()
throws IOException
EOFException - If the read would put the read/write position past
the end of the buffer.
public final float readFloat()
throws IOException
EOFException - If the read would put the read/write position past
the end of the buffer.
public void readFully(byte[] outputBuffer)
throws EOFException
If this method cannot retrieve enough data from this buffer to fill
the output buffer, then it reads no data and throws an
EOFException.
outputBuffer - Output buffer to fill.EOFException - If filling the output buffer would put read/write
position past end of this buffer.
public void readFully(byte[] outputBuffer,
int outputBufferOffset,
int outputBufferLength)
throws EOFException
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.
outputBuffer - Output buffer containing section to fill.outputBufferOffset - First element in output buffer to fill.outputBufferLength - Number of elements in output buffer to fill.EOFException - If filling the section in the output buffer would
put read/write position past end of this buffer.
public int readInt()
throws EOFException
EOFException - If the read would put the read/write position past
the end of the buffer.
public long readLong()
throws EOFException
EOFException - If the read would put the read/write position past
the end of the buffer.
public short readShort()
throws EOFException
EOFException - If the read would put the read/write position past
the end of the buffer.
public int readUnsignedByte()
throws EOFException
EOFException - If the read would put the read/write position past
the end of the buffer.
public int readUnsignedShort()
throws EOFException
EOFException - If the read would put the read/write position past
the end of the buffer.public String readUTF() throws IOException
Expects to read a string written into this buffer with writeUTF(java.lang.String).
public void reset()
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).
public void setBigEndian(boolean flag)
flag - If true, this buffer will write numeric data in big endian
form; otherwise, this buffer will use little endian form.
public void setData(byte[] contents,
int offset,
int numBytes)
This method assumes the buffer will continue to use the endian form already established for this buffer.
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).
public void setData(byte[] contents,
int offset,
int numBytes,
boolean bigEndianFlag)
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.public void setLength(int newLength)
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.
newLength - New number of data bytes this buffer should contain;
must not be less than zero.public void setPosition(int newPosition)
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.
newPosition - Sets the new read/write position for this stream; the
position value gets clamped between the current start and end of this
buffer.public int skipBytes(int n)
Invoke this method to skip the read/write position over a number of bytes in the buffer without reading or writing to them.
n - Number of bytes to skip over.public byte[] toArray()
public void trim()
Invoke this method to trim both the buffer and the underlying store so that the last element is the current read/write position.
public void trim(boolean resize)
Invoke this method to trim both the buffer, and optionally the underlying store so that the last element is the current read/write position.
resize - True to truncate the underlying store; false to leave
underlying store the same size.public void write(byte[] b)
This method increases the size of this buffer as necessary to contain the data.
b - Byte array to write to this buffer.
public void write(byte[] b,
int off,
int len)
This method increases the size of this buffer as necessary to contain the data.
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.public void write(DataBuffer dataBuffer, int length)
This method reads data from the provided data buffer, starting at its read/write position, and writes the data into this buffer.
dataBuffer - Source data buffer.length - Number of bytes to read from the source buffer.public void write(DataInput input, int length) throws IOException
Note that this is not an efficient method to use; you would be better
off to employ write(InputStream,int) if possible.
input - Source for data.length - Number of bytes to read from source.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.public void write(InputStream input) throws IOException
input - Source input stream.IOException - If an I/O error occurs.public void write(InputStream input, int length) throws IOException
input - Source input stream.length - Number of bytes to read from input stream.IOException - If an I/O error occurs.public void write(int b)
This method uses the eight low-order bits of the provided integer as the byte to write to this buffer.
b - Integer to use as source of data.public void writeBoolean(boolean v)
Writing a boolean value adds one byte to this buffer.
v - Boolean value to write.public void writeByte(int v)
This method uses the eight low-order bits of the provided integer as the byte to write to this buffer.
b - Integer to use as source of data.public void writeByteArray(byte[] b)
This method first adds a compressed integer into this buffer (with
writeCompressedInt(int)) that encodes the length of the byte array;
then it writes the byte array itself into this buffer.
Use 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).
b - Byte array to write.
public void writeByteArray(byte[] b,
int offset,
int length)
This method first adds a compressed integer into this buffer (with
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 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).
b - Byte array to write.offset - First element in the byte array to write.length - Number of bytes to write.
public void writeByteArray(byte[] b,
int offset,
int length,
boolean writeLength)
When the writeLength parameter is true; This method first adds a compressed
integer into this buffer (with 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 wrriten into the buffer with no preceding values.
Use 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).
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 otherwiseIndexOutOfBounds - 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.public void writeChar(int v)
Writing a character adds two bytes to this buffer.
v - Character value to write.public void writeChars(String s)
This method writes each character in the provided string to this buffer, one character at a time, two bytes per character.
s - String to use as source of character data.public void writeCompressedInt(int i)
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.
i - Integer value to compress.public void writeCompressedLong(long i)
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.
i - Long integer value to compress.public final void writeDouble(double v)
Writing a double adds eight bytes to this buffer.
v - Double value to write.public final void writeFloat(float v)
Writing a float adds four bytes to this buffer.
v - Float value to write.public void writeInt(int i)
Writing an integer adds four bytes to this buffer.
i - Integer value to write.public void writeLong(long v)
Writing a long integer adds eight bytes to this buffer.
v - Long integer value to write.public void writeShort(int v)
Writing a short integer adds two bytes to this buffer.
v - SHort integer value to write.public void writeUTF(String str) throws IOException
This method writes two bytes of length information to this buffer, followed by the Java-modified UTF represenation of every character in the string.
str - String used as source of character data.public void zero()
Bytes equal to the number retrieved from
getLength() are converted to zeros.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2007 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.