com.ibm.wbi.util
Class ByteBufferUnsynchronized

java.lang.Object
  |
  +--com.ibm.wbi.util.ByteBufferUnsynchronized
All Implemented Interfaces:
ByteStore

public final class ByteBufferUnsynchronized
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
ByteBufferUnsynchronized()
          Constructs a ByteBufferUnsynchronized that is initially empty.
ByteBufferUnsynchronized(int cap)
          Constructs a ByteBufferUnsynchronized with specified initial capacity.
 
Method Summary
 void append(byte val)
          Appends the given byte argument to this buffer.
 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 buffer.
 byte byteAt(int index)
          Returns the byte at a specific index in this buffer.
 int capacity()
          Returns the current capacity.
 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 buffer.
 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 buffer into the destination byte array dst.
 void insert(int offset, byte val)
          Inserts the given byte argument into this buffer.
 void insert(int offset, byte[] bytes)
          Inserts the given byte array argument into this buffer.
 int length()
          Returns the length (byte count).
 long longAt(int index)
          Returns the long at a specific index in this buffer.
 void purge()
          The current contents are released and an empty ByteBufferUnsynchronized with a default capacity of is created.
 void purge(int capacity)
          The current contents are released and an empty ByteBufferUnsynchronized with the specified capacity is created.
 void setByteAt(int index, byte val)
          The byte at the specified index of this buffer is set to val .
 void setLength(int newLength)
          Sets the length of this buffer.
 int size()
          Returns the length (byte count).
 void write(java.io.OutputStream stream)
          Writes the bytes contained in the buffer to an OutputStream.
 void write(java.io.OutputStream stream, int offset, int length)
          Writes some of the bytes contained in the buffer 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

ByteBufferUnsynchronized

public ByteBufferUnsynchronized()
Constructs a ByteBufferUnsynchronized that is initially empty.

ByteBufferUnsynchronized

public ByteBufferUnsynchronized(int cap)
Constructs a ByteBufferUnsynchronized with specified initial capacity.
Parameters:
cap - Initial capacity.
Method Detail

purge

public void purge()
The current contents are released and an empty ByteBufferUnsynchronized with a default capacity of is created.
Specified by:
purge in interface ByteStore

purge

public void purge(int capacity)
The current contents are released and an empty ByteBufferUnsynchronized 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).
Specified by:
length in interface ByteStore
Returns:
The number of bytes.

size

public int size()
Returns the length (byte count). This method returns the same information as length().
Specified by:
size in interface ByteStore
Returns:
The number of bytes.

capacity

public int capacity()
Returns the current capacity. 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.

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 buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: 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 buffer. If the newLength argument is less than the current length of the buffer, the buffer 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 buffer.

The first byte of the buffer 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 buffer.

Specified by:
byteAt in interface ByteStore
Parameters:
index - The index of the desired byte.
Returns:
The byte at the specified index of this buffer.
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 buffer.

The first byte of the buffer 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 buffer. The long must be in the buffer 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 buffer.
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 buffer. Since is useful for avoiding a copy, but must be used carefully. Subsequent changes to the buffer 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 buffer.
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 buffer 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 buffer.
srcEnd - Stop copying at this offset in the buffer.
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 buffer 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 buffer.

The argument is appended to the contents of this buffer. The length of this buffer 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 buffer.

The argument is appended to the contents of this buffer. The length of this buffer 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 buffer. 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 buffer 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 buffer.

The bytes of the array argument are inserted into the contents of this buffer at the position indicated by offset. The length of this buffer 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 buffer.

The second argument is inserted into the contents of this byte buffer at the position indicated by offset. The length of this buffer 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 buffer to an OutputStream. Note that this method may block indefinitely on a write() call, causing any other threads attempting to use or modify this buffer 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 buffer to an OutputStream. Note that this method may block indefinitely on a write() call, causing any other threads attempting to use or modify this buffer 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.