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

Modifier and Type	Method and Description
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.