org.j3d.util
Class CircularList

java.lang.Object
  org.j3d.util.CircularList

public class CircularList
extends java.lang.Object

A circular list (buffer) implementation.

The implementation uses a double linked list. When the toArray method is called, the values are written to the list based on the current position. The code is implemented for speed, not safety. Accessing a single instance from multiple threads is probably going to cause problems. However, it does cache internal entry values amongst instances to save on garbage generation and allocation costs. If the code needs to reduce allocated memory, a convenience method is provided to reduce the internal cache size.

Version:

$Revision: 1.1 $

Author:

Rob Nielsen

Constructor Summary

CircularList()
Constructs a new, empty list.

Method Summary

void	add(java.lang.Object o) Adds the specified element to this list.
boolean	addAll(java.util.Collection c) Adds all of the elements in the specified collection to this set.
void	clear() Removes all of the elements from this set.
void	clearCachedObjects() Clean up the internal cache and reduce it to zero.
boolean	contains(java.lang.Object o) Returns true if this set contains the specified element.
java.lang.Object	current() Get the current item that is being pointed to in the list.
boolean	equals(java.lang.Object o) Compares the specified object with this set for equality.
int	hashCode() Returns the hash code value for this list.
boolean	isEmpty() Check to see if this set contains elements.
java.lang.Object	next() Fetch the next item in the list from this one and advance the current pointer to it.
java.lang.Object	previous() Fetch the previous item in the list from this one and retire the current pointer to it.
boolean	remove(java.lang.Object o) Removes the specified element from this set if it is present.
boolean	removeAll(java.util.Collection c) Removes from this set all of its elements that are contained in the specified collection.
int	size() Returns the number of elements in this set (its cardinality).
java.lang.Object[]	toArray() Returns an array containing all of the elements in this collection.
java.lang.Object[]	toArray(java.lang.Object[] array) Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
java.lang.String	toString() Returns a string representation of this set.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CircularList

public CircularList()

Constructs a new, empty list.

Method Detail

size

public int size()

Returns the number of elements in this set (its cardinality).

Returns:

the number of elements in this set

isEmpty

public boolean isEmpty()

Check to see if this set contains elements.

Returns:

true if this set contains no elements.

next

public java.lang.Object next()

Fetch the next item in the list from this one and advance the current pointer to it. If the list is empty, returns null.

Returns:

The next item in the list.

previous

public java.lang.Object previous()

Fetch the previous item in the list from this one and retire the current pointer to it. If the list is empty, returns null.

Returns:

The previous item in the list.

current

public java.lang.Object current()

Get the current item that is being pointed to in the list. If the list is empty, returns null.

Returns:

The current item

contains

public boolean contains(java.lang.Object o)

Returns true if this set contains the specified element.

Parameters:

o - element whose presence in this set is to be tested.

Returns:

true if this set contains the specified element.

add

public void add(java.lang.Object o)

Adds the specified element to this list. Duplicate entries are allowed, but null values are not. The Add operation places it at the end of the list, just behind the current pointer.

Parameters:

o - element to be added to this set

Throws:

java.lang.NullPointerException - The passed object was null

remove

public boolean remove(java.lang.Object o)

Removes the specified element from this set if it is present. Comparison is made using both referential equality or .equals(). If the removed object is the current object, the list pointer is moved to the next object in the list.

Parameters:

o - object to be removed from this set, if present.

Returns:

true if the set contained the specified element.

clear

public void clear()

Removes all of the elements from this set.

addAll

public boolean addAll(java.util.Collection c)

Adds all of the elements in the specified collection to this set. The behavior of this operation is undefined if the specified collection is modified while the operation is in progress.

This implementation iterates over the specified collection, and adds each object returned by the iterator to this collection, in turn.

Parameters:

c - collection whose elements are to be added to this collection.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if this collection does not support the addAll method.

java.lang.NullPointerException - if the specified collection is null.

removeAll

public boolean removeAll(java.util.Collection c)

Removes from this set all of its elements that are contained in the specified collection.

This implementation iterates over this collection, checking each element returned by the iterator in turn to see if it's contained in the specified collection. If it's so contained, it's removed from this collection with the iterator's remove method.

Parameters:

c - elements to be removed from this set.

Returns:

true if this collection changed as a result of the call.

Throws:

java.lang.UnsupportedOperationException - if the removeAll method is not supported by this collection.

java.lang.NullPointerException - if the specified collection is null.

See Also:

remove(Object), contains(Object)

toArray

public java.lang.Object[] toArray()

Returns an array containing all of the elements in this collection. If the collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. The returned array will be "safe" in that no references to it are maintained by the collection. (In other words, this method must allocate a new array even if the collection is backed by an Array). The caller is thus free to modify the returned array.

This implementation allocates the array to be returned, and iterates over the elements in the collection, storing each object reference in the next consecutive element of the array, starting with element 0.

Returns:

an array containing all of the elements in this collection.

toArray

public java.lang.Object[] toArray(java.lang.Object[] array)

Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If the collection fits in the specified array with room to spare (i.e., the array has more elements than the collection), the element in the array immediately following the end of the collection is set to null. This is useful in determining the length of the collection only if the caller knows that the collection does not contain any null elements.)

If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

This implementation checks if the array is large enough to contain the collection; if not, it allocates a new array of the correct size and type (using reflection). Then, it iterates over the collection, storing each object reference in the next consecutive element of the array, starting with element 0. If the array is larger than the collection, a null is stored in the first location after the end of the collection.

Parameters:

array - the array into which the elements of the set are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:

an array containing the elements of the collection.

Throws:

java.lang.NullPointerException - if the specified array is null.

java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this collection.

equals

public boolean equals(java.lang.Object o)

Compares the specified object with this set for equality. Returns true if the given object is also a set, the two sets have the same size, and every member of the given set is contained in this set and in the exact same order. This implementation first checks if the specified object is this set; if so it returns true. Then, it checks if the specified object is a set whose size is identical to the size of this set; if not, it it returns false. If so, it returns containsAll((Collection) o).

Overrides:

equals in class java.lang.Object

Parameters:

o - Object to be compared for equality with this set.

Returns:

true if the specified object is equal to this set.

hashCode

public int hashCode()

Returns the hash code value for this list. The hash code of a list is defined to be the sum of the hash codes of the elements in the list. This ensures that s1.equals(s2) implies that s1.hashCode()==s2.hashCode() for any two sets s1 and s2, as required by the general contract of Object.hashCode.

This implementation enumerates over the set, calling the hashCode method on each element in the collection, and adding up the results.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code value for this set.

toString

public java.lang.String toString()

Returns a string representation of this set. The string representation consists of a list of the collection's elements in the order they are returned by its iterator, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (comma and space). Elements are converted to strings as by String.valueOf(Object).

This implementation creates an empty string buffer, appends a left square bracket, and iterates over the collection appending the string representation of each element in turn. After appending each element except the last, the string ", " is appended. Finally a right bracket is appended. A string is obtained from the string buffer, and returned.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this collection.

clearCachedObjects

public void clearCachedObjects()

Clean up the internal cache and reduce it to zero.