com.mapinfo.midev.data

## Interface ICursor

All Superinterfaces:
  IFeatureIterator

    public interface ICursor
    extends IFeatureIterator

A cursor iterates through the results of a search request. Initially the cursor is positioned before the first feature. The `IFeatureIterator.next()` method moves the cursor to the next feature.

A default cursor object moves forward only. Thus, one can iterate through it only once and only from the first feature to the last feature. It is possible to produce cursor objects that are rewindable and/or scrollable as long as the implementing data provider supports these capabilities.

Changes made to features returned in a result set by another process or thread while being read may be visible to the user of a class that implements an ICursor. However, the precise behavior is both implementation and timing dependent.

Cursors are specialized types of `IFeatureIterators`. As such, they have simple iterator behavior such as `hasNext` and `next`. Cursors also expose more elaborate methods for positioning the cursor differently rather than simple forward-only processing. Cursors may be able to be scrolled backward or rewound back to the beginning. Each of these capabilities may or may not be supported and the interface exposes testable properties to determine the level of support available. Typically the fastest, most efficient cursor is a non-scrollable, non-rewindable cursor. Unless specifically requested otherwise, cursors will be delivered with as little capability as possible.

As feature iterators, cursors may hold on to resources such as file locks, database connections, database cursors, etc. and must be properly disposed of when no longer needed. Features obtained from a cursor that are designated as transient will be invalidated after the cursor is disposed. A typical pattern for using a cursor is as follows:

    // this assumes there is a search() method that returns a cursor
    ICursor cursor = search();
    try {
        while (cursor.hasNext()) {
            IFeature feature = cursor.next();
            // do something with each feature
        }
    } finally {
        cursor.dispose();
    }

Cursors also differ from feature iterators in that the attribute definitions of the returned features is available off the cursor, even if there are no features in the result set.

See Also:
  `IFeatureIterator.dispose()`

### Method Summary

All Methods Instance Methods Abstract Methods
`AttributeDefinitionCollection` `getAttributeDefinitions()` Provides access to the IAttributeDefinition instances that define the IFeatures that will be returned by the cursor.
`boolean` `hasPrevious()` Indicates whether or not the cursor has been positioned after at least one feature.
`boolean` `isRewindable()` Indicates if the cursor can be repositioned before the first feature to re-read the data.
`boolean` `isScrollable()` Indicates whether or not the cursor can be scrolled "backward" through calls to previous.
`IFeature` `previous()` Positions the cursor at the previous feature and returns it.
`void` `rewind()` Repositions the result set to before the first feature.

### Methods inherited from interface com.mapinfo.midev.feature.IFeatureIterator

`dispose, forEachRemaining, hasNext, isDisposed, isTransient, next, remove`

### Method Detail

#### getAttributeDefinitions

    AttributeDefinitionCollection getAttributeDefinitions()

Provides access to the IAttributeDefinition instances that define the IFeatures that will be returned by the cursor. The attribute definitions should be accessible even if the cursor returns no features. The same collection of attribute definitions will be accessible off the IFeatureMetadata obtained from the IFeature instances returned by the cursor.

Returns:
  the collection of attributes that define the features returned by the search.

#### isScrollable

    boolean isScrollable()

Indicates whether or not the cursor can be scrolled "backward" through calls to previous. Note that forward-only cursors may or may not be rewindable. In other words, the `ICursor.isRewindable()` property is independent of the isScrollable property.

Returns:
  `true` if the cursor is forward only, `false` if the cursor can be repositioned through calls to previous.

#### hasPrevious

    boolean hasPrevious()

Indicates whether or not the cursor has been positioned after at least one feature. Even cursors that are not scrollable and not rewindable should still be able to indicate whether or not there is a previous feature.

When a cursor is initially created as a result of a search or other operation, it is at the top of the result set and does not have a previous feature. A call to `next` is required to advance the cursor to the first feature (if there is one). If the cursor is rewindable, then after calling `rewind`, `hasPrevious` will return `false`.

Cursors that have been disposed will throw an exception on calls to `previous` or `hasPrevious`.

Returns:
  `true` if the cursor has fetched at least one feature (e.g. has previous features).

#### previous

    IFeature previous()

Positions the cursor at the previous feature and returns it. If the iterator does not support scrolling, then an exception will be thrown. Use `ICursor.hasPrevious()` before calling previous to determine if a previous feature is available. Use `ICursor.isScrollable()` before calling previous to determine if the previous operation is supported by this cursor.

Note that features designated as transient obtained through prior calls to next, previous, or rewind should no longer be accessed and only the feature returned from this operation should be accessed.

Cursors that have been disposed will throw an exception on calls to previous.

Returns:
  the previous IFeature instance from the cursor.
Throws:
  `NoSuchElementException` - iteration has no previous feature.
See Also:
  `IFeatureIterator.dispose()`

#### isRewindable

    boolean isRewindable()

Indicates if the cursor can be repositioned before the first feature to re-read the data. A rewindable cursor may also indicate that it is forward-only. A forward-only cursor means that while fetching the features, the only positioning options available to the user is to read the next feature, rewind back to the beginning (if supported), and disposing of the cursor.

Returns:
  `true` if this cursor is rewindable; `false` otherwise.

#### rewind

    void rewind()

Repositions the result set to before the first feature. This is the initial state of the cursor when initially created. If the cursor does not support the rewind operation, an exception will be thrown. Check the `ICursor.isRewindable()` property before calling rewind to avoid the exception.

Note that features designated as transient obtained through prior calls to next, previous, or rewind should no longer be accessed and only the feature returned from this operation should be used.