gov.lbl.dsd.sea.nio.util
Class ByteArrayList

java.lang.Object
  gov.lbl.dsd.sea.nio.util.ByteArrayList

All Implemented Interfaces:

Serializable

public class ByteArrayList

extends Object

implements Serializable

Highly efficient resizable list holding byte elements; implemented with arrays; Convenient to assemble variable-sized byte messages if message lengths are a priori unknown.

Manipulating primitive values other than bytes and ints is not directly supported. However, this can be done along the following lines:

    // append double at end
    list = ...
    double elemToAdd = 1234.0;
    int s = list.size();
    list.setSize(s + 8);
    list.asByteBuffer().putDouble(s, elemToAdd);

    // or insertion at beginning can be done this way
    list = ...
    double elemToInsert = 1234.0;
    list.replace(0, 0, 0, 8); // insert 8 bytes at beginning
    list.asByteBuffer().putDouble(0, elemToInsert);

Version:

$Revision: 1.34 $, $Date: 2004/06/17 18:34:39 $

See Also:

Serialized Form

Constructor Summary

ByteArrayList()
Constructs an empty list.

ByteArrayList(byte[] elems)
Constructs a list SHARING the specified elements.

ByteArrayList(ByteBuffer elems)
Constructs a list containing a copy of the remaining buffer elements.

ByteArrayList(int initialCapacity)
Constructs an empty list with the specified initial capacity.

ByteArrayList(String str, Charset charset)
Constructs a list containing the encoded representation of the given string.

Method Summary

void	add(byte elem) Appends the specified element to the end of this list.
void	add(byte[] elems) Appends the specified elements to the end of this list.
void	add(ByteArrayList elems) Appends the specified elements to the end of this list.
void	add(ByteBuffer elems) Appends the remaining buffer elements to the end of this list.
void	add(String str, Charset charset) Appends the encoded representation of the given string.
byte[]	asArray() Returns the elements currently stored, including invalid elements between size and capacity, if any.
ByteBuffer	asByteBuffer() Returns a byte buffer SHARING elements with the receiver; the buffer will have the default NIO byte order, which is ByteOrder.BIG_ENDIAN.
void	clear() Removes all elements from the receiver.
ByteArrayList	copy() Returns a deep copy of the receiver.
void	ensureCapacity(int minCapacity) Ensures that the receiver can hold at least the specified number of elements without needing to allocate new internal memory.
boolean	equals(Object otherObj) Compares the specified Object with the receiver.
byte	get(int index) Returns the element at the specified position in the receiver.
int	getInt(int index) Returns the 4 byte integer at the specified position in the receiver; using the NIO default byte order, which is ByteOrder.BIG_ENDIAN.
String	getString(int from, int to, Charset charset) Returns a decoded string representation of the receiver's bytes in the given range.
int	indexOf(byte elem, int from, int to) Returns the index of the first occurrence of the specified element.
void	insert(int index, byte elem) Inserts the specified element before the specified position into the receiver.
void	insert(int index, byte[] elems) Inserts the specified elements before the specified position into the receiver.
void	insert(int index, ByteArrayList elems) Inserts the specified elements before the specified position into the receiver.
void	insert(int index, ByteBuffer elems) Inserts the remaining buffer elements before the specified position into the receiver.
int	lastIndexOf(byte elem, int from, int to) Returns the index of the last occurrence of the specified element.
void	remove(int index) Removes the element at the specified position from the receiver.
void	remove(int from, int to) Removes the elements in the given range from the receiver.
boolean	removeAll(ByteArrayList other) Removes from the receiver all elements that are contained in the specified list.
void	replace(int from, int length, byte[] replacement) Replaces all elements[from..from+length-1] with the given replacement.
void	replace(int from, int length, ByteArrayList replacement) Replaces all elements[from..from+length-1] with the given replacement.
void	replace(int from, int length, ByteBuffer replacement) Replaces all elements[from..from+length-1] with the given replacement.
void	replace(int from, int length, byte replacement, int replacementSize) Replaces all elements[from..from+length-1] with the given replacement.
boolean	retainAll(ByteArrayList other) Retains (keeps) only the elements in the receiver that are contained in the specified other list.
void	reverse() Reverses the elements of the receiver.
void	set(int index, byte element) Replaces the element at the specified position in the receiver with the specified element.
void	setInt(int index, int elem) Replaces the 4 bytes at the specified position in the receiver with the specified element; using the NIO default byte order, which is ByteOrder.BIG_ENDIAN.
void	setSize(int newSize) Sets the size to the given new size; expanding the list capacity if necessary.
int	size() Returns the number of elements contained in the receiver.
void	sort() Sorts the receiver into ascending numerical order.
ByteArrayList	subList(int from, int to) Returns a new list of the copied part of the receiver between from, inclusive, and to, exclusive.
byte[]	toArray() Returns a copied array of bytes containing all the elements in the receiver; the returned array has length = this.size().
ArrayList	toList() Returns a java.util.ArrayList containing all the elements in the receiver.
String	toString() Returns a string representation of the receiver, containing the numeric String representation of each element.
String	toString(Charset charset) Returns a decoded string representation of the receiver.
void	trimToSize() Trims the capacity of the receiver to be the receiver's current size.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ByteArrayList

