FastCollection (Javolution 5.5.1 API)

java.lang.Object
- javolution.util.FastCollection<E>

All Implemented Interfaces:

Serializable, Iterable<E>, Collection<E>, Realtime, XMLSerializable

Direct Known Subclasses:

FastBitSet, FastList, FastSet, FastTable
```
public abstract class FastCollection<E>
extends Object
implements Collection<E>, XMLSerializable, Realtime
```
This class represents collections which can quickly be iterated over (forward or backward) and which an be made thread-safe and/or unmodifiable.

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

Fast collections are thread-safe when marked shared (can be read, iterated over or modified concurrently). [code] public class Foo { private static final Collection INSTANCES = new FastTable().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]

Users may provide a read-only view of any FastCollection instance using the unmodifiable() method (the view is thread-safe if the collection is shared). [code] class Foo { private static final FastTable INSTANCES = new FastTable().shared(); Foo() { INSTANCES.add(this); } public static Collection getInstances() { return INSTANCES.unmodifiable(); // Returns a public unmodifiable view over the shared collection. } }[/code]

Finally, FastCollection may use custom comparators for element equality or ordering if the collection is ordered (e.g. FastTree).

Version:

5.4.5, March 23, 2010

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static interface FastCollection.Record
This interface represents the collection records which can directly be iterated over.

Nested Classes
Modifier and Type	Class and Description
`static interface`	`FastCollection.Record` This interface represents the collection records which can directly be iterated over.

Constructor Summary

Constructors
Modifier Constructor and Description

protected FastCollection()
Default constructor.

Constructors
Modifier	Constructor and Description
`protected`	`FastCollection()` Default constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`add(E value)` Appends the specified value to the end of this collection (optional operation).
`boolean`	`addAll(Collection<? extends E> 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(Object value)` Indicates if this collection contains the specified value.
`boolean`	`containsAll(Collection<?> c)` Indicates if this collection contains all of the values of the specified collection.
`abstract void`	`delete(FastCollection.Record record)` Deletes the specified record from this collection.
`boolean`	`equals(Object obj)` Compares the specified object with this collection for equality.
`FastComparator<? super E>`	`getValueComparator()` Returns the value comparator for this collection (default `FastComparator.DEFAULT`).
`int`	`hashCode()` Returns the hash code for this collection.
`abstract FastCollection.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.
`Iterator<E>`	`iterator()` Returns an iterator over the elements in this collection (allocated on the stack when executed in a `StackContext`).
`boolean`	`remove(Object value)` Removes the first occurrence in this collection of the specified value (optional operation).
`boolean`	`removeAll(Collection<?> c)` Removes from this collection all the values that are contained in the specified collection.
`boolean`	`retainAll(Collection<?> c)` Retains only the values in this collection that are contained in the specified collection.
`Collection<E>`	`shared()` Returns a thread-safe read-write view of this collection.
`abstract int`	`size()` Returns the number of values in this collection.
`abstract FastCollection.Record`	`tail()` Returns the tail record of this collection; it is the record such as `tail().getPrevious()` holds the last collection value.
`Object[]`	`toArray()` Returns a new array allocated on the heap containing all of the values in this collection in proper sequence.
`<T> T[]`	`toArray(T[] array)` Fills the specified array with the values of this collection in the proper sequence.
`String`	`toString()` Returns the `String` representation of this `FastCollection`.
`Text`	`toText()` Returns the textual representation of this collection.
`Collection<E>`	`unmodifiable()` Returns the unmodifiable view associated to this collection.
`abstract E`	`valueOf(FastCollection.Record record)` Returns the collection value for the specified record.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection
parallelStream, removeIf, spliterator, stream

Methods inherited from interface java.lang.Iterable
forEach

- Constructor Detail
  - FastCollection
```
protected FastCollection()
```
    Default constructor.
- Method Detail
  - size
```
public abstract int size()
```
    Returns the number of values in this collection.
    
    Specified by:
    
    size in interface Collection<E>
    
    Returns:
    
    the number of values.
  - head
```
public abstract FastCollection.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
```
public abstract FastCollection.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
```
public abstract E valueOf(FastCollection.Record record)
```
    Returns the collection value for the specified record.
    
    Parameters:
    
    record - the record whose current value is returned.
    
    Returns:
    
    the current value.
  - delete
```
public abstract void delete(FastCollection.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
```
public Collection<E> 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
```
public Collection<E> 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
```
public Iterator<E> iterator()
```
    Returns an iterator over the elements in this collection (allocated on the stack when executed in a StackContext).
    
    Specified by:
    
    iterator in interface Iterable<E>
    
    Specified by:
    
    iterator in interface Collection<E>
    
    Returns:
    
    an iterator over this collection's elements.
  - getValueComparator
```
public FastComparator<? super E> getValueComparator()
```
    Returns the value comparator for this collection (default FastComparator.DEFAULT).
    
    Returns:
    
    the comparator to use for value equality (or ordering if the collection is ordered)
  - add
```
public boolean add(E value)
```
    Appends the specified value to the end of this collection (optional operation).
    Note: This default implementation always throws UnsupportedOperationException.
    
    Specified by:
    
    add in interface Collection<E>
    
    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
```
public boolean remove(Object value)
```
    Removes the first occurrence in this collection of the specified value (optional operation).
    
    Specified by:
    
    remove in interface Collection<E>
    
    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
```
public void clear()
```
    Removes all of the values from this collection (optional operation).
    
    Specified by:
    
    clear in interface Collection<E>
    
    Throws:
    
    UnsupportedOperationException - if not supported.
  - isEmpty
```
public final boolean isEmpty()
```
    Indicates if this collection is empty.
    
    Specified by:
    
    isEmpty in interface Collection<E>
    
    Returns:
    
    true if this collection contains no value; false otherwise.
  - contains
```
public boolean contains(Object value)
```
    Indicates if this collection contains the specified value.
    
    Specified by:
    
    contains in interface Collection<E>
    
    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
```
public boolean addAll(Collection<? extends E> 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.
    
    Specified by:
    
    addAll in interface Collection<E>
    
    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
```
public boolean containsAll(Collection<?> c)
```
    Indicates if this collection contains all of the values of the specified collection.
    
    Specified by:
    
    containsAll in interface Collection<E>
    
    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
```
public boolean removeAll(Collection<?> c)
```
    Removes from this collection all the values that are contained in the specified collection.
    
    Specified by:
    
    removeAll in interface Collection<E>
    
    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
```
public boolean retainAll(Collection<?> c)
```
    Retains only the values in this collection that are contained in the specified collection.
    
    Specified by:
    
    retainAll in interface Collection<E>
    
    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
```
public Object[] 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(Object[]) is recommended.
    
    Specified by:
    
    toArray in interface Collection<E>
    
    Returns:
    
    toArray(new Object[size()])
  - toArray
```
public <T> T[] toArray(T[] array)
```
    Fills the specified array with the values of this collection in the proper sequence.
    Note: Unlike standard Collection, this method does not try to resize the array using reflection (which might not be supported) if the array is too small. UnsupportedOperationException is raised if the specified array is too small for this collection.
    
    Specified by:
    
    toArray in interface Collection<E>
    
    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()
  - toText
```
public Text toText()
```
    Returns the textual representation of this collection.
    
    Specified by:
    
    toText in interface Realtime
    
    Returns:
    
    this collection textual representation.
  - toString
```
public final String toString()
```
    Returns the String representation of this FastCollection.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    toText().toString()
  - equals
```
public 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). Equality comparisons are performed using this collection value comparator.
    
    Specified by:
    
    equals in interface Collection<E>
    
    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
```
public 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.
    
    Specified by:
    
    hashCode in interface Collection<E>
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    the hash code for this collection.

Class FastCollection<E>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

Constructor Detail

FastCollection

Method Detail

size

head

tail

valueOf

delete

unmodifiable

shared

iterator

getValueComparator

add

remove

clear

isEmpty

contains

addAll

containsAll

removeAll

retainAll

toArray

toArray

toText

toString

equals

hashCode