Berkeley DB version 4.3.29

## com.sleepycat.collections
Class StoredCollection

    java.lang.Object
      com.sleepycat.collections.StoredContainer
          com.sleepycat.collections.StoredCollection

All Implemented Interfaces:
  Cloneable, Collection

Direct Known Subclasses:
  StoredEntrySet, StoredKeySet, StoredList, StoredValueSet

public abstract class StoredCollection
extends StoredContainer
implements Collection

A abstract base class for all stored collections. This class, and its base class `StoredContainer`, provide implementations of most methods in the `Collection` interface. Other methods, such as `Collection.add(java.lang.Object)` and `Collection.remove(java.lang.Object)`, are provided by concrete classes that extend this class.

Note that this class does not conform to the standard Java collections interface in the following ways:

- The `StoredContainer.size()` method always throws `UnsupportedOperationException` because, for performance reasons, databases do not maintain their total record count.
- All iterators must be explicitly closed using `StoredIterator.close()` or `StoredIterator.close(java.util.Iterator)` to release the underlying database cursor resources.

In addition, this class provides the following methods for stored collections only. Note that the use of these methods is not compatible with the standard Java collections interface.

- `iterator(boolean)`
- `join(com.sleepycat.collections.StoredContainer[], java.lang.Object[], com.sleepycat.db.JoinConfig)`
- `toList()`

Method Summary
`boolean` `addAll(Collection coll)` Adds all of the elements in the specified collection to this collection (optional operation).
`boolean` `containsAll(Collection coll)` Returns true if this collection contains all of the elements in the specified collection.
`boolean` `equals(Object other)` Compares the specified object with this collection for equality.
`int` `hashCode()`
`Iterator` `iterator()` Returns an iterator over the elements in this collection.
`StoredIterator` `iterator(boolean writeAllowed)` Returns a read or read-write iterator over the elements in this collection.
`StoredIterator` `join(StoredContainer[] indices, Object[] indexKeys, JoinConfig joinConfig)` Returns an iterator representing an equality join of the indices and index key values specified.
`boolean` `removeAll(Collection coll)` Removes all this collection's elements that are also contained in the specified collection (optional operation).
`boolean` `retainAll(Collection coll)` Retains only the elements in this collection that are contained in the specified collection (optional operation).
`Object[]` `toArray()` Returns an array of all the elements in this collection.
`Object[]` `toArray(Object[] a)` Returns an array of all the elements in this collection whose runtime type is that of the specified array.
`List` `toList()` Returns a copy of this collection as an ArrayList.
`String` `toString()` Converts the collection to a string representation for debugging.

Methods inherited from class com.sleepycat.collections.StoredContainer
`areDuplicatesAllowed, areDuplicatesOrdered, areKeysRenumbered, clear, isDirtyRead, isDirtyReadAllowed, isEmpty, isOrdered, isSecondary, isTransactional, isWriteAllowed, size`

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

Methods inherited from interface java.util.Collection
`add, clear, contains, isEmpty, remove, size`

Method Detail

### iterator

    public Iterator iterator()

  Returns an iterator over the elements in this collection. The iterator will be read-only if the collection is read-only. This method conforms to the `Collection.iterator()` interface.

  Specified by:
    `iterator` in interface `Collection`
  Returns:
    a `StoredIterator` for this collection.
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.
  See Also:
    `StoredContainer.isWriteAllowed()`

### iterator

    public StoredIterator iterator(boolean writeAllowed)

  Returns a read or read-write iterator over the elements in this collection. This method does not exist in the standard `Collection` interface.

  Parameters:
    `writeAllowed` - is true to open a read-write iterator or false to open a read-only iterator. If the collection is read-only the iterator will always be read-only.
  Returns:
    a `StoredIterator` for this collection.
  Throws:
    `IllegalStateException` - if writeAllowed is true but the collection is read-only.
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.
  See Also:
    `StoredContainer.isWriteAllowed()`

### toArray

    public Object[] toArray()

  Returns an array of all the elements in this collection. This method conforms to the `Collection.toArray()` interface.

  Specified by:
    `toArray` in interface `Collection`
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### toArray

    public Object[] toArray(Object[] a)

  Returns an array of all the elements in this collection whose runtime type is that of the specified array. This method conforms to the `Collection.toArray(Object[])` interface.

  Specified by:
    `toArray` in interface `Collection`
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### containsAll

    public boolean containsAll(Collection coll)

  Returns true if this collection contains all of the elements in the specified collection. This method conforms to the `Collection.containsAll(java.util.Collection)` interface.

  Specified by:
    `containsAll` in interface `Collection`
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### addAll

    public boolean addAll(Collection coll)

  Adds all of the elements in the specified collection to this collection (optional operation). This method calls the `Collection.add(Object)` method of the concrete collection class, which may or may not be supported. This method conforms to the `Collection.addAll(java.util.Collection)` interface.

  Specified by:
    `addAll` in interface `Collection`
  Throws:
    `UnsupportedOperationException` - if the collection is read-only, or if the collection is indexed, or if the add method is not supported by the concrete collection.
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### removeAll

    public boolean removeAll(Collection coll)

  Removes all this collection's elements that are also contained in the specified collection (optional operation). This method conforms to the `Collection.removeAll(java.util.Collection)` interface.

  Specified by:
    `removeAll` in interface `Collection`
  Throws:
    `UnsupportedOperationException` - if the collection is read-only.
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### retainAll

    public boolean retainAll(Collection coll)

  Retains only the elements in this collection that are contained in the specified collection (optional operation). This method conforms to the `Collection.removeAll(java.util.Collection)` interface.

  Specified by:
    `retainAll` in interface `Collection`
  Throws:
    `UnsupportedOperationException` - if the collection is read-only.
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### equals

    public boolean equals(Object other)

  Compares the specified object with this collection for equality. A value comparison is performed by this method and the stored values are compared rather than calling the equals() method of each element. This method conforms to the `Collection.equals(java.lang.Object)` interface.

  Specified by:
    `equals` in interface `Collection`
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### hashCode

    public int hashCode()

  Specified by:
    `hashCode` in interface `Collection`

### toList

    public List toList()

  Returns a copy of this collection as an ArrayList. This is the same as `toArray()` but returns a collection instead of an array.

  Returns:
    an `ArrayList` containing a copy of all elements in this collection.
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### toString

    public String toString()

  Converts the collection to a string representation for debugging. WARNING: All elements will be converted to strings and returned and therefore the returned string may be very large.

  Returns:
    the string representation.
  Throws:
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

### join

    public StoredIterator join(StoredContainer[] indices,
                               Object[] indexKeys,
                               JoinConfig joinConfig)

  Returns an iterator representing an equality join of the indices and index key values specified. This method does not exist in the standard `Collection` interface.

  The returned iterator supports only the two methods: hasNext() and next(). All other methods will throw UnsupportedOperationException.

  Parameters:
    `indices` - is an array of indices with elements corresponding to those in the indexKeys array.
    `indexKeys` - is an array of index key values identifying the elements to be selected.
    `joinConfig` - is the join configuration, or null to use the default configuration.
  Returns:
    an iterator over the elements in this collection that match all specified index key values.
  Throws:
    `IllegalArgumentException` - if this collection is indexed or if a given index does not have the same store as this collection.
    `RuntimeExceptionWrapper` - if a `DatabaseException` is thrown.

Berkeley DB version 4.3.29

Copyright (c) 1996-2004 Sleepycat Software, Inc. - All rights reserved.