com.objsys.xbinder.runtime

Class XBByteArray

java.lang.Object

com.objsys.xbinder.runtime.XBByteArray

public class XBByteArray
extends java.lang.Object

XBByteArray is a lightweight wrapper around a byte array. It is intended to help with reusing an array by combining an array ("the buffer") with a size field. Usage: Dealing with an API that writes to an array you might: - call ensureCapacity() - call internalArray() - call manage() Dealing with an API that only reads an array, you might: - call internalArray() An API designed for this class may use add and get to assign/retrieve values from the array without worrying about capacity. This class is used in preference to an ArrayList because ArrayList requires boxing/unboxing of primitive values. Thread Safety: This class does not include synchronization. It is not recommended that you share instances of this class amongst threads.

Constructor Summary

Constructors

Constructor and Description
XBByteArray()
XBByteArray(byte[] initialData) Create XBByteArray object using the given array as its initial array.
XBByteArray(int initialCapacity) Create XBByteArray object with the given initial capacity.

Method Summary

Modifier and Type	Method and Description
void	add(byte value) Add given value to end of buffer.
java.lang.Object	clone() Return a copy of this object.
int	compareTo(java.lang.Object obj) Compare two XBByteArray objects.
void	ensureCapacity(int capacity) Ensure the buffer is at least the given size.
void	ensureCapacity(int capacity, int preserveLength) Ensure the buffer's length is at least the given capacity.
byte	get(int index) Return value at given index.
void	initialize(int capacity) Initialize the buffer so that: capacity is at least as given size is set to given capacity 0..size-1 are initialized
byte[]	internalArray() Get the internal array.
void	reset() Reset size to 0.
void	setInternalArray(byte[] newBuffer, int size) Give this object a new array to manage.
int	size() Return the number of valid bytes in the array.
byte[]	toArray() Return a newly allocated array, holding the data from this object.
java.lang.String	toString() Provides a hex binary representation of the string.
void	writeToStream(java.io.OutputStream stream) Write the data of this array to the given stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

XBByteArray

public XBByteArray()

XBByteArray

public XBByteArray(int initialCapacity)

Create XBByteArray object with the given initial capacity.

Parameters:

initialCapacity -

XBByteArray

public XBByteArray(byte[] initialData)

Create XBByteArray object using the given array as its initial array. A copy is NOT made. The size will be the size of the array.

Parameters:

initialData -

Method Detail

internalArray

public byte[] internalArray()

Get the internal array. Does NOT make a copy. This has obvious danger, but it helps work with API's that expect an arrays. This is useful for APIs that require an array as input, and avoids copying data. If you must give the array to an API for output, you may want to call manage() to update the size (and buffer, if necessary).

Returns:

clone

public java.lang.Object clone()

Return a copy of this object. The copy will contain the same bytes. The size of the internal buffer is unspecified.

Overrides:

clone in class java.lang.Object

compareTo

public int compareTo(java.lang.Object obj)

Compare two XBByteArray objects. A return of zero indicates the objects have the same bytes. A non-zero return indicates the first byte where they differ. More precisely: Return 0 if host and obj have the same number of bytes and (if the number of bytes > 0) all bytes are equal. Otherwise, let retVal be the returned value. Then the following is true: If |retVal| == 1, the arrays have no bytes in common. Otherwise, host[x] == obj[x] for all x 0..|retVal| - 2 if retVal < 0, then host[-retVal-1] < obj[-retVal-1] OR host.size < obj.size else if retVal > 0, then host[retVal-1] > obj[retVal-1] OR host.size > obj.size

Parameters:

obj -

Returns:

add

public void add(byte value)

Add given value to end of buffer. This sets buffer[size] = value, updates size, and expands capacity, if necessary.

Parameters:

value -

ensureCapacity

public void ensureCapacity(int capacity,
                           int preserveLength)

Ensure the buffer's length is at least the given capacity. Preserve data from the buffer up preserveLength. Size will be set to preserveLength.

Parameters:

capacity -

preserveLength -

Throws:

java.lang.ArrayIndexOutOfBoundsException - if preserveLength < 0 or preserveLength > size.

ensureCapacity

public void ensureCapacity(int capacity)

Ensure the buffer is at least the given size. Preserves contents of existing buffer (size does not change).

Parameters:

capacity -

get

public byte get(int index)

Return value at given index. An array must be under management.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index < 0 or index >= size()

initialize

public void initialize(int capacity)

Initialize the buffer so that: capacity is at least as given size is set to given capacity 0..size-1 are initialized

setInternalArray

public void setInternalArray(byte[] newBuffer,
                             int size)

Give this object a new array to manage. A copy is NOT made. (Note: you can simply change the size by passing the existing array.)

Parameters:

newBuffer - The new buffer to manage.

size - The new size (0..newBuffer.length)

reset

public void reset()

Reset size to 0.

size

public int size()

Return the number of valid bytes in the array.

Returns:

toArray

public byte[] toArray()

Return a newly allocated array, holding the data from this object. The new array will have length == size.

Returns:

toString

public java.lang.String toString()

Provides a hex binary representation of the string.

Overrides:

toString in class java.lang.Object

writeToStream

public void writeToStream(java.io.OutputStream stream)
                   throws java.io.IOException

Write the data of this array to the given stream.

Throws:

java.io.IOException