public ByteArrayList()

Constructs an empty list.

ByteArrayList

public ByteArrayList(int initialCapacity)

Constructs an empty list with the specified initial capacity.

Parameters:

initialCapacity - the number of elements the receiver can hold without auto-expanding itself by allocating new internal memory.

ByteArrayList

public ByteArrayList(byte[] elems)

Constructs a list SHARING the specified elements. The initial size and capacity of the list is the length of the array. WARNING: For efficiency reasons and to keep memory usage low, the array is not copied . So if subsequently you modify the specified array directly via the [] operator, be sure you know what you're doing.

Parameters:

elems - the array to be backed by the the constructed list

ByteArrayList

public ByteArrayList(ByteBuffer elems)

Constructs a list containing a copy of the remaining buffer elements. The initial size and capacity of the list is elements.remaining().

Parameters:

elems - the elements initially to be added to the list

ByteArrayList

public ByteArrayList(String str,
                     Charset charset)

Constructs a list containing the encoded representation of the given string.

Parameters:

str - the string to convert.

charset - the requested charset to convert with (e.g. Charset.forName("US-ASCII"), Charset.forName("UTF-8"))

Method Detail

add

public void add(byte elem)

Appends the specified element to the end of this list.

Parameters:

elem - element to be appended to this list.

add

public void add(byte[] elems)

Appends the specified elements to the end of this list.

Parameters:

elems - elements to be appended.

add

public void add(ByteArrayList elems)

Appends the specified elements to the end of this list.

Parameters:

elems - elements to be appended.

add

public void add(ByteBuffer elems)

Appends the remaining buffer elements to the end of this list.

Parameters:

elems - elements to be appended.

add

public void add(String str,
                Charset charset)

Appends the encoded representation of the given string.

Parameters:

str - the string to convert.

charset - the requested charset to convert with (e.g. Charset.forName("US-ASCII"), Charset.forName("UTF-8"))

asArray

public byte[] asArray()

Returns the elements currently stored, including invalid elements between size and capacity, if any.

WARNING: For efficiency reasons and to keep memory usage low, the array is not copied . So if subsequently you modify the returned array directly via the [] operator, be sure you know what you're doing.

Returns:

the elements currently stored.

asByteBuffer

public ByteBuffer asByteBuffer()

Returns a byte buffer SHARING elements with the receiver; the buffer will have the default NIO byte order, which is ByteOrder.BIG_ENDIAN.

WARNING: For efficiency reasons and to keep memory usage low, the array is not copied . So if subsequently you modify the returned bytebuffer, be sure you know what you're doing.

clear

public void clear()

Removes all elements from the receiver. The receiver will be empty after this call returns, but keep its current capacity.

copy

public ByteArrayList copy()

Returns a deep copy of the receiver.

Returns:

a deep copy of the receiver.

equals

public boolean equals(Object otherObj)

Compares the specified Object with the receiver. Returns true if and only if the specified Object is also an ArrayList of the same type, both Lists have the same size, and all corresponding pairs of elements in the two Lists are identical. In other words, two Lists are defined to be equal if they contain the same elements in the same order.

Parameters:

