Berkeley DB version 4.2.52

## com.sleepycat.bdb.collection
Class StoredIterator

    java.lang.Object
      |
      +--com.sleepycat.bdb.collection.StoredIterator

All Implemented Interfaces:
  Cloneable, Iterator, ListIterator

public class StoredIterator
extends Object
implements ListIterator, Cloneable

The Iterator returned by all stored collections.

While in general this class conforms to the `Iterator` interface, it is important to note that all iterators for stored collections must be explicitly closed with `close()`. The static method `close(java.util.Iterator)` allows calling close for all iterators without harm to iterators that are not from stored collections, and also avoids casting. If a stored iterator is not closed, unpredictable behavior including process death may result.

This class implements the `Iterator` interface for all stored iterators. It also implements `ListIterator` because some list iterator methods apply to all stored iterators, for example, `previous()` and `hasPrevious()`. Other list iterator methods are always supports for lists, but for other types of collections are only supported under certain conditions. For example, `nextIndex()` and `previousIndex()` are only supported when record number keys are used, while `add(java.lang.Object)` and `set(java.lang.Object)` are supported only under certain other conditions. See the individual method descriptions for more information.

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

- `close()`
- `close(Iterator)`
- `getCollection()`

Method Summary
`void` `add(Object value)` Inserts the specified element into the list or inserts a duplicate into other types of collections (optional operation).
`void` `close()` Closes this iterator.
`static void` `close(Iterator i)` Closes the given iterator using `close()` if it is a `StoredIterator`.
`int` `count()` Returns the number of elements having the same key value as the key value of the element last returned by next() or previous().
`StoredCollection` `getCollection()` Returns the collection associated with this iterator.
`boolean` `getLockForWrite()` Returns whether write-locks will be obtained when reading with this cursor.
`boolean` `hasNext()` Returns true if this iterator has more elements when traversing in the forward direction.
`boolean` `hasPrevious()` Returns true if this iterator has more elements when traversing in the reverse direction.
`Object` `next()` Returns the next element in the interation.
`int` `nextIndex()` Returns the index of the element that would be returned by a subsequent call to next.
`Object` `previous()` Returns the next element in the interation.
`int` `previousIndex()` Returns the index of the element that would be returned by a subsequent call to previous.
`void` `remove()` Removes the last element that was returned by next or previous (optional operation).
`void` `set(Object value)` Replaces the last element returned by next or previous with the specified element (optional operation).
`void` `setLockForWrite(boolean lockForWrite)` Changes whether write-locks will be obtained when reading with this cursor.

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

Method Detail

### close

    public static void close(Iterator i)

  Closes the given iterator using `close()` if it is a `StoredIterator`. If the given iterator is not a `StoredIterator`, this method does nothing.

  Parameters:
    `i` - is the iterator to close.
  Throws:
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### getLockForWrite

    public final boolean getLockForWrite()

  Returns whether write-locks will be obtained when reading with this cursor. Obtaining write-locks can prevent deadlocks when reading and then modifying data.

  Returns:
    the write-lock setting.

### setLockForWrite

    public void setLockForWrite(boolean lockForWrite)

  Changes whether write-locks will be obtained when reading with this cursor. Obtaining write-locks can prevent deadlocks when reading and then modifying data.

  Parameters:
    `lockForWrite` - the write-lock setting.

