public class Cursor extends java.lang.Object implements ForwardCursor
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.
To obtain a cursor with default attributes:
Cursor cursor = myDatabase.openCursor(txn, null);
To customize the attributes of a cursor, use a CursorConfig object.
CursorConfig config = new CursorConfig();
config.setReadUncommitted(true);
Cursor cursor = myDatabase.openCursor(txn, config);
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 the operation does not succeed. However, it is possible
to configure a cursor as non-sticky to enable certain performance benefits.
See CursorConfig.setNonSticky(boolean) for details.
Null can be passed for DatabaseEntry output parameters if the value is
not needed. The DatabaseEntry Partial
property can also be used to optimize in certain cases. These provide
varying degrees of performance benefits that depend on the specific
operation, 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 by passing null. If null is 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 already 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:
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.
However, 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 has less
of a performance benefit than one might assume, 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.
A null or partial DatabaseEntry output parameter may also be used in other cases, for example, to retrieve a partial key item. 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.
Historical note: Prior to JE 7.0, null could not be passed for output
parameters. Instead, DatabaseEntry.setPartial(0, 0, true) was called
for a data parameter to avoid reading the record's data. Now, null can be
passed instead.
| Modifier and Type | Method and Description |
|---|---|
void |
close()
Discards the cursor.
|
int |
count()
Returns a count of the number of data items for the key to which the
cursor refers.
|
long |
countEstimate()
Returns a rough estimate of the count of the number of data items for
the key to which the cursor refers.
|
OperationStatus |
delete()
Deletes the record to which the cursor refers.
|
OperationResult |
delete(WriteOptions options)
Deletes the record to which the cursor refers.
|
Cursor |
dup(boolean samePosition)
Returns a new cursor with the same transaction and locker ID as the
original cursor.
|
OperationResult |
get(DatabaseEntry key,
DatabaseEntry data,
Get getType,
ReadOptions options)
Moves the cursor to a record according to the specified
Get
type. |
CacheMode |
getCacheMode()
Returns the default
CacheMode used for subsequent operations
performed using this cursor. |
CursorConfig |
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 |
getFirst(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the first key/data pair of the database, and returns
that pair.
|
OperationStatus |
getLast(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the last key/data pair of the database, and returns
that pair.
|
OperationStatus |
getNext(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the next key/data pair and returns that pair.
|
OperationStatus |
getNextDup(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
If the next key/data pair of the database is a duplicate data record for
the current key/data pair, moves the cursor to the next key/data pair of
the database and returns that pair.
|
OperationStatus |
getNextNoDup(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the next non-duplicate key/data pair and returns
that pair.
|
OperationStatus |
getPrev(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the previous key/data pair and returns that pair.
|
OperationStatus |
getPrevDup(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
If the previous key/data pair of the database is a duplicate data record
for the current key/data pair, moves the cursor to the previous key/data
pair of the database and returns that pair.
|
OperationStatus |
getPrevNoDup(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the previous non-duplicate key/data pair and returns
that pair.
|
OperationStatus |
getSearchBoth(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the specified key/data pair, where both the key and
data items must match.
|
OperationStatus |
getSearchBothRange(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the specified key and closest matching data item of
the database.
|
OperationStatus |
getSearchKey(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the given key of the database, and returns the datum
associated with the given key.
|
OperationStatus |
getSearchKeyRange(DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Moves the cursor to the closest matching key of the database, and
returns the data item associated with the matching key.
|
OperationStatus |
put(DatabaseEntry key,
DatabaseEntry data)
Stores a key/data pair into the database.
|
OperationResult |
put(DatabaseEntry key,
DatabaseEntry data,
Put putType,
WriteOptions options)
Inserts or updates a record according to the specified
Put
type. |
OperationStatus |
putCurrent(DatabaseEntry data)
Replaces the data in the key/data pair at the current cursor position.
|
OperationStatus |
putNoDupData(DatabaseEntry key,
DatabaseEntry data)
Stores a key/data pair into the database.
|
OperationStatus |
putNoOverwrite(DatabaseEntry key,
DatabaseEntry data)
Stores a key/data pair into the database.
|
void |
setCacheMode(CacheMode cacheMode)
Sets the
CacheMode default used for subsequent operations
performed using this cursor. |
long |
skipNext(long maxCount,
DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Skips forward a given number of key/data pairs and returns the number by
which the cursor is moved.
|
long |
skipPrev(long maxCount,
DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
Skips backward a given number of key/data pairs and returns the number
by which the cursor is moved.
|
public Database getDatabase()
getDatabase in interface ForwardCursorpublic CursorConfig getConfig()
This may differ from the configuration used to open this object if the cursor existed previously.
public CacheMode getCacheMode()
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.CacheMode default used for subsequent operations
using this cursor.public void setCacheMode(CacheMode cacheMode)
CacheMode default used for subsequent operations
performed using this cursor. This method may be used to override the
defaults specified using DatabaseConfig.setCacheMode(com.sleepycat.je.CacheMode) and EnvironmentMutableConfig.setCacheMode(com.sleepycat.je.CacheMode). Note that the default is always
overridden by a non-null cache mode that is specified via
ReadOptions or WriteOptions.cacheMode - is the default CacheMode used for subsequent
operations using this cursor, or null to configure the Database or
Environment default.for further details.public void 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.
close in interface ForwardCursorclose in interface java.io.Closeableclose in interface java.lang.AutoCloseableEnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.public Cursor dup(boolean samePosition)
This is useful when an application is using locking and requires two or more cursors in the same thread of control.
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.DatabasePreemptedException - in a replicated
environment if the master has truncated, removed or renamed the
database.OperationFailureException - if this exception occurred earlier and
caused the transaction to be invalidated.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed.public OperationResult delete(WriteOptions options)
The cursor position is unchanged after a delete, and subsequent calls to cursor functions expecting the cursor to refer to an existing record will fail.
options - the WriteOptions, or null to use default options.OperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException - if the database is transactional
but this cursor was not opened with a non-null transaction parameter,
or the database is read-only.java.lang.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.public OperationStatus delete()
The cursor position is unchanged after a delete, and subsequent calls to cursor functions expecting the cursor to refer to an existing record will fail.
Calling this method is equivalent to calling delete(WriteOptions).
OperationStatus.KEYEMPTY if the record at the cursor position has
already been deleted; otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException - if the database is transactional
but this cursor was not opened with a non-null transaction parameter,
or the database is read-only.java.lang.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.public OperationResult put(DatabaseEntry key, DatabaseEntry data, Put putType, WriteOptions options)
Put
type.
If the operation succeeds, the record will be locked according to the
lock mode specified, the cursor will
be positioned on the record, and a non-null OperationResult will be
returned. If the operation fails because the record already exists (or
does not exist, depending on the putType), null is returned.
When the database has associated secondary databases, this method also inserts or deletes associated index records as necessary.
The following table lists each allowed operation. See the individual
Put operations for more information.
| Put operation | Description | Returns null when? | Other special rules |
|---|---|---|---|
Put.OVERWRITE |
Inserts or updates a record depending on whether a matching record is already present. | Never returns null. | Without duplicates, a matching record is one with the same key; with duplicates, it is one with the same key and data. |
Put.NO_OVERWRITE |
Inserts a record if a record with a matching key is not already present. | When an existing record matches. | If the database has duplicate keys, a record is inserted only if there are no records with a matching key. |
Put.NO_DUP_DATA |
Inserts a record in a database with duplicate keys if a record with a matching key and data is not already present. | When an existing record matches. | Without duplicates, this operation is not allowed. |
Put.CURRENT |
Updates the data of the record at the cursor position. | When the record at the cursor position has been deleted. | With duplicates, the data must be considered equal by the
duplicate comparator, meaning that changing the data is only
possible if a custom duplicate comparator is configured.
Cannot be used to update the key of an existing record and in fact the key parameter must be null. A partial data item may be specified to optimize for partial data update. |
key - the key used as
input. Must be null when
putType is Put.CURRENT.data - the data used as
input. May be partial only when
putType is Put.CURRENT.putType - the Put operation type. May not be null.options - the WriteOptions, or null to use default options.DuplicateDataException - if putType is Put.CURRENT and the old and
new data are not equal according to the configured duplicate comparator
or default comparator.OperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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 putType is Put.NO_DUP_DATA and the
database is not configured for duplicates.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.
This includes passing a null putType, a null input key/data parameter,
an input key/data parameter with a null data array, a partial key/data
input parameter.public OperationStatus put(DatabaseEntry key, DatabaseEntry data)
Calling this method is equivalent to calling put(DatabaseEntry, DatabaseEntry, Put, WriteOptions) with
Put.OVERWRITE.
If the put method succeeds, the cursor is 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.
key - the key used as
input..data - the data used as
input.OperationStatus.SUCCESS.OperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException - if the database is transactional
but this cursor was not opened with a non-null transaction parameter,
or the database is read-only.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus putNoOverwrite(DatabaseEntry key, DatabaseEntry data)
Calling this method is equivalent to calling put(DatabaseEntry, DatabaseEntry, Put, WriteOptions) with
Put.NO_OVERWRITE.
If the putNoOverwrite method succeeds, the cursor is positioned to refer to the newly inserted item.
If the key already appears in the database, putNoOverwrite will
return OperationStatus.KEYEXIST.
key - the key used as
input..data - the data used as
input.OperationStatus.KEYEXIST if the key already appears in the database,
else OperationStatus.SUCCESSOperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException - if the database is transactional
but this cursor was not opened with a non-null transaction parameter,
or the database is read-only.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus putNoDupData(DatabaseEntry key, DatabaseEntry data)
Calling this method is equivalent to calling put(DatabaseEntry, DatabaseEntry, Put, WriteOptions) with
Put.NO_DUP_DATA.
If the putNoDupData method succeeds, the cursor is 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.
key - the key used as
input..data - the data used as
input.OperationStatus.KEYEXIST if the key/data pair already appears in the
database, else OperationStatus.SUCCESSOperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus putCurrent(DatabaseEntry data)
Calling this method is equivalent to calling put(DatabaseEntry, DatabaseEntry, Put, WriteOptions) with
Put.CURRENT.
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.
data - the data used as
input.
A partial data item may be
specified to optimize for partial data update.OperationStatus.KEYEMPTY if the key/pair at the cursor position has
been deleted; otherwise, OperationStatus.SUCCESS.DuplicateDataException - if the old and new data are not equal
according to the configured duplicate comparator or default comparator.OperationFailureException - if one of the Write
Operation Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.UnsupportedOperationException - if the database is transactional
but this cursor was not opened with a non-null transaction parameter,
or the database is read-only.java.lang.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.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationResult get(DatabaseEntry key, DatabaseEntry data, Get getType, ReadOptions options)
Get
type.
If the operation succeeds, the record at the resulting cursor
position will be locked according to the lock mode specified, the key and/or data will
be returned via the (non-null) DatabaseEntry parameters, and a non-null
OperationResult will be returned. If the operation fails because the
record requested is not found, null is returned.
The following table lists each allowed operation and whether the key
and data parameters are input or
output parameters. Also specified is whether the cursor must be
initialized (positioned on a record) before calling this method. See the
individual Get operations for more information.
| Get operation | Description | 'key' parameter | 'data' parameter | Cursor position must be initialized? |
|---|---|---|---|---|
Get.SEARCH |
Searches using an exact match by key. | input | output | no |
Get.SEARCH_BOTH |
Searches using an exact match by key and data. | input | input | no |
Get.SEARCH_GTE |
Searches using a GTE match by key. | input/output | output | no |
Get.SEARCH_BOTH_GTE |
Searches using an exact match by key and a GTE match by data. | input | input/output | no |
Get.CURRENT |
Accesses the current record | output | output | yes |
Get.FIRST |
Finds the first record in the database. | output | output | no |
Get.LAST |
Finds the last record in the database. | output | output | no |
Get.NEXT |
Moves to the next record. | output | output | no** |
Get.NEXT_DUP |
Moves to the next record with the same key. | output | output | yes |
Get.NEXT_NO_DUP |
Moves to the next record with a different key. | output | output | no** |
Get.PREV |
Moves to the previous record. | output | output | no** |
Get.PREV_DUP |
Moves to the previous record with the same key. | output | output | yes |
Get.PREV_NO_DUP |
Moves to the previous record with a different key. | output | output | no** |
** - For these 'next' and 'previous' operations the cursor may be uninitialized, in which case the cursor will be moved to the first or last record, respectively.
get in interface ForwardCursorkey - the key input or output parameter, depending on getType.data - the data input or output parameter, depending on getType.getType - the Get operation type. May not be null.options - the ReadOptions, or null to use default options.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
the cursor is uninitialized (not positioned on a record) and this is not
permitted (see above), or the non-transactional cursor was created in a
different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.
This includes passing a null getType, a null input key/data parameter,
an input key/data parameter with a null data array, a partial key/data
input parameter, and specifying a lock mode of READ_COMMITTED.public OperationStatus getCurrent(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.CURRENT.
getCurrent in interface ForwardCursorkey - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.KEYEMPTY if the key/pair at the cursor position has
been deleted; otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getFirst(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.FIRST.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getLast(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.LAST.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getNext(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.NEXT.
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.
getNext in interface ForwardCursorkey - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getNextDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.NEXT_DUP.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getNextNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.NEXT_NO_DUP.
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.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getPrev(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.PREV.
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.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getPrevDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.PREV_DUP.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getPrevNoDup(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.PREV_NO_DUP.
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.
key - the key returned as
output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public long skipNext(long maxCount,
DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
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.
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.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.java.lang.IllegalArgumentException - if an invalid parameter is specified.public long skipPrev(long maxCount,
DatabaseEntry key,
DatabaseEntry data,
LockMode lockMode)
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.
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.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getSearchKey(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.SEARCH.
key - the key used as
input.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getSearchKeyRange(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.SEARCH_GTE.
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.
key - the key used as
input and returned as output.data - the data returned as
output.lockMode - the locking attributes; if null, default attributes
are used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getSearchBoth(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.SEARCH_BOTH.
key - the key used as
input.data - the data used as
input.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public OperationStatus getSearchBothRange(DatabaseEntry key, DatabaseEntry data, LockMode lockMode)
Calling this method is equivalent to calling get(DatabaseEntry, DatabaseEntry, Get, ReadOptions) with
Get.SEARCH_BOTH_GTE.
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.
key - the key used as
input.data - the data used as
input and returned as output.lockMode - the locking attributes; if null, default attributes are
used. LockMode.READ_COMMITTED is not allowed.OperationStatus.NOTFOUND if no matching key/data pair is found;
otherwise, OperationStatus.SUCCESS.OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.IllegalStateException - if the cursor or database has been closed,
or the non-transactional cursor was created in a different thread.java.lang.IllegalArgumentException - if an invalid parameter is specified.public int count()
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.
OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.public long countEstimate()
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.
OperationFailureException - if one of the Read Operation
Failures occurs.EnvironmentFailureException - if an unexpected, internal or
environment-wide failure occurs.java.lang.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.Copyright (c) 2002, 2017 Oracle and/or its affiliates. All rights reserved.