Collection

All Superinterfaces:

Rollbackable

All Known Subinterfaces:

List, Set, SortedSet

All Known Implementing Classes:

AbstractCollection, AbstractList, AbstractSequentialList, AbstractSet, ArrayList, HashSet, LinkedHashSet, LinkedList, Stack, TreeSet, Vector
```
public interface Collection
extends Rollbackable
```
Interface that represents a collection of objects. This interface is the root of the collection hierarchy, and does not provide any guarantees about the order of its elements or whether or not duplicate elements are permitted.
All methods of this interface that are defined to modify the collection are defined as optional. An optional operation may throw an UnsupportedOperationException if the data backing this collection does not support such a modification. This may mean that the data structure is immutable, or that it is read-only but may change ("unmodifiable"), or that it is modifiable but of fixed size (such as an array), or any number of other combinations.
A class that wishes to implement this interface should consider subclassing AbstractCollection, which provides basic implementations of most of the methods of this interface. Classes that are prepared to make guarantees about ordering or about absence of duplicate elements should consider implementing List or Set respectively, both of which are subinterfaces of Collection.
A general-purpose implementation of the Collection interface should in most cases provide at least two constructors: One which takes no arguments and creates an empty collection, and one which takes a Collection as an argument and returns a collection containing the same elements (that is, creates a copy of the argument using its own implementation).

Since:

1.2

Author:

Original author unknown, Eric Blake (ebb9@email.byu.edu)

See Also:

List, Set, Map, SortedSet, SortedMap, HashSet, TreeSet, ArrayList, LinkedList, Vector, Collections, Arrays, AbstractCollection

Status

updated to 1.4

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`$COMMIT(long timestamp)` Commit changes up to the given timestamp, but not including changes made at timestamp and afterward.
`Checkpoint`	`$GET$CHECKPOINT()` Get the checkpoint object that monitors this rollbackable object.
`void`	`$RESTORE(long timestamp, boolean trim)` Restore a previous state to all the private fields of this rollbackable object.
`java.lang.Object`	`$SET$CHECKPOINT(Checkpoint checkpoint)` Set the checkpoint object of this rollbackable object.
`boolean`	`add(java.lang.Object o)` Add an element to this collection.
`boolean`	`addAll(Collection c)` Add the contents of a given collection to this collection.
`void`	`clear()` Clear the collection, such that a subsequent call to isEmpty() would return true.
`boolean`	`contains(java.lang.Object o)` Test whether this collection contains a given object as one of its elements.
`boolean`	`containsAll(Collection c)` Test whether this collection contains every element in a given collection.
`boolean`	`equals(java.lang.Object o)` Test whether this collection is equal to some object.
`int`	`hashCode()` Obtain a hash code for this collection.
`boolean`	`isEmpty()` Test whether this collection is empty, that is, if size() == 0.
`java.util.Iterator`	`iterator()` Obtain an Iterator over this collection.
`boolean`	`remove(java.lang.Object o)` Remove a single occurrence of an object from this collection.
`boolean`	`removeAll(Collection c)` Remove all elements of a given collection from this collection.
`boolean`	`retainAll(Collection c)` Remove all elements of this collection that are not contained in a given collection.
`int`	`size()` Get the number of elements in this collection.
`java.lang.Object[]`	`toArray()` Copy the current contents of this collection into an array.
`java.lang.Object[]`	`toArray(java.lang.Object[] a)` Copy the current contents of this collection into an array.

- Method Detail
  - add
```
boolean add(java.lang.Object o)
```
    Add an element to this collection.
    
    Parameters:
    
    o - the object to add.
    
    Returns:
    
    true if the collection was modified as a result of this action.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this collection does not support the add operation.
    
    java.lang.ClassCastException - if o cannot be added to this collection due to its type.
    
    java.lang.NullPointerException - if o is null and this collection doesn't support the addition of null values.
    
    java.lang.IllegalArgumentException - if o cannot be added to this collection for some other reason.
  - addAll
