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:

• 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 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.