Cursor (Apache Directory Shared 0.9.19 API)

All Superinterfaces:

Iterable<E>

All Known Implementing Classes:

AbstractCursor, EmptyCursor, ListCursor, SingletonCursor
```
public interface Cursor<E>
extends Iterable<E>
```
A Cursor for bidirectional traversal over elements in a dataSet. Cursors unlike Iterators or Enumerations may advance to an element by calling next() or previous() which returns true or false if the request succeeds with a viable element at the new position. Operations for relative positioning in larger increments are provided. If the cursor can not advance, then the Cursor is either positioned before the first element or after the last element in which case the user of the Cursor must stop advancing in the respective direction. If an advance succeeds a get() operation retrieves the current object at the Cursors position. Although this interface presumes Cursors can advance bidirectionally, implementations may restrict this by throwing UnsupportedOperationExceptions.

Version:

$Rev$, $Date$

Author:

Apache Directory Project

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`after(E element)` Prepares this Cursor, so a subsequent call to Cursor#previous() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater.
`void`	`afterLast()` Positions this Cursor after the last element.
`boolean`	`available()` Determines whether or not a call to get() will succeed.
`void`	`before(E element)` Prepares this Cursor, so a subsequent call to Cursor#next() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater.
`void`	`beforeFirst()` Positions this Cursor before the first element.
`void`	`close()` Closes this Cursor and frees any resources it my have allocated.
`void`	`close(Exception reason)` Closes this Cursor and frees any resources it my have allocated.
`boolean`	`first()` Positions this Cursor at the first element.
`E`	`get()` Gets the object at the current position.
`boolean`	`isClosed()` Checks if this Cursor is closed.
`boolean`	`isElementReused()` Gets whether or not this Cursor will return the same element object instance on get() operations for any position of this Cursor.
`boolean`	`last()` Positions this Cursor at the last element.
`boolean`	`next()` Advances this Cursor to the next position.
`boolean`	`previous()` Advances this Cursor to the previous position.
`void`	`setClosureMonitor(ClosureMonitor monitor)` Sets a non-null closure monitor to associate with this Cursor.

Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator

- Method Detail
  - available
```
boolean available()
```
    Determines whether or not a call to get() will succeed.
    
    Returns:
    
    true if the cursor is valid get() will succeed, false otherwise
  - before
```
void before(E element)
     throws Exception
```
    Prepares this Cursor, so a subsequent call to Cursor#next() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater. A call to Cursor#previous() with a true return value will position the Cursor on a dataSet element less than the argument. If Cursor#next() returns false then the Cursor is past the last element and so all values in the dataSet are less than the argument. If Cursor#previous() returns false then the Cursor is positioned before the first element and all elements in the dataSet are greater than the argument.
    
    Parameters:
    
    element - the element to be positioned before
    
    Throws:
    
    Exception - with problems accessing the underlying btree
    
    UnsupportedOperationException - if this method is not supported
  - after
```
void after(E element)
    throws Exception
```
    Prepares this Cursor, so a subsequent call to Cursor#previous() with a true return value, will have positioned the Cursor on a dataSet element equal to or less than the element argument but not greater. A call to Cursor#next() with a true return value will position the Cursor on a dataSet element greater than the argument. If Cursor#next() returns false then the Cursor is past the last element and so all values in the dataSet are less than or equal to the argument. If Cursor#previous() returns false then the Cursor is positioned before the first element and all elements in the dataSet are greater than the argument.
    
    Parameters:
    
    element - the element to be positioned after
    
    Throws:
    
    Exception - if there are problems positioning this cursor or if this Cursor is closed
    
    UnsupportedOperationException - if this method is not supported
  - beforeFirst
```
void beforeFirst()
          throws Exception
```
    Positions this Cursor before the first element.
    
    Throws:
    
    Exception - if there are problems positioning this cursor or if this Cursor is closed
    
    UnsupportedOperationException - if this method is not supported
  - afterLast
