Main Page | Class Hierarchy | Data Structures | Directories | File List | Data Fields | Related Pages
com::sleepycat::collections::StoredIterator

com::sleepycat::collections::StoredIterator Class Reference


Public Member Functions

final boolean isReadModifyWrite ()
void setReadModifyWrite (boolean lockForWrite)
boolean hasNext ()
boolean hasPrevious ()
Object next ()
Object previous ()
int nextIndex ()
int previousIndex ()
void set (Object value)
void remove ()
void add (Object value)
int count ()
void close ()
final StoredCollection getCollection ()

Static Public Member Functions

static void close (Iterator i)

Protected Member Functions

Object clone ()

Detailed Description

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

Author:
Mark Hayes

Definition at line 51 of file StoredIterator.java.

Member Function Documentation

void com::sleepycat::collections::StoredIterator::add (  Object  value  )  [inline]
 

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

Parameters:
value the new value.
Exceptions:
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 DatabaseException is thrown.

Definition at line 425 of file StoredIterator.java.

References close(), hasNext(), next(), com::sleepycat::collections::DataCursor::putAfter(), com::sleepycat::collections::DataCursor::putBefore(), and com::sleepycat::collections::DataCursor::putNoDupData().

Object com::sleepycat::collections::StoredIterator::clone (   )  [inline, protected]
 

Clones this iterator preserving its current position.

Returns:
a new StoredIterator having the same position as this iterator.

Definition at line 110 of file StoredIterator.java.

References com::sleepycat::collections::DataCursor::cloneCursor(), and cursor.

void com::sleepycat::collections::StoredIterator::close (   )  [inline]
 

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.

Exceptions:
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 540 of file StoredIterator.java.

Referenced by add().

static void com::sleepycat::collections::StoredIterator::close (  Iterator  i  )  [inline, static]
 

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.
Exceptions:
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 62 of file StoredIterator.java.

Referenced by com::sleepycat::collections::StoredList::listIterator().

int com::sleepycat::collections::StoredIterator::count (   )  [inline]
 

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.
Exceptions:
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().

Definition at line 515 of file StoredIterator.java.

References com::sleepycat::collections::DataCursor::count().

final StoredCollection com::sleepycat::collections::StoredIterator::getCollection (   )  [inline]
 

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.

Definition at line 555 of file StoredIterator.java.

boolean com::sleepycat::collections::StoredIterator::hasNext (   )  [inline]
 

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.

Returns:
whether next() will succeed.
Exceptions:
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 158 of file StoredIterator.java.

Referenced by add(), and nextIndex().

boolean com::sleepycat::collections::StoredIterator::hasPrevious (   )  [inline]
 

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.

Returns:
whether previous() will succeed.
Exceptions:
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 188 of file StoredIterator.java.

Referenced by previousIndex().

final boolean com::sleepycat::collections::StoredIterator::isReadModifyWrite (   )  [inline]
 

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.

Definition at line 129 of file StoredIterator.java.

Object com::sleepycat::collections::StoredIterator::next (   )  [inline]
 

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

Returns:
the next element.
Exceptions:
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 217 of file StoredIterator.java.

Referenced by add().

int com::sleepycat::collections::StoredIterator::nextIndex (   )  [inline]
 

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.

Returns:
the next index.
Exceptions:
UnsupportedOperationException if this iterator's collection does not use record number keys.
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 291 of file StoredIterator.java.

References com::sleepycat::collections::DataCursor::getCurrentRecordNumber(), and hasNext().

Object com::sleepycat::collections::StoredIterator::previous (   )  [inline]
 

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

Returns:
the previous element.
Exceptions:
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 250 of file StoredIterator.java.

int com::sleepycat::collections::StoredIterator::previousIndex (   )  [inline]
 

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

Returns:
the previous index.
Exceptions:
UnsupportedOperationException if this iterator's collection does not use record number keys.
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 320 of file StoredIterator.java.

References com::sleepycat::collections::DataCursor::getCurrentRecordNumber(), and hasPrevious().

void com::sleepycat::collections::StoredIterator::remove (   )  [inline]
 

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.

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

Exceptions:
UnsupportedOperationException if the collection is a sublist, or if the collection is read-only.
RuntimeExceptionWrapper if a DatabaseException is thrown.

Definition at line 383 of file StoredIterator.java.

References com::sleepycat::collections::DataCursor::delete().

void com::sleepycat::collections::StoredIterator::set (  Object  value  )  [inline]
 

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

Parameters:
value the new value.
Exceptions:
UnsupportedOperationException if the collection is a StoredKeySet (the set returned by java.util.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 DatabaseException is thrown.

Definition at line 354 of file StoredIterator.java.

References com::sleepycat::collections::DataCursor::putCurrent().

Referenced by com::sleepycat::collections::StoredMapEntry::setValue().

void com::sleepycat::collections::StoredIterator::setReadModifyWrite (  boolean  lockForWrite  )  [inline]
 

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.

Definition at line 142 of file StoredIterator.java.

The documentation for this class was generated from the following file:
Generated on Sun Dec 25 12:15:01 2005 for Berkeley DB 4.4.16 by  doxygen 1.4.2