Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javolution.util
Class FastCollection<E>

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

All Implemented Interfaces:
  java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, Realtime, XMLSerializable

Direct Known Subclasses:
  FastList, FastSet, FastTable

    public abstract class FastCollection<E>

extends java.lang.Object
implements java.util.Collection<E>, XMLSerializable, Realtime

This class represents collections which can quickly be iterated over (forward or backward) in a thread-safe manner without creating new objects and without using `iterators` . For example:``

         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;
         }

Iterations are thread-safe as long as the `record` sequence iterated over is not structurally modified by another thread (objects can safely be append/prepend during iterations but not inserted/removed).

Users may provide a read-only view of any `FastCollection` instance using the `unmodifiable()` method (the view is thread-safe if iterations are thread-safe). For example:``

         public class Polynomial {
             private final FastTable<Coefficient> _coefficients = new FastTable<Coefficient>();
             public List<Coefficient> getCoefficients() { // Read-only view.
                 return _coefficients.unmodifiable();
             }
         }

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

Version:
  4.2, December 18, 2006
Author:
  Jean-Marie Dautelle
See Also:
  Serialized Form

Nested Class Summary
`static interface` | `FastCollection.Record` This interface represents the collection records which can directly be iterated over.

Constructor Summary
`protected` | `FastCollection()` Default constructor.

Method Summary
`boolean` | `add(E value)` Appends the specified value to the end of this collection (optional operation).
`boolean` | `addAll(java.util.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 or the node order if the specified collection is a `FastCollection`.
`void` | `clear()` Removes all of the values from this collection (optional operation).
`boolean` | `contains(java.lang.Object value)` Indicates if this collection contains the specified value.
`boolean` | `containsAll(java.util.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(java.lang.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 (independent from the collection order; unless this collection is a list instance).
`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.
`java.util.Iterator<E>` | `iterator()` Returns an iterator over the elements in this collection (allocated on the stack when executed in a `StackContext`).
`boolean` | `remove(java.lang.Object value)` Removes the first occurrence in this collection of the specified value (optional operation).
`boolean` | `removeAll(java.util.Collection<?> c)` Removes from this collection all the values that are contained in the specified collection.
`boolean` | `retainAll(java.util.Collection<?> c)` Retains only the values in this collection that are contained in the specified 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.
`java.lang.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.
`java.lang.String` | `toString()` Returns the `String` representation of this `FastCollection`.
`Text` | `toText()` Returns the textual representation of this collection.
`java.util.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`

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 `java.util.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:
    `java.lang.UnsupportedOperationException` - if not supported.

### unmodifiable

    public java.util.Collection<E> unmodifiable()

  Returns the unmodifiable view associated to this collection. Attempts to modify the returned collection result in an `UnsupportedOperationException` being thrown. The view is typically part of the collection itself (created only once) and also an instance of `FastCollection` supporting direct iterations.

  Returns:
    the unmodifiable view over this collection.

### iterator

    public java.util.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 `java.lang.Iterable<E>`
  Specified by:
    `iterator` in interface `java.util.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 `java.util.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:
    `java.lang.UnsupportedOperationException` - if not supported.

### remove

    public boolean remove(java.lang.Object value)

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

  Specified by:
    `remove` in interface `java.util.Collection<E>`
  Parameters:
    `value` - the value to be removed from this collection.
  Returns:
    `true` if this collection contained the specified value; `false` otherwise.
  Throws:
    `java.lang.UnsupportedOperationException` - if not supported.

### clear

    public void clear()

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

  Specified by:
    `clear` in interface `java.util.Collection<E>`
  Throws:
    `java.lang.UnsupportedOperationException` - if not supported.

### isEmpty

    public final boolean isEmpty()

  Indicates if this collection is empty.

  Specified by:
    `isEmpty` in interface `java.util.Collection<E>`
  Returns:
    `true` if this collection contains no value; `false` otherwise.

### contains

    public boolean contains(java.lang.Object value)

  Indicates if this collection contains the specified value.

  Specified by:
    `contains` in interface `java.util.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(java.util.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 or the node order if the specified collection is a `FastCollection`.

  Specified by:
    `addAll` in interface `java.util.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(java.util.Collection<?> c)

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

  Specified by:
    `containsAll` in interface `java.util.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(java.util.Collection<?> c)

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

  Specified by:
    `removeAll` in interface `java.util.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(java.util.Collection<?> c)

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

  Specified by:
    `retainAll` in interface `java.util.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 java.lang.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 `java.util.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 `java.util.Collection<E>`
  Parameters:
    `array` - the array into which the values of this collection are to be stored.
  Returns:
    the specified array.
  Throws:
    `java.lang.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 java.lang.String toString()

  Returns the `String` representation of this `FastCollection`.

  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    `toText().toString()`

### equals

    public boolean equals(java.lang.Object obj)

  Compares the specified object with this collection for equality. Returns `true` if and only both collection contains the same values regardless of the order; unless this collection is a list instance in which case both collections must be list with the same order.

  Specified by:
    `equals` in interface `java.util.Collection<E>`
  Overrides:
    `equals` in class `java.lang.Object`
  Parameters:
    `obj` - the object to be compared for equality with this collection.
  Returns:
    `true` if the specified object is equal to this collection; `false` otherwise.

### hashCode

    public int hashCode()

  Returns the hash code for this collection (independent from the collection order; unless this collection is a list instance).

  Specified by:
    `hashCode` in interface `java.util.Collection<E>`
  Overrides:
    `hashCode` in class `java.lang.Object`
  Returns:
    the hash code for this collection.

Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2005 - 2007 Javolution.