A database cursor. Cursors are used for operating on collections of records,
for iterating over a database, and for saving handles to individual records,
so that they can be modified after they have been read.

Cursors which are opened with a transaction instance are transactional
cursors and may be used by multiple threads, but only serially. That is,
the application must serialize access to the handle. Non-transactional
cursors, opened with a null transaction instance, may not be used by
multiple threads.

If the cursor is to be used to perform operations on behalf of a
transaction, the cursor must be opened and closed within the context of that
single transaction.

Once the cursor close() method has been called, the handle may not
be accessed again, regardless of the close method's success or
failure, with one exception: the close method itself may be called
any number of times to simplify error handling.

Modifications to the database during a sequential scan will be reflected
in the scan; that is, records inserted behind a cursor will not be returned
while records inserted in front of a cursor will be returned.

By default, a cursor is "sticky", meaning that the prior position is
maintained by cursor movement operations, and the cursor stays at the
prior position when NOTFOUND is returned or an exception is thrown.
However, it is possible to configure a cursor as non-sticky to enable
certain performance benefits. See CursorConfig.setNonSticky(boolean) for
details.

The DatabaseEntry Partial property can
be used to optimize in certain cases. This provides varying degrees of
performance benefits that depend on the specific operation and use of READ_UNCOMMITTED isolation, as described below.

When retrieving a record with a Database or Cursor
method, if only the key is needed by the application then the retrieval of
the data item can be suppressed using the Partial property. If setPartial(0, 0, true) is called for the DatabaseEntry passed as
the data parameter, the data item will not be returned by the Database or Cursor method.

Suppressing the return of the data item potentially has a large
performance benefit. In this case, if the record data is not in the JE
cache, it will not be read from disk. The performance benefit is
potentially large because random access disk reads may be reduced.
Examples use cases are:

Scanning all records in key order, when the data is not needed.

Skipping over records quickly with READ_UNCOMMITTED isolation to
select records for further processing by examining the key value.

Note that by "record data" we mean both the data parameter for a
regular or primary DB, and the pKey parameter for a secondary DB.
Also note that the performance advantage of a key-only operation does not
apply to databases configured for duplicates. For a duplicates DB, the data
is always available along with the key and does not have to be fetched
separately.

The Partial property may also be used to retrieve or update only a
portion of a data item. This avoids copying the entire record between the
JE cache and the application data parameter. However, this feature is not
currently fully optimized, since the entire record is always read or written
to the database, and the entire record is cached. A partial update may
be performed only with Cursor.putCurrent.

In limited cases, the Partial property may also be used to retrieve a
partial key item. For example, a DatabaseEntry with a Partial
property may be passed to getNext. However, in practice
this has limited value since the entire key is usually needed by the
application, and the benefit of copying a portion of the key is generally
very small. Partial key items may not be passed to methods that use the key
as an input parameter, for example, getSearchKey. In
general, the usefulness of partial key items is very limited.

getCacheMode

Returns the CacheMode used for subsequent operations performed
using this cursor. If setCacheMode(com.sleepycat.je.CacheMode) has not been called with a
non-null value, the configured Database or Environment default is
returned.

close

The cursor handle may not be used again after this method has been
called, regardless of the method's success or failure, with one
exception: the close method itself may be called any number of
times.

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.

dup

Returns a new cursor with the same transaction and locker ID as the
original cursor.

This is useful when an application is using locking and requires
two or more cursors in the same thread of control.

Parameters:

samePosition - If true, the newly created cursor is initialized
to refer to the same position in the database as the original cursor
(if any) and hold the same locks (if any). If false, or the original
cursor does not hold a database position and locks, the returned
cursor is uninitialized and will behave like a newly created cursor.

Returns:

A new cursor with the same transaction and locker ID as the
original cursor.

put

If the put method succeeds, the cursor is always positioned to refer
to the newly inserted item.

If the key already appears in the database and duplicates are
supported, the new data value is inserted at the correct sorted
location, unless the new data value also appears in the database
already. In the later case, although the given key/data pair compares
equal to an existing key/data pair, the two records may not be identical
if custom comparators are used, in which case the existing record will
be replaced with the new record. If the key already appears in the
database and duplicates are not supported, the data associated with
the key will be replaced.

