com.ibm.wbi.util
Class ByteBuffer

java.lang.Object
  |
  +--com.ibm.wbi.util.ByteBuffer

All Implemented Interfaces:

ByteStore

public final class ByteBuffer

extends java.lang.Object

implements ByteStore

This class is something like java.lang.StringBuffer, except that it provides a buffer of bytes instead of char s. The provided append methods automatically allocate storage (when the internal capacity is exceeded) before adding data. It's useful for building up arbitrary length byte arrays.

Field Summary

static int

DEFAULT_SIZE The default initial capacity.

Constructor Summary

ByteBuffer()
Constructs a ByteBuffer that is initially empty, with a default capacity of 512 bytes.

ByteBuffer(byte[] data)
Constructs a ByteBuffer containing the given bytes, with a capacity a bit bigger than the array.

ByteBuffer(byte[] data, int offset, int length)
Constructs a ByteBuffer containing the given bytes, with a capacity a bit bigger than the array.

ByteBuffer(int capacity)
Constructs a ByteBuffer that is initially empty, with the given capacity.

ByteBuffer(java.lang.String string)
Constructs a ByteBuffer from the passed String.

ByteBuffer(java.lang.StringBuffer stringBuffer)
Constructs a ByteBuffer from the passed StringBuffer.

ByteBuffer(java.lang.StringBuffer stringBuffer, java.lang.String encoding)
Constructs a ByteBuffer from the passed StringBuffer.

ByteBuffer(java.lang.String string, java.lang.String encoding)
Constructs a ByteBuffer from the passed String.

Method Summary

void	append(byte val) Appends the given byte argument to this ByteBuffer.
void	append(byte[] bytes) Appends the given byte array argument to this string buffer.
void	append(byte[] bytes, int offset, int length) Appends the given byte subarray of the bytes array argument to this buffer.
void	append(long val) Appends the given long argument to this ByteBuffer.
byte	byteAt(int index) Returns the byte at a specific index in this ByteBuffer.
int	capacity() Returns the current capacity of the ByteBuffer.
void	ensureCapacity(int minimumCapacity) Ensures that the capacity of the buffer is at least equal to the specified minimum.
byte[]	getByteArrayRef() Return a reference to the byte array inside the ByteBuffer.
byte[]	getBytes() Return a byte array of the current buffer size containing the bytes.
void	getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin) Bytes are copied from this ByteBuffer into the destination byte array dst.
void	insert(int offset, byte val) Inserts the given byte argument into this ByteBuffer.
void	insert(int offset, byte[] bytes) Inserts the given byte array argument into this ByteBuffer.
int	length() Returns the length (byte count) of this ByteBuffer.
long	longAt(int index) Returns the long at a specific index in this ByteBuffer.
void	purge() The current contents are released and an empty ByteBuffer with a default capacity of 256 characters is created.
void	purge(int capacity) The current contents are released and an empty ByteBuffer with the specified capacity is created.
void	setByteAt(int index, byte val) The byte at the specified index of this ByteBuffer is set to val .
void	setLength(int newLength) Sets the length of this ByteBuffer.
int	size() Returns the length (byte count) of this ByteBuffer.
void	write(java.io.OutputStream stream) Writes the bytes contained in the ByteBuffer to an OutputStream.
void	write(java.io.OutputStream stream, int offset, int length) Writes some of the bytes contained in the ByteBuffer to an OutputStream.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SIZE

public static final int DEFAULT_SIZE

The default initial capacity.

Constructor Detail

ByteBuffer

public ByteBuffer()

Constructs a ByteBuffer that is initially empty, with a default capacity of 512 bytes.

ByteBuffer

public ByteBuffer(int capacity)

Constructs a ByteBuffer that is initially empty, with the given capacity.

Parameters:

capacity - The initial capacity.

ByteBuffer

public ByteBuffer(byte[] data)

Constructs a ByteBuffer containing the given bytes, with a capacity a bit bigger than the array.

Parameters:

data - The initial contents of the ByteBuffer.

ByteBuffer

public ByteBuffer(byte[] data,
                  int offset,
                  int length)

Constructs a ByteBuffer containing the given bytes, with a capacity a bit bigger than the array.

Parameters:

data - The initial contents of the ByteBuffer.

offset - The starting offset in data of the bytes to be placed in the buffer.

length - The number of bytes, starting at offset, of the bytes to be placed in the buffer.

ByteBuffer

public ByteBuffer(java.lang.StringBuffer stringBuffer)

Constructs a ByteBuffer from the passed StringBuffer. The default character encoding will be used during char to byte conversions.

Parameters:

stringBuffer - A reference to a StringBuffer object. This object will be used to fill the newly created ByteBuffer object.

ByteBuffer

public ByteBuffer(java.lang.StringBuffer stringBuffer,
                  java.lang.String encoding)
           throws java.io.UnsupportedEncodingException