otherObj - the Object to be compared for equality with the receiver.

Returns:

true if the specified Object is equal to the receiver.

ensureCapacity

public void ensureCapacity(int minCapacity)

Ensures that the receiver can hold at least the specified number of elements without needing to allocate new internal memory. If necessary, allocates new internal memory and increases the capacity of the receiver.

Parameters:

minCapacity - the desired minimum capacity.

get

public final byte get(int index)

Returns the element at the specified position in the receiver.

Parameters:

index - index of element to return.

Throws:

IndexOutOfBoundsException - if index is out of range.

getInt

public int getInt(int index)

Returns the 4 byte integer at the specified position in the receiver; using the NIO default byte order, which is ByteOrder.BIG_ENDIAN.

Parameters:

index - index of first byte of the integer.

Throws:

IndexOutOfBoundsException - if index is out of range.

getString

public String getString(int from,
                        int to,
                        Charset charset)

Returns a decoded string representation of the receiver's bytes in the given range.

Parameters:

from - the index of the first element (inclusive).

to - the index of the last element (exclusive).

charset - the requested charset to convert with (e.g. Charset.forName("US-ASCII"), Charset.forName("UTF-8"))

Throws:

IndexOutOfBoundsException - if indexes are out of range

indexOf

public int indexOf(byte elem,
                   int from,
                   int to)

Returns the index of the first occurrence of the specified element. Returns -1 if the receiver does not contain this element. Searches between from, inclusive and to, exclusive. Tests for identity.

Parameters:

elem - element to search for.

from - the leftmost search position, inclusive.

to - the rightmost search position, exclusive.

Returns:

the index of the first occurrence of the element in the receiver; returns -1 if the element is not found.

Throws:

IndexOutOfBoundsException - if indexes are out of range

insert

public void insert(int index,
                   byte elem)

Inserts the specified element before the specified position into the receiver. Shifts the element currently at that position (if any) and any subsequent elements to the right.

Parameters:

index - index before which the specified element is to be inserted

elem - element to insert.

insert

public void insert(int index,
                   byte[] elems)

Inserts the specified elements before the specified position into the receiver. Shifts the element currently at that position (if any) and any subsequent elements to the right.

Parameters:

index - index before which the specified elements are to be inserted

elems - elements to insert.

insert

public void insert(int index,
                   ByteArrayList elems)

Inserts the specified elements before the specified position into the receiver. Shifts the element currently at that position (if any) and any subsequent elements to the right.

Parameters:

index - index before which the specified elements are to be inserted

elems - elements to insert.

insert

public void insert(int index,
                   ByteBuffer elems)

Inserts the remaining buffer elements before the specified position into the receiver. Shifts the element currently at that position (if any) and any subsequent elements to the right.

Parameters:

index - index before which the specified elements are to be inserted

elems - elements to insert.

lastIndexOf

public int lastIndexOf(byte elem,
                       int from,
                       int to)

Returns the index of the last occurrence of the specified element. Returns -1 if the receiver does not contain this element. Searches beginning at to, inclusive until from, exclusive. Tests for identity.

Parameters:

elem - element to search for.

from - the leftmost search position, inclusive.

to - the rightmost search position, exclusive.

Returns:

the index of the last occurrence of the element in the receiver; returns -1 if the element is not found.

Throws:

IndexOutOfBoundsException - if indexes are out of range.

remove

public void remove(int index)

Removes the element at the specified position from the receiver. Shifts any subsequent elements to the left.

Parameters:

index - the index of the element to removed.

Throws:

IndexOutOfBoundsException - if index is out of range

remove

public void remove(int from,
                   int to)

Removes the elements in the given range from the receiver. Shifts any subsequent elements to the left.

Parameters:

from - the index of the first element to removed (inclusive).

to - the index of the last element to removed (exclusive).

Throws:

IndexOutOfBoundsException - if indexes are out of range

removeAll

public boolean removeAll(ByteArrayList other)

Removes from the receiver all elements that are contained in the specified list. Tests for identity.

Parameters:

other - the other list.

Returns:

true if the receiver changed as a result of the call.

replace

public void replace(int from,
                    int length,
                    byte[] replacement)

Replaces all elements[from..from+length-1] with the given replacement. The replacement can have any length. Examples:

