StoredCollection (Oracle - Berkeley DB Java API)
Date: 2020-06-01

Package com.sleepycat.collections

## Class StoredCollection<E>

- java.lang.Object
- - com.sleepycat.collections.StoredContainer
  - - com.sleepycat.collections.StoredCollection<E>

- All Implemented Interfaces:
    `java.lang.Cloneable`, `java.lang.Iterable<E>`, `java.util.Collection<E>`
  Direct Known Subclasses:
    `StoredEntrySet`, `StoredKeySet`, `StoredList`, `StoredValueSet`

      public abstract class StoredCollection<E>
      extends StoredContainer
      implements java.util.Collection<E>

  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 `add(java.lang.Object, java.lang.Object)` and `Collection.remove(java.lang.Object)`, are provided by concrete classes that extend this class.

  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.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `DEFAULT_ITERATOR_BLOCK_SIZE` | The default number of records read at one time by iterators.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `addAll​(java.util.Collection<? extends E> coll)` | Adds all of the elements in the specified collection to this collection (optional operation).
    `boolean` | `containsAll​(java.util.Collection<?> coll)` | Returns true if this collection contains all of the elements in the specified collection.
    `boolean` | `equals​(java.lang.Object other)` | Compares the specified object with this collection for equality.
    `int` | `getIteratorBlockSize()` | Returns the number of records read at one time by iterators returned by the `iterator()` method.
    `int` | `hashCode()` |
    `java.util.Iterator<E>` | `iterator()` | Returns an iterator over the elements in this collection.
    `StoredIterator<E>` | `iterator​(boolean writeAllowed)` | Deprecated. Please use `storedIterator()` or `storedIterator(boolean)` instead.
    `StoredIterator<E>` | `join​(StoredContainer[] indices, java.lang.Object[] indexKeys, JoinConfig joinConfig)` | Returns an iterator representing an equality join of the indices and index key values specified.
    `boolean` | `removeAll​(java.util.Collection<?> coll)` | Removes all this collection's elements that are also contained in the specified collection (optional operation).
    `boolean` | `retainAll​(java.util.Collection<?> coll)` | Retains only the elements in this collection that are contained in the specified collection (optional operation).
    `void` | `setIteratorBlockSize​(int blockSize)` | Changes the number of records read at one time by iterators returned by the `iterator()` method.
    `int` | `size()` | Returns a non-transactional count of the records in the collection or map.
    `StoredIterator<E>` | `storedIterator()` | Returns an iterator over the elements in this collection.
    `StoredIterator<E>` | `storedIterator​(boolean writeAllowed)` | Returns a read or read-write iterator over the elements in this collection.
    `java.lang.Object[]` | `toArray()` | Returns an array of all the elements in this collection.
    `<T> T[]` | `toArray​(T[] a)` | Returns an array of all the elements in this collection whose runtime type is that of the specified array.
    `java.util.List<E>` | `toList()` | Returns a copy of this collection as an ArrayList.
    `java.lang.String` | `toString()` | Converts the collection to a string representation for debugging.

    - ### Methods inherited from class com.sleepycat.collections.StoredContainer

      `areDuplicatesAllowed, areDuplicatesOrdered, areKeyRangesAllowed, areKeysRenumbered, clear, getCursorConfig, isEmpty, isOrdered, isSecondary, isTransactional, isWriteAllowed`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.Collection

      `add, clear, contains, isEmpty, parallelStream, remove, removeIf, spliterator, stream, toArray`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

