com.sleepycat.collections

Class StoredIterator<E>

java.lang.Object

com.sleepycat.collections.StoredIterator<E>

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, java.lang.Cloneable, java.util.Iterator<E>, java.util.ListIterator<E>

public class StoredIterator<E>
extends java.lang.Object
implements java.util.ListIterator<E>, java.lang.Cloneable, java.io.Closeable

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 supported for lists, but for other types of collections are only supported under certain conditions. See nextIndex(), previousIndex(), add(E) and set(E) for details.

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)
• count()
• getCollection()
• setReadModifyWrite(boolean)
• isReadModifyWrite()

Author:

Mark Hayes

Method Summary

Modifier and Type	Method and Description
void	add(E 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(java.util.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<E>	getCollection() Returns the collection associated with this iterator.
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.
boolean	isReadModifyWrite() Returns whether write-locks will be obtained when reading with this cursor.
E	next() Returns the next element in the iteration.
int	nextIndex() Returns the index of the element that would be returned by a subsequent call to next.
E	previous() Returns the next element in the iteration.
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(E value) Replaces the last element returned by next or previous with the specified element (optional operation).
void	setReadModifyWrite(boolean lockForWrite) Changes whether write-locks will be obtained when reading with this cursor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator

forEachRemaining

Method Detail

close

public static void close(java.util.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 checked exception is thrown, including a DatabaseException on BDB (C edition).

isReadModifyWrite

public final boolean isReadModifyWrite()

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.

setReadModifyWrite

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

Specified by:

hasNext in interface java.util.ListIterator<E>

Returns:

whether next() will succeed.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C edition).

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

Returns:

whether previous() will succeed.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C edition).

next

public E next()

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

Specified by:

next in interface java.util.Iterator<E>

Specified by:

next in interface java.util.ListIterator<E>

Returns:

the next element.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C Edition).

previous

public E previous()

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

Specified by:

previous in interface java.util.ListIterator<E>

Returns:

the previous element.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C Edition).

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

Returns:

the next index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.UnsupportedOperationException - if this iterator's collection does not use record number keys.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C Edition).

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

Returns:

the previous index.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.UnsupportedOperationException - if this iterator's collection does not use record number keys.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C Edition).

set

public void set(E value)

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

In order to call this method, if the underlying Database is transactional then a transaction must be active when creating the iterator.

Specified by:

set in interface java.util.ListIterator<E>

Parameters:

value - the new value.

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.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.

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).

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.

In order to call this method, if the underlying Database is transactional then a transaction must be active when creating the iterator.

Note that for the JE product, RECNO-RENUMBER databases are not supported, and therefore list indices are never renumbered by this method.

Specified by:

remove in interface java.util.Iterator<E>

Specified by:

remove in interface java.util.ListIterator<E>

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

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).

add

public void add(E 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(E) 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.

Note that for the JE product, RECNO-RENUMBER databases are not supported, and therefore this method may only be used to add duplicates.

Specified by:

add in interface java.util.ListIterator<E>

Parameters:

value - the new value.

Throws:

OperationFailureException - if one of the Write Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

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

java.lang.IllegalStateException - if the collection is empty and is not a list with RECNO-RENUMBER access.

java.lang.IllegalArgumentException - if a duplicate value is being added that already exists and duplicates are sorted.

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C Edition).

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. This method does not exist in the standard Iterator or ListIterator interfaces.

Returns:

the number of duplicates.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

java.lang.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.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

RuntimeExceptionWrapper - if a checked exception is thrown, including a DatabaseException on BDB (C Edition).

getCollection

public final StoredCollection<E> 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.