[a,b,c,d,e].replace(1,3, [x,y]) --> [a,x,y,e]

[a,b].replace(1,0, [w,x,y,z]) --> [a,w,x,y,z,b]

Parameters:

from - the index of the first element to replace (inclusive)

length - the number of elements to replace

replacement - the elements to replace the replaced elements

replace

public void replace(int from,
                    int length,
                    ByteArrayList replacement)

Replaces all elements[from..from+length-1] with the given replacement. The replacement can have any length. Examples:

[a,b,c,d,e].replace(1,3, [x,y]) --> [a,x,y,e]

[a,b].replace(1,0, [w,x,y,z]) --> [a,w,x,y,z,b]

Parameters:

from - the index of the first element to replace (inclusive)

length - the number of elements to replace

replacement - the elements to replace the replaced elements

replace

public void replace(int from,
                    int length,
                    ByteBuffer replacement)

Replaces all elements[from..from+length-1] with the given replacement. The replacement can have any length. Examples:

[a,b,c,d,e].replace(1,3, [x,y]) --> [a,x,y,e]

[a,b].replace(1,0, [w,x,y,z]) --> [a,w,x,y,z,b]

Parameters:

from - the index of the first element to replace (inclusive)

length - the number of elements to replace

replacement - the elements to replace the replaced elements

replace

public void replace(int from,
                    int length,
                    byte replacement,
                    int replacementSize)

Replaces all elements[from..from+length-1] with the given replacement. The replacement can have any length. Example: [a,b,c,d,e].replace(1,3,x,4) --> [a,x,x,x,x,e]

Parameters:

from - the index of the first element to replace (inclusive)

length - the number of elements to replace

replacement - the elements to replace the replaced elements

replacementSize - the number of times replacement is to replace the replaced elements

retainAll

public boolean retainAll(ByteArrayList other)

Retains (keeps) only the elements in the receiver that are contained in the specified other list. In other words, removes from the receiver all of its elements that are not contained in the specified other list.

Parameters:

other - the other list to test against.

Returns:

true if the receiver changed as a result of the call.

reverse

public void reverse()

Reverses the elements of the receiver. Last becomes first, second last becomes second first, and so on.

set

public final void set(int index,
                      byte element)

Replaces the element at the specified position in the receiver with the specified element.

Parameters:

index - index of element to replace.

element - element to be stored at the specified position.

Throws:

IndexOutOfBoundsException - if index is out of range.

setInt

public void setInt(int index,
                   int elem)

Replaces the 4 bytes at the specified position in the receiver with the specified element; using the NIO default byte order, which is ByteOrder.BIG_ENDIAN.

Parameters:

index - index of first element to replace.

elem - element value to set.

Throws:

IndexOutOfBoundsException - if index is out of range.

setSize

public void setSize(int newSize)

Sets the size to the given new size; expanding the list capacity if necessary.

Parameters:

newSize - the new size.

Throws:

IndexOutOfBoundsException - if index is out of range.

size

public int size()

Returns the number of elements contained in the receiver.

Returns:

the number of elements contained in the receiver.

sort

public void sort()

Sorts the receiver into ascending numerical order.

subList

public ByteArrayList subList(int from,
                             int to)

Returns a new list of the copied part of the receiver between from, inclusive, and to, exclusive.

Parameters:

from - the index of the first element (inclusive).

to - the index of the last element (exclusive).

Returns:

a new list

Throws:

IndexOutOfBoundsException - if indexes are out of range

toArray

public byte[] toArray()

Returns a copied array of bytes containing all the elements in the receiver; the returned array has length = this.size().

toList

public ArrayList toList()

Returns a java.util.ArrayList containing all the elements in the receiver.

toString

public String toString()

Returns a string representation of the receiver, containing the numeric String representation of each element.

toString

public String toString(Charset charset)

Returns a decoded string representation of the receiver.

Parameters:

charset - the requested charset to convert with (e.g. Charset.forName("US-ASCII"), Charset.forName("UTF-8"))

trimToSize

public void trimToSize()

Trims the capacity of the receiver to be the receiver's current size. Releases any superfluos internal memory. An application can use this operation to minimize the storage of the receiver.