```
boolean addAll(Collection c)
```
    Add the contents of a given collection to this collection.
    
    Parameters:
    
    c - the collection to add.
    
    Returns:
    
    true if the collection was modified as a result of this action.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this collection does not support the addAll operation.
    
    java.lang.ClassCastException - if some element of c cannot be added to this collection due to its type.
    
    java.lang.NullPointerException - if some element of c is null and this collection does not support the addition of null values.
    
    java.lang.NullPointerException - if c itself is null.
    
    java.lang.IllegalArgumentException - if some element of c cannot be added to this collection for some other reason.
  - clear
```
void clear()
```
    Clear the collection, such that a subsequent call to isEmpty() would return true.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this collection does not support the clear operation.
  - contains
```
boolean contains(java.lang.Object o)
```
    Test whether this collection contains a given object as one of its elements.
    
    Parameters:
    
    o - the element to look for.
    
    Returns:
    
    true if this collection contains at least one element e such that o == null ? e == null : o.equals(e).
    
    Throws:
    
    java.lang.ClassCastException - if the type of o is not a valid type for this collection.
    
    java.lang.NullPointerException - if o is null and this collection doesn't support null values.
  - containsAll
```
boolean containsAll(Collection c)
```
    Test whether this collection contains every element in a given collection.
    
    Parameters:
    
    c - the collection to test for.
    
    Returns:
    
    true if for every element o in c, contains(o) would return true.
    
    Throws:
    
    java.lang.ClassCastException - if the type of any element in c is not a valid type for this collection.
    
    java.lang.NullPointerException - if some element of c is null and this collection does not support null values.
    
    java.lang.NullPointerException - if c itself is null.
  - equals
```
boolean equals(java.lang.Object o)
```
    Test whether this collection is equal to some object. The Collection interface does not explicitly require any behaviour from this method, and it may be left to the default implementation provided by Object. The Set and List interfaces do, however, require specific behaviour from this method.
    If an implementation of Collection, which is not also an implementation of Set or List, should choose to implement this method, it should take care to obey the contract of the equals method of Object. In particular, care should be taken to return false when o is a Set or a List, in order to preserve the symmetry of the relation.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    o - the object to compare to this collection.
    
    Returns:
    
    true if the o is equal to this collection.
  - hashCode
```
int hashCode()
```
    Obtain a hash code for this collection. The Collection interface does not explicitly require any behaviour from this method, and it may be left to the default implementation provided by Object. The Set and List interfaces do, however, require specific behaviour from this method.
    If an implementation of Collection, which is not also an implementation of Set or List, should choose to implement this method, it should take care to obey the contract of the hashCode method of Object. Note that this method renders it impossible to correctly implement both Set and List, as the required implementations are mutually exclusive.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a hash code for this collection.
  - isEmpty
```
boolean isEmpty()
```
    Test whether this collection is empty, that is, if size() == 0.
    
    Returns:
    
    true if this collection contains no elements.
  - iterator
```
java.util.Iterator iterator()
```
    Obtain an Iterator over this collection.
    
    Returns:
    
    an Iterator over the elements of this collection, in any order.
  - remove
```
boolean remove(java.lang.Object o)
```
    Remove a single occurrence of an object from this collection. That is, remove an element e, if one exists, such that o == null ? e == null : o.equals(e).
    
    Parameters:
    
    o - the object to remove.
    
    Returns:
    
    true if the collection changed as a result of this call, that is, if the collection contained at least one occurrence of o.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this collection does not support the remove operation.
    
    java.lang.ClassCastException - if the type of o is not a valid type for this collection.
    
    java.lang.NullPointerException - if o is null and the collection doesn't support null values.
  - removeAll
```
boolean removeAll(Collection c)
```
    Remove all elements of a given collection from this collection. That is, remove every element e such that c.contains(e).
    
    Parameters:
    
    c - The collection of objects to be removed.
    
    Returns:
    
    true if this collection was modified as a result of this call.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this collection does not support the removeAll operation.
    
    java.lang.ClassCastException - if the type of any element in c is not a valid type for this collection.
    
    java.lang.NullPointerException - if some element of c is null and this collection does not support removing null values.
    
    java.lang.NullPointerException - if c itself is null.
  - retainAll