Constructs a ByteBuffer from the passed StringBuffer. The passed character encoding will be used during char to byte conversions.

Parameters:

stringBuffer - A reference to a StringBuffer object. This object will be used to fill the newly created ByteBuffer object.

encoding - A character encoding string to be used when converting char's within the StringBuffer to bytes.

Throws:

java.io.UnsupportedEncodingException - The provided encoding is invalid.

ByteBuffer

public ByteBuffer(java.lang.String string)

Constructs a ByteBuffer from the passed String. The default character encoding will be used during char to byte conversions.

Parameters:

string - A reference to a String object. This object will be used to fill the newly created ByteBuffer object.

ByteBuffer

public ByteBuffer(java.lang.String string,
                  java.lang.String encoding)
           throws java.io.UnsupportedEncodingException

Constructs a ByteBuffer from the passed String. The passed character encoding will be used during char to byte conversions.

Parameters:

string - A reference to a String object. This object will be used to fill the newly created ByteBuffer object.

encoding - A character encoding string to be used when converting char's within the StringBuffer to bytes.

Throws:

java.io.UnsupportedEncodingException - The provided encoding is invalid.

Method Detail

purge

public void purge()

The current contents are released and an empty ByteBuffer with a default capacity of 256 characters is created.

Specified by:

purge in interface ByteStore

purge

public void purge(int capacity)

The current contents are released and an empty ByteBuffer with the specified capacity is created.

Specified by:

purge in interface ByteStore

Parameters:

capacity - The initial capacity.

length

public int length()

Returns the length (byte count) of this ByteBuffer.

Specified by:

length in interface ByteStore

Returns:

The number of bytes in the ByteBuffer.

size

public int size()

Returns the length (byte count) of this ByteBuffer. This method returns the same information as length().

Specified by:

size in interface ByteStore

Returns:

The number of bytes in the ByteBuffer.

capacity

public int capacity()

Returns the current capacity of the ByteBuffer. The capacity is the amount of storage available for newly inserted bytes. If more are added (i.e. via append()), an expansion will occur.

Specified by:

capacity in interface ByteStore

Returns:

The current capacity of this ByteBuffer.

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Ensures that the capacity of the buffer is at least equal to the specified minimum. If the current capacity of the ByteBuffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of:

• The minimumCapacity argument.
• Twice the old capacity, plus 2.

If the minimumCapacity argument is nonpositive, this method takes no action and simply returns.

Specified by:

ensureCapacity in interface ByteStore

Parameters:

minimumCapacity - The minimum desired capacity.

setLength

public void setLength(int newLength)
               throws java.lang.StringIndexOutOfBoundsException

Sets the length of this ByteBuffer. If the newLength argument is less than the current length of the ByteBuffer, the ByteBuffer is truncated to contain exactly the number of characters given by the newLength argument.

If the newLength argument is greater than or equal to the current length, sufficient null bytes will be appended to the byte buffer so that length becomes equal to the newLength argument.

The newLength argument must be greater than or equal to 0.

Specified by:

setLength in interface ByteStore

Parameters:

newLength - The new length of the buffer.

Throws:

java.lang.StringIndexOutOfBoundsException - The newLength argument is invalid

byteAt

public byte byteAt(int index)
            throws java.lang.ArrayIndexOutOfBoundsException

Returns the byte at a specific index in this ByteBuffer.

The first byte of the ByteBuffer is considered to be at index 0, the next at index 1, and so on, for array indexing.

The index argument must be greater than or equal to 0, and less than the length of this ByteBuffer.

Specified by:

byteAt in interface ByteStore

Parameters:

index - The index of the desired byte.

Returns:

The byte at the specified index of this ByteBuffer.

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index is invalid.

longAt

public long longAt(int index)
            throws java.lang.ArrayIndexOutOfBoundsException

Returns the long at a specific index in this ByteBuffer.

The first byte of the ByteBuffer is considered to be at index 0, the next at index 1, and so on, for array indexing.

The index argument must be greater than or equal to 0, and less than the length of this ByteBuffer. The long must be in the ByteBuffer in the format used by our append(long val) method.

Parameters:

index - The index of the first byte of the desired long.

Returns:

The long at the specified index of this ByteBuffer.

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index is invalid.

getBytes

public byte[] getBytes()

Return a byte array of the current buffer size containing the bytes. The returned array will be newly created with a copy of the buffered bytes.

Specified by:

getBytes in interface ByteStore

Returns:

A byte array with a length equal to the length of the buffered array, containing the buffered bytes.

getByteArrayRef

public byte[] getByteArrayRef()

Return a reference to the byte array inside the ByteBuffer. Since is useful for avoiding a copy, but must be used carefully. Subsequent changes to the ByteBuffer may affect the returned array, but are not guaranteed to. Furthermore, the returned array may be larger than the number of bytes contained in this ByteBuffer.

Specified by:

