com.neeve.lang
Interface XLongCollection

All Known Subinterfaces:

XLongList, XLongSet

All Known Implementing Classes:

XLongCollectionBase, XLongIndexedList, XLongLinkedList

public interface XLongCollection

This class represents collections which can quickly be iterated over (forward or backward) and which an be made thread-safe and/or unmodifiable.

XLongCollections can be iterated over without creating new objects and without using iterators . [code] public boolean search(Object item, XCollection c) { for (LongRecord r = c.head(), end = c.tail(); (r = r.getNext()) != end;) { if (item.equals(c.valueOf(r))) return true; } return false; } [/code]

Alternatively XCollection}s can be iterated over using reusableIterator(), Utilization of this iterators does not introduce garbage because it is created once. This iterator may not be used concurrently by multiple threads as they are single instance by nature.

XLongCollections are thread-safe when marked shared (can be read, iterated over or modified concurrently). [code] public class Foo { private static final Collection INSTANCES = new XLinkedHashMap().shared(); public Foo() { INSTANCES.add(this); } public static void showInstances() { for (Foo foo : INSTANCES) { // Iterations are thread-safe even if new Foo instances are added. System.out.println(foo); } } }[/code]

This class was based on collections code from http://javolution.org, but modified for use outside of realtime jvms.

Method Summary

boolean	add(long value) Appends the specified value to the end of this collection (optional operation).
boolean	addAll(XLongCollection c) Appends all of the values in the specified collection to the end of this collection, in the order that they are returned by the specified collection's iterator.
void	clear() Removes all of the values from this collection (optional operation).
boolean	contains(long value) Indicates if this collection contains the specified value.
boolean	containsAll(XLongCollection c) Indicates if this collection contains all of the values of the specified collection.
void	delete(XCollection.Record record) Deletes the specified record from this collection.
boolean	equals(Object obj) Compares the specified object with this collection for equality.
int	hashCode() Returns the hash code for this collection.
XCollection.Record	head() Returns the head record of this collection; it is the record such as head().getNext() holds the first collection value.
boolean	isEmpty() Indicates if this collection is empty.
XLongIterator	iterator() Returns an iterator over the elements in this collection
boolean	remove(long value) Removes the first occurrence in this collection of the specified value (optional operation).
boolean	removeAll(XLongCollection c) Removes from this collection all the values that are contained in the specified collection.
boolean	retainAll(XLongCollection c) Retains only the values in this collection that are contained in the specified collection.
XLongIterator	reusableIterator() Returns an iterator over the elements in this collection.
XLongCollection	shared() Returns a thread-safe read-write view of this collection.
int	size() Returns the number of values in this collection.
XCollection.Record	tail() Returns the tail record of this collection; it is the record such as tail().getPrevious() holds the last collection value.
long[]	toArray() Returns a new array allocated on the heap containing all of the values in this collection in proper sequence.
long[]	toArray(long[] array) Fills the specified array with the values of this collection in the proper sequence.
XLongCollection	unmodifiable() Returns the unmodifiable view associated to this collection.
long	valueOf(XCollection.Record record) Returns the collection value for the specified record.

Method Detail

size

int size()

Returns the number of values in this collection.

Returns:

the number of values.

head

XCollection.Record head()

Returns the head record of this collection; it is the record such as head().getNext() holds the first collection value.

Returns:

the head record.

tail

XCollection.Record tail()

Returns the tail record of this collection; it is the record such as tail().getPrevious() holds the last collection value.

Returns:

the tail record.

valueOf

long valueOf(XCollection.Record record)

Returns the collection value for the specified record.

Parameters:

record - the record whose current value is returned.

Returns:

the current value.

delete

void delete(XCollection.Record record)

Deletes the specified record from this collection.

Implementation must ensure that removing a record from the collection does not affect in any way the records preceding the record being removed (it might affect the next records though, e.g. in a list collection, the indices of the subsequent records will change).

Parameters:

record - the record to be removed.

Throws:

UnsupportedOperationException - if not supported.

unmodifiable

XLongCollection unmodifiable()

Returns the unmodifiable view associated to this collection. Attempts to modify the returned collection result in an UnsupportedOperationException being thrown.

Returns:

the unmodifiable view over this collection.

shared

XLongCollection shared()

Returns a thread-safe read-write view of this collection.

The default implementation performs synchronization on read and write. Sub-classes may provide more efficient implementation (e.g. only synchronizing on writes modifying the internal data structure).

Having a shared collection does not mean that modifications made by onethread are automatically viewed by others thread. Which in practice is not an issue. In a well-behaved system, threads need to synchronize only at predetermined synchronization points (the fewer the better).

Returns:

a thread-safe collection.

iterator

XLongIterator iterator()

Returns an iterator over the elements in this collection

Returns:

an iterator over this collection's elements.

reusableIterator

XLongIterator reusableIterator()

Returns an iterator over the elements in this collection. This iterator may only be used by a single thread at a time. This method invokes XCollectionIterator.toFirst() on the iterator prior to returning it.

Returns:

an iterator over this collection's elements.

add

boolean add(long value)

Appends the specified value to the end of this collection (optional operation).

Note: This default implementation always throws UnsupportedOperationException.

Parameters:

value - the value to be appended to this collection.

Returns:

true (as per the general contract of the Collection.add method).

Throws:

UnsupportedOperationException - if not supported.

remove

boolean remove(long value)

Removes the first occurrence in this collection of the specified value (optional operation).

Parameters:

value - the value to be removed from this collection.

Returns:

true if this collection contained the specified value; false otherwise.

Throws:

UnsupportedOperationException - if not supported.

clear

void clear()

Removes all of the values from this collection (optional operation).

Throws:

UnsupportedOperationException - if not supported.

isEmpty

boolean isEmpty()

Indicates if this collection is empty.

Returns:

true if this collection contains no value; false otherwise.

contains

boolean contains(long value)

Indicates if this collection contains the specified value.

Parameters:

value - the value whose presence in this collection is to be tested.

Returns:

true if this collection contains the specified value;false otherwise.

addAll

boolean addAll(XLongCollection c)

Appends all of the values in the specified collection to the end of this collection, in the order that they are returned by the specified collection's iterator.

Parameters:

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

Returns:

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

containsAll

boolean containsAll(XLongCollection c)

Indicates if this collection contains all of the values of the specified collection.

Parameters:

c - collection to be checked for containment in this collection.

Returns:

true if this collection contains all of the values of the specified collection; false otherwise.

removeAll

boolean removeAll(XLongCollection c)

Removes from this collection all the values that are contained in the specified collection.

Parameters:

c - collection that defines which values will be removed from this collection.

Returns:

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

retainAll

boolean retainAll(XLongCollection c)

Retains only the values in this collection that are contained in the specified collection.

Parameters:

c - collection that defines which values this set will retain.

Returns:

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

toArray

long[] toArray()

Returns a new array allocated on the heap containing all of the values in this collection in proper sequence.

Note: To avoid heap allocation toArray(long[]) is recommended.

Returns:

toArray(new Object[size()])

toArray

long[] toArray(long[] array)

Fills the specified array with the values of this collection in the proper sequence.

Note: If the provided array is greater than the size of this collection the value of values greater than this collections size are left unaltered

Parameters:

array - the array into which the values of this collection are to be stored.

Returns:

the specified array.

Throws:

UnsupportedOperationException - if array.length < size()

equals

boolean equals(Object obj)

Compares the specified object with this collection for equality. The default behavior is to consider two collections equal if they hold the same values and have the same iterative order if any of the collections is an ordered collection (List instances).

Overrides:

equals in class Object

Parameters:

obj - the object to be compared for equality with this collection

Returns:

true if the specified object is a collection with the same content and iteration order when necessary; false otherwise.

hashCode

int hashCode()

Returns the hash code for this collection. For non-ordered collection the hashcode of this collection is the sum of the hashcode of its values.

Overrides:

hashCode in class Object

Returns:

the hash code for this collection.