```
void afterLast()
        throws Exception
```
    Positions this Cursor after the last element.
    
    Throws:
    
    Exception - if there are problems positioning this Cursor or if this Cursor is closed
    
    UnsupportedOperationException - if this method is not supported
  - first
```
boolean first()
       throws Exception
```
    Positions this Cursor at the first element.
    
    Returns:
    
    true if the position has been successfully changed to the first element, false otherwise
    
    Throws:
    
    Exception - if there are problems positioning this Cursor or if this Cursor is closed
    
    UnsupportedOperationException - if this method is not supported
  - last
```
boolean last()
      throws Exception
```
    Positions this Cursor at the last element.
    
    Returns:
    
    true if the position has been successfully changed to the last element, false otherwise
    
    Throws:
    
    Exception - if there are problems positioning this Cursor or if this Cursor is closed
    
    UnsupportedOperationException - if this method is not supported
  - isClosed
```
boolean isClosed()
          throws Exception
```
    Checks if this Cursor is closed. Calls to this operation should not fail with exceptions if and only if the cursor is in the closed state.
    
    Returns:
    
    true if this Cursor is closed, false otherwise
    
    Throws:
    
    Exception - if there are problems determining the cursor's closed state
    
    UnsupportedOperationException - if this method is not supported
  - previous
```
boolean previous()
          throws Exception
```
    Advances this Cursor to the previous position. If called before explicitly positioning this Cursor, the position is presumed to be after the last element and this method moves the cursor back to the last element.
    
    Returns:
    
    true if the advance succeeded, false otherwise
    
    Throws:
    
    Exception - if there are problems advancing to the next position
    
    UnsupportedOperationException - if this method is not supported
  - next
```
boolean next()
      throws Exception
```
    Advances this Cursor to the next position. If called before explicitly positioning this Cursor, the position is presumed to be before the first element and this method moves the cursor forward to the first element.
    
    Returns:
    
    true if the advance succeeded, false otherwise
    
    Throws:
    
    Exception - if there are problems advancing to this Cursor to the next position, or if this Cursor is closed
    
    UnsupportedOperationException - if this method is not supported
  - get
```
E get()
throws Exception
```
    Gets the object at the current position. Cursor implementations may choose to reuse element objects by re-populating them on advances instead of creating new objects on each advance.
    
    Returns:
    
    the object at the current position
    
    Throws:
    
    Exception - if the object at this Cursor's current position cannot be retrieved, or if this Cursor is closed
  - isElementReused
```
boolean isElementReused()
```
    Gets whether or not this Cursor will return the same element object instance on get() operations for any position of this Cursor. Some Cursor implementations may reuse the same element copying values into it for every position rather than creating and emit new element objects on each advance. Some Cursor implementations may return different elements for each position yet the same element instance is returned for the same position. In these cases this method should return true.
    
    Returns:
    
    true if elements are reused by this Cursor
  - close
```
void close()
    throws Exception
```
    Closes this Cursor and frees any resources it my have allocated. Repeated calls to this method after this Cursor has already been called should not fail with exceptions.
    
    Throws:
    
    Exception - if for some reason this Cursor could not be closed
  - close
```
void close(Exception reason)
    throws Exception
```
    Closes this Cursor and frees any resources it my have allocated. Repeated calls to this method after this Cursor has already been called should not fail with exceptions. The reason argument is the Exception instance thrown instead of the standard CursorClosedException.
    
    Parameters:
    
    reason - exception thrown when this Cursor is accessed after close
    
    Throws:
    
    Exception - if for some reason this Cursor could not be closed
  - setClosureMonitor
```
void setClosureMonitor(ClosureMonitor monitor)
```
    Sets a non-null closure monitor to associate with this Cursor.
    
    Parameters:
    
    monitor - the monitor to use for detecting Cursor close events

Interface Cursor<E>

Method Summary

Methods inherited from interface java.lang.Iterable

Method Detail

available

before

after

beforeFirst

afterLast

first

last

isClosed

previous

next

get

isElementReused

close

close

setClosureMonitor