getByteArrayRef in interface ByteStore

Returns:

A byte array, possibly longer than the length of the buffered array, containing the buffered bytes starting at index zero.

getBytes

public void getBytes(int srcBegin,
                     int srcEnd,
                     byte[] dst,
                     int dstBegin)
              throws java.lang.ArrayIndexOutOfBoundsException

Bytes are copied from this ByteBuffer into the destination byte array dst. The first byte to be copied is at index srcBegin; the last byte to be copied is at index srcEnd-1. The total number of bytes to be copied is srcEnd-srcBegin. The bytes are copied into the subarray of dst starting at index dstBegin and ending at index:

    dstbegin + (srcEnd-srcBegin) - 1
 

Specified by:

getBytes in interface ByteStore

Parameters:

srcBegin - Start copying at this offset in the ByteBuffer.

srcEnd - Stop copying at this offset in the ByteBuffer.

dst - The array to copy the data into.

dstBegin - Offset into dst.

Throws:

java.lang.ArrayIndexOutOfBoundsException - There is an invalid index into the buffer.

setByteAt

public void setByteAt(int index,
                      byte val)
               throws java.lang.ArrayIndexOutOfBoundsException

The byte at the specified index of this ByteBuffer is set to val .

Specified by:

setByteAt in interface ByteStore

Parameters:

index - The index of the byte to overwrite.

val - The new byte value.

Throws:

java.lang.ArrayIndexOutOfBoundsException - The index is invalid.

append

public void append(byte val)

Appends the given byte argument to this ByteBuffer.

The argument is appended to the contents of this ByteBuffer. The length of this ByteBuffer increases by 1.

Specified by:

append in interface ByteStore

Parameters:

val - A byte value.

append

public void append(long val)

Appends the given long argument to this ByteBuffer.

The argument is appended to the contents of this ByteBuffer. The length of this ByteBuffer increases by 8. This long can be retrieved with the longAt() method.

Parameters:

val - A long value.

append

public void append(byte[] bytes)

Appends the given byte array argument to this string buffer.

The bytes of the array argument are appended, in order, to the contents of this ByteBuffer. The length of this ByteBuffer increases by the length of the argument.

Specified by:

append in interface ByteStore

Parameters:

bytes - The bytes to be appended.

append

public void append(byte[] bytes,
                   int offset,
                   int length)

Appends the given byte subarray of the bytes array argument to this buffer.

Bytes of the byte array bytes, starting at index offset, are appended, in order, to the contents of this byte buffer. The length of this ByteBuffer increases by the value of length.

Specified by:

append in interface ByteStore

Parameters:

bytes - The bytes to be appended.

offset - The index of the first byte to append.

length - The number of bytes to append.

insert

public void insert(int offset,
                   byte[] bytes)
            throws java.lang.ArrayIndexOutOfBoundsException

Inserts the given byte array argument into this ByteBuffer.

The bytes of the array argument are inserted into the contents of this ByteBuffer at the position indicated by offset. The length of this ByteBuffer increases by the length of the argument.

Specified by:

insert in interface ByteStore

Parameters:

offset - The offset.

bytes - A byte array.

Throws:

java.lang.ArrayIndexOutOfBoundsException - There is an invalid index into the buffer.

insert

public void insert(int offset,
                   byte val)

Inserts the given byte argument into this ByteBuffer.

The second argument is inserted into the contents of this byte buffer at the position indicated by offset. The length of this ByteBuffer increases by one.

The offset argument must be greater than or equal to 0, and less than or equal to the length of this ByteBuffer.

Specified by:

insert in interface ByteStore

Parameters:

offset - The offset.

val - The byte value.

write

public void write(java.io.OutputStream stream)
           throws java.io.IOException,
                  java.lang.ArrayIndexOutOfBoundsException

Writes the bytes contained in the ByteBuffer to an OutputStream. Note that this method may block indefinitely on a write() call, causing any other threads attempting to use or modify this ByteBuffer to also block until this operation is complete. All bytes will be written before returning.

Parameters:

stream - OutputStream to which bytes should be written.

Throws:

java.io.IOException - The write() failed.

java.lang.ArrayIndexOutOfBoundsException - The index is invalid.

write

public void write(java.io.OutputStream stream,
                  int offset,
                  int length)
           throws java.io.IOException,
                  java.lang.ArrayIndexOutOfBoundsException

Writes some of the bytes contained in the ByteBuffer to an OutputStream. Note that this method may block indefinitely on a write() call, causing any other threads attempting to use or modify this ByteBuffer to also block until this operation is complete. All bytes indicated by the given offset and length will be written before return.

Parameters:

stream - OutputStream to which bytes should be written.

offset - Offset of the first byte from the buffer to be written.

length - Number of bytes from the buffer to be written.

Throws:

java.io.IOException - The write() failed.

java.lang.ArrayIndexOutOfBoundsException - The index is invalid.