putNoDupData

Stores a key/data pair into the database. The database must be
configured for duplicates.

If the putNoDupData method succeeds, the cursor is always positioned
to refer to the newly inserted item.

Insert the specified key/data pair into the database, unless a
key/data pair comparing equally to it already exists in the database.
If a matching key/data pair already exists in the database, OperationStatus.KEYEXIST is
returned.

UnsupportedOperationException - if the database is transactional
but this cursor was not opened with a non-null transaction parameter, or
the database is read-only, or the database is not configured for
duplicates.

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

putCurrent

Replaces the data in the key/data pair at the current cursor position.

Overwrite the data of the key/data pair to which the cursor refers
with the specified data item. This method will return
OperationStatus.NOTFOUND if the cursor currently refers to an
already-deleted key/data pair.

For a database that does not support duplicates, the data may be
changed by this method. If duplicates are supported, the data may be
changed only if a custom partial comparator is configured and the
comparator considers the old and new data to be equal (that is, the
comparator returns zero). For more information on partial comparators
see DatabaseConfig.setDuplicateComparator(java.util.Comparator<byte[]>).

If the old and new data are unequal according to the comparator, a
DuplicateDataException is thrown. Changing the data in this
case would change the sort order of the record, which would change the
cursor position, and this is not allowed. To change the sort order of a
record, delete it and then re-insert it.

Parameters:

data - - the data DatabaseEntry stored.
A partial data item may be
specified to optimize for partial data update.

getNext

If the cursor is not yet initialized, move the cursor to the first
key/data pair of the database, and return that pair. Otherwise, the
cursor is moved to the next key/data pair of the database, and that pair
is returned. In the presence of duplicate key values, the value of the
key may not change.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

getNextNoDup

Moves the cursor to the next non-duplicate key/data pair and returns
that pair. If the matching key has duplicate values, the first data
item in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the first
key/data pair of the database, and return that pair. Otherwise, the
cursor is moved to the next non-duplicate key of the database, and that
key/data pair is returned.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

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.
A partial data item may be
specified to optimize for key only or partial data retrieval.

getPrev

If the cursor is not yet initialized, move the cursor to the last
key/data pair of the database, and return that pair. Otherwise, the
cursor is moved to the previous key/data pair of the database, and that
pair is returned. In the presence of duplicate key values, the value of
the key may not change.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

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.
A partial data item may be
specified to optimize for key only or partial data retrieval.

getPrevNoDup

Moves the cursor to the previous non-duplicate key/data pair and returns
that pair. If the matching key has duplicate values, the last data item
in the set of duplicates is returned.

If the cursor is not yet initialized, move the cursor to the last
key/data pair of the database, and return that pair. Otherwise, the
cursor is moved to the previous non-duplicate key of the database, and
that key/data pair is returned.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

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.
A partial data item may be
specified to optimize for key only or partial data retrieval.

skipNext

Skips forward a given number of key/data pairs and returns the number by
which the cursor is moved.

Without regard to performance, calling this method is equivalent to
repeatedly calling getNext with LockMode.READ_UNCOMMITTED to skip over the desired number of key/data
pairs, and then calling getCurrent with the lockMode parameter to return the final key/data pair.

With regard to performance, this method is optimized to skip over
key/value pairs using a smaller number of Btree operations. When there
is no contention on the bottom internal nodes (BINs) and all BINs are in
cache, the number of Btree operations is reduced by roughly two orders
of magnitude, where the exact number depends on the EnvironmentConfig.NODE_MAX_ENTRIES setting. When there is contention
on BINs or fetching BINs is required, the scan is broken up into smaller
operations to avoid blocking other threads for long time periods.

If the returned count is greater than zero, then the key/data pair at
the new cursor position is also returned. If zero is returned, then
there are no key/value pairs that follow the cursor position and a
key/data pair is not returned.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

Parameters:

maxCount - the maximum number of key/data pairs to skip, i.e., the
maximum number by which the cursor should be moved; must be greater
than zero.

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.
A partial data item may be
specified to optimize for key only or partial data retrieval.

skipPrev

