com.sleepycat.je
Class DiskOrderedCursor

java.lang.Object
  com.sleepycat.je.DiskOrderedCursor

All Implemented Interfaces:

ForwardCursor, Closeable

public class DiskOrderedCursor
extends Object
implements ForwardCursor

DiskOrderedCursor returns records in unsorted order in exchange for generally faster retrieval times. Instead of key order, an approximation of disk order is used, which results in less I/O. This can be useful when the application needs to scan all records in a database, and will be applying filtering logic which does not need key ordered retrieval. DiskOrderedCursor is created using the Database.openCursor(DiskOrderedCursorConfig) method.

All cursors can consume resources and should be closed as soon as the application is finished using them. In particular, a DiskOrderedCursor disables the file deletion done by log cleaning, and will therefore delay the compaction of log files.

Optional configurations: the following options are available to tune the DiskOrderedCursor.

The DiskOrderedCursor creates a background producer thread which prefetches some target records and inserts them in a queue for use by the cursor. The parameter EnvironmentConfig.DOS_PRODUCER_QUEUE_TIMEOUT applies to this background thread, and controls the timeout which governs the blocking queue.

When the DiskOrderedCursor is first created, it is "seeded" with in-memory internal B-Tree nodes. This seeding causes the root and all seed INs to be latched for read, for use by the cursor. Seeded B-Tree nodes help the efficiency of the cursor, but penalize any concurrent update operations which require write locks on those nodes. DiskOrderedCursorConfig.setMaxSeedMillisecs(long) can be used to limit the time spent on the seeding process in exchange for reduced performance during the cursor walk.

DiskOrderedCursorConfig.setMaxSeedNodes(long) can be used to limit the number of nodes used to seed the DiskOrderedCursor, which also can reduce cursor performance, but improves the performance of concurrent write operations.

Since:

5.0

Method Summary

void	close() Discards the cursor.
DiskOrderedCursorConfig	getConfig() Returns this cursor's configuration.
OperationStatus	getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Returns the key/data pair to which the cursor refers.
Database	getDatabase() Returns the Database handle associated with this Cursor.
OperationStatus	getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode) Moves the cursor to the next key/data pair and returns that pair.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDatabase

public Database getDatabase()

Returns the Database handle associated with this Cursor.

Specified by:

getDatabase in interface ForwardCursor

Returns:

The Database handle associated with this Cursor.

close

public void close()
           throws DatabaseException

Discards the cursor.

The cursor handle may not be used again after this method has been called, regardless of the method's success or failure.

WARNING: To guard against memory leaks, the application should discard all references to the closed handle. While BDB makes an effort to discard references from closed objects to the allocated memory for an environment, this behavior is not guaranteed. The safe course of action for an application is to discard all references to closed BDB objects.

Specified by:

close in interface ForwardCursor

Specified by:

close in interface Closeable

Throws:

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

DatabaseException

getCurrent

public OperationStatus getCurrent(DatabaseEntry key,
                                  DatabaseEntry data,
                                  LockMode lockMode)
                           throws DatabaseException

Returns the key/data pair to which the cursor refers.

If this method fails for any reason, the position of the cursor will be unchanged.

Specified by:

getCurrent in interface ForwardCursor

Parameters:

key - the key returned as output. Its byte array does not need to be initialized by the caller.

data - the data returned as output. Its byte array does not need to be initialized by the caller. This argument should be supplied even if the DiskOrderedCursor has been configured with keysOnly.

lockMode - the locking attributes. For DiskOrderedCursors this parameter must be either null or LockMode.READ_UNCOMMITTED since no locking is performed.

Returns:

OperationStatus.KEYEMPTY if there are no more records in the DiskOrderedCursor set, otherwise, OperationStatus.SUCCESS. If the record referred to by a DiskOrderedCursor is deleted after the ForwardCursor is positioned at that record, getCurrent() will still return the key and value of that record and OperationStatus.SUCCESS.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

IllegalStateException - if the cursor or database has been closed, or the cursor is uninitialized (not positioned on a record), or the non-transactional cursor was created in a different thread.

IllegalArgumentException - if an invalid parameter is specified.

DatabaseException

getNext

public OperationStatus getNext(DatabaseEntry key,
                               DatabaseEntry data,
                               LockMode lockMode)
                        throws DatabaseException

Moves the cursor to the next key/data pair and returns that pair.

If the cursor is not yet initialized, move the cursor to an arbitrary key/data pair of the database, and return that pair. Otherwise, the cursor is moved to the next key/data pair of the set, and that pair is returned.

If this method fails for any reason, the position of the cursor will be unchanged.

Specified by:

getNext in interface ForwardCursor

Parameters:

key - the key returned as output. Its byte array does not need to be initialized by the caller.

data - the data returned as output. Its byte array does not need to be initialized by the caller. This argument should be supplied even if the DiskOrderedCursor has been configured with keysOnly.

lockMode - the locking attributes. For DiskOrderedCursors this parameter must be either null or LockMode.READ_UNCOMMITTED since no locking is performed.

Returns:

OperationStatus.NOTFOUND if no matching key/data pair is found; otherwise, OperationStatus.SUCCESS.

Throws:

OperationFailureException - if one of the Read Operation Failures occurs.

EnvironmentFailureException - if an unexpected, internal or environment-wide failure occurs.

IllegalStateException - if the cursor or database has been closed, or the non-transactional cursor was created in a different thread.

IllegalArgumentException - if an invalid parameter is specified.

DatabaseException

getConfig

public DiskOrderedCursorConfig getConfig()

Returns this cursor's configuration.

This may differ from the configuration used to open this object if the cursor existed previously.

Returns:

This cursor's configuration.