### hasNext

    public boolean hasNext()

  Returns true if this iterator has more elements when traversing in the forward direction. False is returned if the iterator has been closed. This method conforms to the `Iterator.hasNext()` interface.

  Specified by:
    `hasNext` in interface `ListIterator`
  Returns:
    whether `next()` will succeed.
  Throws:
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### hasPrevious

    public boolean hasPrevious()

  Returns true if this iterator has more elements when traversing in the reverse direction. It returns false if the iterator has been closed. This method conforms to the `ListIterator.hasPrevious()` interface.

  Specified by:
    `hasPrevious` in interface `ListIterator`
  Returns:
    whether `previous()` will succeed.
  Throws:
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### next

    public Object next()

  Returns the next element in the interation. This method conforms to the `Iterator.next()` interface.

  Specified by:
    `next` in interface `ListIterator`
  Returns:
    the next element.
  Throws:
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### previous

    public Object previous()

  Returns the next element in the interation. This method conforms to the `ListIterator.previous()` interface.

  Specified by:
    `previous` in interface `ListIterator`
  Returns:
    the previous element.
  Throws:
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### nextIndex

    public int nextIndex()

  Returns the index of the element that would be returned by a subsequent call to next. This method conforms to the `ListIterator.nextIndex()` interface except that it returns Integer.MAX_VALUE for stored lists when positioned at the end of the list, rather than returning the list size as specified by the ListIterator interface. This is because the database size is not available.

  Specified by:
    `nextIndex` in interface `ListIterator`
  Returns:
    the next index.
  Throws:
    `UnsupportedOperationException` - if this iterator's collection does not use record number keys.
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### previousIndex

    public int previousIndex()

  Returns the index of the element that would be returned by a subsequent call to previous. This method conforms to the `ListIterator.previousIndex()` interface.

  Specified by:
    `previousIndex` in interface `ListIterator`
  Returns:
    the previous index.
  Throws:
    `UnsupportedOperationException` - if this iterator's collection does not use record number keys.
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### set

    public void set(Object value)

  Replaces the last element returned by next or previous with the specified element (optional operation). This method conforms to the `ListIterator.set(java.lang.Object)` interface.

  Specified by:
    `set` in interface `ListIterator`
  Parameters:
    `value` - the new value.
  Throws:
    `UnsupportedOperationException` - if the collection is a `StoredKeySet` (the set returned by `Map.keySet()`), or if duplicates are sorted since this would change the iterator position, or if the collection is indexed, or if the collection is read-only.
    `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 `DbException` is thrown.

### remove

    public void remove()

  Removes the last element that was returned by next or previous (optional operation). This method conforms to the `ListIterator.remove()` interface except that when the collection is a list and the RECNO-RENUMBER access method is not used, list indices will not be renumbered.

  Specified by:
    `remove` in interface `ListIterator`
  Throws:
    `UnsupportedOperationException` - if the collection is a sublist, or if the collection is read-only.
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### add

    public void add(Object value)

  Inserts the specified element into the list or inserts a duplicate into other types of collections (optional operation). This method conforms to the `ListIterator.add(java.lang.Object)` interface when the collection is a list and the RECNO-RENUMBER access method is used. Otherwise, this method may only be called when duplicates are allowed. If duplicates are unsorted, the new value will be inserted in the same manner as list elements. If duplicates are sorted, the new value will be inserted in sort order.

  Specified by:
    `add` in interface `ListIterator`
  Parameters:
    `value` - the new value.
  Throws:
    `UnsupportedOperationException` - if the collection is a sublist, or if the collection is indexed, or if the collection is read-only, or if the collection is a list and the RECNO-RENUMBER access method was not used, or if the collection is not a list and duplicates are not allowed.
    `IllegalStateException` - if the collection is empty and is not a list with RECNO-RENUMBER access.
    `IllegalArgumentException` - if a duplicate value is being added that already exists and duplicates are sorted.
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### count

    public int count()

  Returns the number of elements having the same key value as the key value of the element last returned by next() or previous(). If no duplicates are allowed, 1 is always returned.

  Returns:
    the number of duplicates.
  Throws:
    `IllegalStateException` - if next() or previous() has not been called for this iterator, or if remove() or add() were called after the last call to next() or previous().

### close

    public void close()

  Closes this iterator. This method does not exist in the standard `Iterator` or `ListIterator` interfaces.

  After being closed, only the `hasNext()` and `hasPrevious()` methods may be called and these will return false. `close()` may also be called again and will do nothing. If other methods are called a `NullPointerException` will generally be thrown.

  Throws:
    `RuntimeExceptionWrapper` - if a `DbException` is thrown.

### getCollection

    public final StoredCollection getCollection()

  Returns the collection associated with this iterator. This method does not exist in the standard `Iterator` or `ListIterator` interfaces.

  Returns:
    the collection associated with this iterator.

Berkeley DB version 4.2.52

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