Skips backward a given number of key/data pairs and returns the number
by which the cursor is moved.

Without regard to performance, calling this method is equivalent to
repeatedly calling getPrev with LockMode.READ_UNCOMMITTED to skip over the desired number of key/data
pairs, and then calling getCurrent with the lockMode parameter to return the final key/data pair.

With regard to performance, this method is optimized to skip over
key/value pairs using a smaller number of Btree operations. When there
is no contention on the bottom internal nodes (BINs) and all BINs are in
cache, the number of Btree operations is reduced by roughly two orders
of magnitude, where the exact number depends on the EnvironmentConfig.NODE_MAX_ENTRIES setting. When there is contention
on BINs or fetching BINs is required, the scan is broken up into smaller
operations to avoid blocking other threads for long time periods.

If the returned count is greater than zero, then the key/data pair at
the new cursor position is also returned. If zero is returned, then
there are no key/value pairs that follow the cursor position and a
key/data pair is not returned.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

Parameters:

maxCount - the maximum number of key/data pairs to skip, i.e., the
maximum number by which the cursor should be moved; must be greater
than zero.

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.
A partial data item may be
specified to optimize for key only or partial data retrieval.

getSearchKey

Moves the cursor to the given key of the database, and returns the datum
associated with the given key. If the matching key has duplicate
values, the first data item in the set of duplicates is returned.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

Parameters:

key - the key used as input. It must be initialized with a
non-null byte array by the caller.

data - the data returned as output. Its byte array does not need
to be initialized by the caller.
A partial data item may be
specified to optimize for key only or partial data retrieval.

getSearchKeyRange

Moves the cursor to the closest matching key of the database, and
returns the data item associated with the matching key. If the matching
key has duplicate values, the first data item in the set of duplicates
is returned.

The returned key/data pair is for the smallest key greater than or
equal to the specified key (as determined by the key comparison
function), permitting partial key matches and range searches.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

Parameters:

key - the key used as input and returned as output. It must be
initialized with a non-null byte array by the caller.
A partial data item may be
specified to optimize for key only or partial data retrieval.

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

getSearchBothRange

Moves the cursor to the specified key and closest matching data item of
the database.

In the case of any database supporting sorted duplicate sets, the
returned key/data pair is for the smallest data item greater than or
equal to the specified data item (as determined by the duplicate
comparison function), permitting partial matches and range searches in
duplicate data sets.

In the case of databases that do not support sorted duplicate sets,
this method is equivalent to getSearchBoth.

In a replicated environment, an explicit transaction must have been
specified when opening the cursor, unless read-uncommitted isolation is
specified via the CursorConfig or LockMode
parameter.

Parameters:

key - the key used as input. It must be initialized with a
non-null byte array by the caller.

data - the data used as input and returned as output. It must be
initialized with a non-null byte array by the caller.

count

Returns a count of the number of data items for the key to which the
cursor refers.

If the database is configured for duplicates, the database is scanned
internally, without taking any record locks, to count the number of
non-deleted entries. Although the internal scan is more efficient under
some conditions, the result is the same as if a cursor were used to
iterate over the entries using LockMode.READ_UNCOMMITTED.

If the database is not configured for duplicates, the count returned
is always zero or one, depending on the record at the cursor position is
deleted or not.

The cost of this method is directly proportional to the number of
records scanned.

Returns:

A count of the number of data items for the key to which the
cursor refers.

countEstimate

Returns a rough estimate of the count of the number of data items for
the key to which the cursor refers.

If the database is configured for duplicates, a quick estimate of the
number of records is computed using information in the Btree. Because
the Btree is unbalanced, in some cases the estimate may be off by a
factor of two or more. The estimate is accurate when the number of
records is less than the configured NodeMaxEntries.

If the database is not configured for duplicates, the count returned
is always zero or one, depending on the record at the cursor position is
deleted or not.

The cost of this method is fixed, rather than being proportional to
the number of records scanned. Because its accuracy is variable, this
method should normally be used when accuracy is not required, such as
for query optimization, and a fixed cost operation is needed. For
example, this method is used internally for determining the index
processing order in a JoinCursor.

Returns:

an estimate of the count of the number of data items for the key
to which the cursor refers.