com.sleepycat.collections

## Class StoredList<E>

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

- All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.List<E>

      public class StoredList<E>
      extends StoredCollection<E>
      implements java.util.List<E>

  A List view of a `Database`.

  For all stored lists the keys of the underlying Database must have record number format, and therefore the store or index must be a RECNO, RECNO-RENUMBER, QUEUE, or BTREE-RECNUM database. Only RECNO-RENUMBER allows true list behavior where record numbers are renumbered following the position of an element that is added or removed. For the other access methods (RECNO, QUEUE, and BTREE-RECNUM), stored Lists are most useful as read-only collections where record numbers are not required to be sequential.

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

  - `append(Object)`

- - ### Field Summary

    - ### Fields inherited from class com.sleepycat.collections.StoredCollection

      `DEFAULT_ITERATOR_BLOCK_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StoredList(Database database, EntityBinding<E> valueEntityBinding, boolean writeAllowed)` Creates a list entity view of a `Database`.
    `StoredList(Database database, EntityBinding<E> valueEntityBinding, PrimaryKeyAssigner keyAssigner)` Creates a list entity view of a `Database` with a `PrimaryKeyAssigner`.
    `StoredList(Database database, EntryBinding<E> valueBinding, boolean writeAllowed)` Creates a list view of a `Database`.
    `StoredList(Database database, EntryBinding<E> valueBinding, PrimaryKeyAssigner keyAssigner)` Creates a list view of a `Database` with a `PrimaryKeyAssigner`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(E value)` Appends the specified element to the end of this list (optional operation).
    `void` | `add(int index, E value)` Inserts the specified element at the specified position in this list (optional operation).
    `boolean` | `addAll(int index, java.util.Collection<? extends E> coll)` Inserts all of the elements in the specified collection into this list at the specified position (optional operation).
    `int` | `append(E value)` Appends a given value returning the newly assigned index.
    `boolean` | `contains(java.lang.Object value)` Returns true if this list contains the specified element.
    `boolean` | `equals(java.lang.Object other)` Compares the specified object with this list for equality.
    `E` | `get(int index)` Returns the element at the specified position in this list.
    `int` | `hashCode()`
    `int` | `indexOf(java.lang.Object value)` Returns the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element.
    `int` | `lastIndexOf(java.lang.Object value)` Returns the index in this list of the last occurrence of the specified element, or -1 if this list does not contain this element.
    `java.util.ListIterator<E>` | `listIterator()` Returns a list iterator of the elements in this list (in proper sequence).
    `java.util.ListIterator<E>` | `listIterator(int index)` Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list.
    `E` | `remove(int index)` Removes the element at the specified position in this list (optional operation).
    `boolean` | `remove(java.lang.Object value)` Removes the first occurrence in this list of the specified element (optional operation).
    `E` | `set(int index, E value)` Replaces the element at the specified position in this list with the specified element (optional operation).
    `java.util.List<E>` | `subList(int fromIndex, int toIndex)` Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive.

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

      `addAll, containsAll, getIteratorBlockSize, iterator, iterator, join, removeAll, retainAll, setIteratorBlockSize, size, storedIterator, storedIterator, toArray, toArray, toList, toString`

    - ### 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.List

      `addAll, clear, containsAll, isEmpty, iterator, removeAll, replaceAll, retainAll, size, sort, spliterator, toArray, toArray`

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

      `parallelStream, removeIf, stream`

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

      `forEach`

- - ### Constructor Detail

    - #### StoredList

          public StoredList(Database database,
                            EntryBinding<E> valueBinding,
                            boolean writeAllowed)

      Creates a list view of a `Database`.
      Parameters:
        `database` - is the Database underlying the new collection.
        `valueBinding` - is the binding used to translate between value buffers and value objects.
        `writeAllowed` - is true to create a read-write collection or false to create a read-only collection.
      Throws:
        `java.lang.IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### StoredList

          public StoredList(Database database,
                            EntityBinding<E> valueEntityBinding,
                            boolean writeAllowed)

      Creates a list entity view of a `Database`.
      Parameters:
        `database` - is the Database underlying the new collection.
        `valueEntityBinding` - is the binding used to translate between key/value buffers and entity value objects.
        `writeAllowed` - is true to create a read-write collection or false to create a read-only collection.
      Throws:
        `java.lang.IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### StoredList

          public StoredList(Database database,
                            EntryBinding<E> valueBinding,
                            PrimaryKeyAssigner keyAssigner)

      Creates a list view of a `Database` with a `PrimaryKeyAssigner`. Writing is allowed for the created list.
      Parameters:
        `database` - is the Database underlying the new collection.
        `valueBinding` - is the binding used to translate between value buffers and value objects.
        `keyAssigner` - is used by the `add(int, E)` and `append(E)` methods to assign primary keys.
      Throws:
        `java.lang.IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### StoredList

          public StoredList(Database database,
                            EntityBinding<E> valueEntityBinding,
                            PrimaryKeyAssigner keyAssigner)

      Creates a list entity view of a `Database` with a `PrimaryKeyAssigner`. Writing is allowed for the created list.
      Parameters:
        `database` - is the Database underlying the new collection.
        `valueEntityBinding` - is the binding used to translate between key/value buffers and entity value objects.
        `keyAssigner` - is used by the `add(int, E)` and `append(E)` methods to assign primary keys.
      Throws:
        `java.lang.IllegalArgumentException` - if formats are not consistently defined or a parameter is invalid.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

  - ### Method Detail

    - #### add

          public void add(int index,
                          E value)

      Inserts the specified element at the specified position in this list (optional operation). This method conforms to the `List.add(int, Object)` interface.
      Specified by:
        `add` in interface `java.util.List<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is a sublist, or if the collection is indexed, or if the collection is read-only, or if the RECNO-RENUMBER access method was not used.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### add

          public boolean add(E value)

      Appends the specified element to the end of this list (optional operation). This method conforms to the `List.add(Object)` interface.
      Specified by:
        `add` in interface `java.util.Collection<E>`
      Specified by:
        `add` in interface `java.util.List<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is a sublist, or if the collection is indexed, or if the collection is read-only, or if the RECNO-RENUMBER access method was not used.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### append

          public int append(E value)

      Appends a given value returning the newly assigned index. If a `PrimaryKeyAssigner` is associated with Store for this list, it will be used to assigned the returned index. Otherwise the Store must be a QUEUE or RECNO database and the next available record number is assigned as the index. This method does not exist in the standard `List` interface.
      Parameters:
        `value` - the value to be appended.
      Returns:
        the assigned index.
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is indexed, or if the collection is read-only, or if the Store has no `PrimaryKeyAssigner` and is not a QUEUE or RECNO database.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### addAll

          public boolean addAll(int index,
                                java.util.Collection<? extends E> coll)

      Inserts all of the elements in the specified collection into this list at the specified position (optional operation). This method conforms to the `List.addAll(int, Collection)` interface.
      Specified by:
        `addAll` in interface `java.util.List<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is a sublist, or if the collection is indexed, or if the collection is read-only, or if the RECNO-RENUMBER access method was not used.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### contains

          public boolean contains(java.lang.Object value)

      Returns true if this list contains the specified element. This method conforms to the `List.contains(java.lang.Object)` interface.
      Specified by:
        `contains` in interface `java.util.Collection<E>`
      Specified by:
        `contains` in interface `java.util.List<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### get

          public E get(int index)

      Returns the element at the specified position in this list. This method conforms to the `List.get(int)` interface.
      Specified by:
        `get` in interface `java.util.List<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### indexOf

          public int indexOf(java.lang.Object value)

      Returns the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element. This method conforms to the `List.indexOf(java.lang.Object)` interface.
      Specified by:
        `indexOf` in interface `java.util.List<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### lastIndexOf

          public int lastIndexOf(java.lang.Object value)

      Returns the index in this list of the last occurrence of the specified element, or -1 if this list does not contain this element. This method conforms to the `List.lastIndexOf(java.lang.Object)` interface.
      Specified by:
        `lastIndexOf` in interface `java.util.List<E>`
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### listIterator

          public java.util.ListIterator<E> listIterator()

      Returns a list iterator of the elements in this list (in proper sequence). The iterator will be read-only if the collection is read-only. This method conforms to the `List.listIterator()` interface.

      For information on cursor stability and iterator block size, see `StoredCollection.iterator()`.

      Specified by:
        `listIterator` in interface `java.util.List<E>`
      Returns:
        a `ListIterator` for this collection.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).
      See Also:
        `StoredContainer.isWriteAllowed()`

    - #### listIterator

          public java.util.ListIterator<E> listIterator(int index)

      Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. The iterator will be read-only if the collection is read-only. This method conforms to the `List.listIterator(int)` interface.

      For information on cursor stability and iterator block size, see `StoredCollection.iterator()`.

      Specified by:
        `listIterator` in interface `java.util.List<E>`
      Returns:
        a `ListIterator` for this collection.
      Throws:
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).
      See Also:
        `StoredContainer.isWriteAllowed()`

    - #### remove

          public E remove(int index)

      Removes the element at the specified position in this list (optional operation). This method conforms to the `List.remove(int)` interface.
      Specified by:
        `remove` in interface `java.util.List<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is a sublist, or if the collection is read-only.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### remove

          public boolean remove(java.lang.Object value)

      Removes the first occurrence in this list of the specified element (optional operation). This method conforms to the `List.remove(Object)` interface.
      Specified by:
        `remove` in interface `java.util.Collection<E>`
      Specified by:
        `remove` in interface `java.util.List<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is a sublist, or if the collection is read-only.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### set

          public E set(int index,
                       E value)

      Replaces the element at the specified position in this list with the specified element (optional operation). This method conforms to the `List.set(int, E)` interface.
      Specified by:
        `set` in interface `java.util.List<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - if the collection is indexed, or if the collection is read-only.
        `java.lang.IllegalArgumentException` - if an entity value binding is used and the primary key of the value given is different than the existing stored primary key.
        `RuntimeExceptionWrapper` - if a checked exception is thrown, including a `DatabaseException` on BDB (C Edition).

    - #### subList

          public java.util.List<E> subList(int fromIndex,
                                           int toIndex)

      Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive. Note that add() and remove() may not be called for the returned sublist. This method conforms to the `List.subList(int, int)` interface.
      Specified by:
        `subList` in interface `java.util.List<E>`
      Throws:
        `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 list 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 `List.equals(java.lang.Object)` interface.
      Specified by:
        `equals` in interface `java.util.Collection<E>`
      Specified by:
        `equals` in interface `java.util.List<E>`
      Overrides:
        `equals` in class `StoredCollection<E>`
      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>`
      Specified by:
        `hashCode` in interface `java.util.List<E>`
      Overrides:
        `hashCode` in class `StoredCollection<E>`

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