- - ### Field Detail

    - #### DEFAULT_ITERATOR_BLOCK_SIZE

          public static final int DEFAULT_ITERATOR_BLOCK_SIZE

      The default number of records read at one time by iterators.
      See Also:
        `setIteratorBlockSize(int)`, Constant Field Values

  - ### Method Detail

    - #### getIteratorBlockSize

          public int getIteratorBlockSize()

      Returns the number of records read at one time by iterators returned by the `iterator()` method. By default this value is `DEFAULT_ITERATOR_BLOCK_SIZE`.
      Returns:
        the number of records.

    - #### setIteratorBlockSize

          public void setIteratorBlockSize​(int blockSize)

      Changes the number of records read at one time by iterators returned by the `iterator()` method. By default this value is `DEFAULT_ITERATOR_BLOCK_SIZE`.
      Parameters:
        `blockSize` - the number of records.
      Throws:
        `java.lang.IllegalArgumentException` - if the blockSize is less than two.

    - #### iterator

          public java.util.Iterator<E> 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.

      The iterator returned by this method does not keep a database cursor open and therefore it does not need to be closed. It reads blocks of records as needed, opening and closing a cursor to read each block of records. The number of records per block is 10 by default and can be changed with `setIteratorBlockSize(int)`.

      Because this iterator does not keep a cursor open, if it is used without transactions, the iterator does not have cursor stability characteristics. In other words, the record at the current iterator position can be changed or deleted by another thread. To prevent this from happening, call this method within a transaction or use the `storedIterator()` method instead.

      Specified by:
        `iterator` in interface `java.util.Collection<E>`
      Specified by:
        `iterator` in interface `java.lang.Iterable<E>`
      Returns:
        a standard `Iterator` for this collection.
      See Also:
        `StoredContainer.isWriteAllowed()`

    - #### storedIterator

          public StoredIterator<E> storedIterator()

      Returns an iterator over the elements in this collection. The iterator will be read-only if the collection is read-only. This method does not exist in the standard `Collection` interface.

      If `Iterator.set` or `Iterator.remove` will be called and the underlying Database is transactional, then a transaction must be active when calling this method and must remain active while using the iterator.

      Warning: The iterator returned must be explicitly closed using `StoredIterator.close()` or `StoredIterator.close(java.util.Iterator)` to release the underlying database cursor resources.

      Returns:
        a `StoredIterator` for this collection.
      See Also:
        `StoredContainer.isWriteAllowed()`

    - #### storedIterator

          public StoredIterator<E> storedIterator​(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.

      If `Iterator.set` or `Iterator.remove` will be called and the underlying Database is transactional, then a transaction must be active when calling this method and must remain active while using the iterator.

      Warning: The iterator returned must be explicitly closed using `StoredIterator.close()` or `StoredIterator.close(java.util.Iterator)` to release the underlying database cursor resources.

      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:
        `java.lang.IllegalStateException` - if writeAllowed is true but the collection is read-only.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).
      See Also:
        `StoredContainer.isWriteAllowed()`

    - #### iterator

          @Deprecated
          public StoredIterator<E> iterator​(boolean writeAllowed)

      Deprecated.
      Please use `storedIterator()` or `storedIterator(boolean)` instead. Because the iterator returned must be closed, the method name `iterator` is confusing since standard Java iterators do not need to be closed.
      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.

    - #### toArray

          public java.lang.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 `java.util.Collection<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### toArray

          public <T> T[] toArray​(T[] 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 `java.util.Collection<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### containsAll

          public boolean containsAll​(java.util.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 `java.util.Collection<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### addAll

          public boolean addAll​(java.util.Collection<? extends E> 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<? extends E>)` interface.
      Specified by:
        `addAll` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.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 checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### removeAll

          public boolean removeAll​(java.util.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 `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is read-only.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### retainAll

          public boolean retainAll​(java.util.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 `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is read-only.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### equals

          public boolean equals​(java.lang.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 `java.util.Collection<E>`
      Overrides:
        `equals` in class `java.lang.Object`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Collection<E>`
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toList

          public java.util.List<E> 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 checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### toString

          public java.lang.String toString()

      Converts the collection to a string representation for debugging. WARNING: The returned string may be very large.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the string representation.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### size

          public int size()

      Description copied from class: `StoredContainer`
      Returns a non-transactional count of the records in the collection or map. This method conforms to the `Collection.size()` and `Map.size()` interfaces.
      Specified by:
        `size` in interface `java.util.Collection<E>`
      Specified by:
        `size` in class `StoredContainer`
      Returns:
        the number of records.

    - #### join

          public StoredIterator<E> join​(StoredContainer[] indices,
                                        java.lang.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.

      Warning: The iterator returned must be explicitly closed using `StoredIterator.close()` or `StoredIterator.close(java.util.Iterator)` to release the underlying database cursor resources.

      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:
        `java.lang.IllegalArgumentException` - if this collection is indexed or if a given index does not have the same store as this collection.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

Copyright (c) 1996, 2020 Oracle and/or its affiliates. All rights reserved.