Interface COM.odi.coll.Cursor

public interface Cursor

extends IPersistent, Enumeration

The order of iteration for a list (an ordered collection) is the list's order. The order of iteration for other collections is arbitrary. That is, there is a specific order, but you have no control over what that order is.

A cursor becomes null if it is positioned past the last element, or before the first element. A cursor becomes invalid if the element to which it points is deleted. A cursor cannot be both null and invalid. If a cursor is nonnull and valid, it points to one particular element of the collection. The more() method indicates whether or not a cursor is nonnull. The valid() method indicates whether or not a cursor is valid.

If a cursor is null, it does not matter whether it was positioned before the first element or after the last element. There is just one null state. You cannot invoke next() or previous() to reposition the cursor and make it nonnull. But you can invoke first() or last() to make the cursor nonnull.

A cursor can be safe or unsafe. The safety attribute is determined when the cursor is created and cannot be changed. You can only specify a safe cursor for a collection if the collection has MAINTAIN_CURSORS behavior. ObjectStore throws COM.odi.coll.CollectionException if you try to specify a safe cursor for a collection that does not have MAINTAIN_CURSORS behavior. You cannot create a safe cursor for any kind of dictionary. Trying to causes ObjectStore to throw COM.odi.coll.CollectionException.

If an unsafe cursor becomes invalid, it cannot be repositioned thereafter. In general, if you change something in a collection while an unsafe cursor is bound to the collection, the consequences of subsequent operations on the cursor (or attempts to use the cursor as an argument to a collection method) are undefined. Note that while you can invoke the rebind() method on an invalid cursor, this is not considered to be repositioning the cursor.

Suppose a safe cursor becomes invalid, because the element under it, e, was removed. Let p and s be the predecessor and succcessor, respectively, of e. The safe cursor is now considered to be between p and s. If you invoke the next() method on the cursor, it moves to s. If you invoke the previous() method, it moves to p. See the ObjectStore C++ API Reference for additional information about the properties of safe cursors.

You must use the ObjectStore.destroy() method to explicitly delete every safe cursor before committing the transaction in which the cursor was created. An attempt to commit a transaction in which there are outstanding safe cursors throws CollectionException. There is no finalizer for Cursor class to do this. Since finalizers have no guarantee of running, they are not helpful in this circumstance.

ORDER_BY_ADDRESS

A cursor with this flag has an iteration order that is sorted by virtual memory address.

SAFE

A cursor with this flag is safe.

UPDATE_INSENSITIVE

A cursor with this flag is update-insensitive.

first()

Positions the cursor at the first element in its collection, and returns the first element.

hasMore()

Determines whether or not there are more elements to iterate over in the collection.

hasMoreElements()

Determines whether or not there are more elements to iterate over in the collection.

isNull()

Determines whether or not the cursor is null.

isValid()

Determines whether or not the cursor is valid.

last()

Positions the cursor at the last element in its collection, and returns the last element.

next()

Positions the cursor at the next element in its collection, after the element that it is currently positioned on, and returns that element.

nextElement()

Obtains the element that the cursor is currently positioned on and moves the cursor to the next element.

owner()

Obtains the collection associated with the cursor.

previous()

Positions the cursor at the previous element in its collection, before the element that it is currently positioned on, and returns that element.

rebind(Collection)

Changes the collection associated with this cursor.

retrieve()

Obtains the element that the cursor is positioned on.

  public final static int SAFE

A cursor with this flag is safe. You might use safe cursors when you want to update a collection while you are iterating through it. A safe cursor ensures that the iteration visits elements added since the cursor was bound to the collection and does not visit elements removed since the cursor was bound to the collection. Also, you can reposition a safe cursor if it becomes invalid.

  public final static int ORDER_BY_ADDRESS

A cursor with this flag has an iteration order that is sorted by virtual memory address.

  public final static int UPDATE_INSENSITIVE

A cursor with this flag is update-insensitive. With an update-insensitive cursor, iteration through the elements in the collection is based on a snapshot of the collection elements at the time the cursor was bound to the collection. None of the insertions or removals that were performed on the collection are reflected in the iteration.

  public abstract Collection owner()

Obtains the collection associated with the cursor.

Returns:

The collection associated with the cursor.

  public abstract void rebind(Collection c)

Changes the collection associated with this cursor. Retains the original flags settings. Frees up resources associated with the cursor. For example, this method removes the cursor from the list of safe cursors. You can invoke this method on a null or invalid cursor.

Parameters:

c - The new collection, to which the cursor becomes bound.

  public abstract Object first()

Positions the cursor at the first element in its collection, and returns the first element. If the collection is empty, this method makes the cursor null and returns null. It does not matter whether or not the cursor is invalid.

Returns:

The first element of the collection, or null if the collection is empty.

  public abstract Object last()

Positions the cursor at the last element in its collection, and returns the last element. If the collection is empty, this method makes the cursor null and returns null. It does not matter whether or not the cursor is invalid.

Returns:

The last element of the collection, or null if the collection is empty.

  public abstract Object next()

Positions the cursor at the next element in its collection, after the element that it is currently positioned on, and returns that element. If the cursor is null, this method leaves it null and returns null. If the cursor is at the last element, this method makes the cursor null and returns null. It does not matter whether or not the cursor is invalid.

Returns:

The element of the collection, or null if the cursor is null.

  public abstract Object previous()

Positions the cursor at the previous element in its collection, before the element that it is currently positioned on, and returns that element. If the cursor is null, this method leaves it null and returns null. If the cursor is at the last element, this method makes the cursor null and returns null. It does not matter whether or not the cursor is invalid.

Returns:

The element of the collection, or null if the cursor is null.

  public abstract Object retrieve()

Obtains the element that the cursor is positioned on. The cursor and collection are not affected.

Returns:

The element of the collection.

Throws: InvalidCursorException

If the cursor is invalid.

Throws: NullCursorException

If the cursor is null.

  public abstract boolean hasMore()

Determines whether or not there are more elements to iterate over in the collection.

This method performs exactly the same operation as the hasMoreElements() method. This method is provided because there is a parallel hasMore member function in the C++ interface to ObjectStore. The hasMoreElements() method is provided because it is a standard Java method.

Returns:

True if there are more elements in the collection or if the cursor is invalid. False if the cursor is null.

  public abstract boolean isNull()

Determines whether or not the cursor is null.

Returns:

True if the cursor is null. False if the cursor is nonnull or invalid.

  public abstract boolean isValid()

Determines whether or not the cursor is valid.

Returns:

True if the cursor is valid or null. False if the cursor is invalid.

  public abstract boolean hasMoreElements()

Determines whether or not there are more elements to iterate over in the collection. This method provides an implementation of the hasMoreElements() method of the Enumeration interface.

This method performs exactly the same operation as the hasMore() method. This method is provided because it is a standard Java method. The hasMore() method is provided because there is a parallel hasMore member function in the C++ interface to ObjectStore.

Returns:

True if there are more elements in the collection or if the cursor is invalid. False if the cursor is null.

  public abstract Object nextElement()

Obtains the element that the cursor is currently positioned on and moves the cursor to the next element. This method implements the nextElement() method of the Enumeration interface. However, it performs a function different from next(), which returns the next element and not the current element.

Returns:

The element the cursor is currently positioned on.

Throws: InvalidCursorException

If the cursor is invalid.

Throws: NoSuchElementException

If no more elements exist.