```
boolean retainAll(Collection c)
```
    Remove all elements of this collection that are not contained in a given collection. That is, remove every element e such that !c.contains(e).
    
    Parameters:
    
    c - The collection of objects to be retained.
    
    Returns:
    
    true if this collection was modified as a result of this call.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this collection does not support the retainAll operation.
    
    java.lang.ClassCastException - if the type of any element in c is not a valid type for this collection.
    
    java.lang.NullPointerException - if some element of c is null and this collection does not support retaining null values.
    
    java.lang.NullPointerException - if c itself is null.
  - size
```
int size()
```
    Get the number of elements in this collection.
    
    Returns:
    
    the number of elements in the collection.
  - toArray
```
java.lang.Object[] toArray()
```
    Copy the current contents of this collection into an array.
    
    Returns:
    
    an array of type Object[] and length equal to the size of this collection, containing the elements currently in this collection, in any order.
  - toArray
```
java.lang.Object[] toArray(java.lang.Object[] a)
```
    Copy the current contents of this collection into an array. If the array passed as an argument has length less than the size of this collection, an array of the same run-time type as a, and length equal to the size of this collection, is allocated using Reflection. Otherwise, a itself is used. The elements of this collection are copied into it, and if there is space in the array, the following element is set to null. The resultant array is returned. Note: The fact that the following element is set to null is only useful if it is known that this collection does not contain any null elements.
    
    Parameters:
    
    a - the array to copy this collection into.
    
    Returns:
    
    an array containing the elements currently in this collection, in any order.
    
    Throws:
    
    java.lang.ArrayStoreException - if the type of any element of the collection is not a subtype of the element type of a.
  - $COMMIT
```
void $COMMIT(long timestamp)
```
    Description copied from interface: Rollbackable
    
    Commit changes up to the given timestamp, but not including changes made at timestamp and afterward.
    
    Specified by:
    
    $COMMIT in interface Rollbackable
    
    Parameters:
    
    timestamp - The timestamp.
  - $RESTORE
```
void $RESTORE(long timestamp,
              boolean trim)
```
    Description copied from interface: Rollbackable
    
    Restore a previous state to all the private fields of this rollbackable object.
    
    Specified by:
    
    $RESTORE in interface Rollbackable
    
    Parameters:
    
    timestamp - The timestamp taken at the time when the previous state was recorded.
    
    trim - Whether to delete the records used for the rollback.
    
    See Also:
    
    Checkpoint.rollback(long, boolean)
  - $GET$CHECKPOINT
```
Checkpoint $GET$CHECKPOINT()
```
    Description copied from interface: Rollbackable
    
    Get the checkpoint object that monitors this rollbackable object.
    
    Specified by:
    
    $GET$CHECKPOINT in interface Rollbackable
    
    Returns:
    
    The checkpoint object.
  - $SET$CHECKPOINT
```
java.lang.Object $SET$CHECKPOINT(Checkpoint checkpoint)
```
    Description copied from interface: Rollbackable
    
    Set the checkpoint object of this rollbackable object. A merge operation is performed on the current checkpoint object and the new checkpoint object, so that the two checkpoint objects monitor the same set of objects when this function returns.
    
    Specified by:
    
    $SET$CHECKPOINT in interface Rollbackable
    
    Parameters:
    
    checkpoint - The new checkpoint object.
    
    Returns:
    
    This rollbackable object itself.
    
    See Also:
    
    Checkpoint.setCheckpoint(Checkpoint)

Interface Collection

Method Summary

Method Detail

add

addAll

clear

contains

containsAll

equals

hashCode

isEmpty

iterator

remove

removeAll

retainAll

size

toArray

toArray

$COMMIT

$RESTORE

$GET$CHECKPOINT

$SET$CHECKPOINT