CursorImpl (starrocks-bdb-je 18.3.17 API)

java.lang.Object
- com.sleepycat.je.dbi.CursorImpl

All Implemented Interfaces:

Cloneable
```
public class CursorImpl
extends Object
implements Cloneable
```
A CursorImpl is the internal implementation of the cursor.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CursorImpl.LockStanding` Holds the result of a lockLN operation.
`static interface`	`CursorImpl.WithCursor` Callback object for traverseDbWithCursor.

Field Summary

Fields
Modifier and Type Field and Description

static int EXACT_KEY

static int FOUND

static int FOUND_LAST

Fields
Modifier and Type	Field and Description
`static int`	`EXACT_KEY`
`static int`	`FOUND`
`static int`	`FOUND_LAST`

Constructor Summary

Constructors
Constructor and Description
`CursorImpl(DatabaseImpl database, Locker locker)` Creates a cursor with retainNonTxnLocks=true, isSecondaryCursor=false.
`CursorImpl(DatabaseImpl dbImpl, Locker locker, boolean retainNonTxnLocks, boolean isSecondaryCursor)` Creates a cursor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`advanceCursor(DatabaseEntry key, DatabaseEntry data)` Advance a cursor.
`void`	`afterNonStickyOp()` For a non-sticky cursor, this method is called after a successful operation.
`void`	`assertBIN(BIN bin)`
`void`	`beforeNonStickyOp()` For a non-sticky cursor, this method is called when the cursor is initialized and an advancing operation (next/prev/skip) is about to be performed.
`void`	`checkCursorState(boolean mustBeInitialized, boolean mustNotBeInitialized)` Check that the cursor is open and optionally if it is initialized or uninitialized.
`void`	`checkEnv()`
`boolean`	`checkForInsertion(GetMode getMode, CursorImpl dupCursor)` Used to detect phantoms during "get next" operations with serializable isolation.
`void`	`clearClosingLocker()` Called when a cursor move operation is complete.
`CursorImpl`	`cloneCursor(boolean samePosition)` Performs a shallow copy and returns the new cursor.
`void`	`close()`
`void`	`close(CursorImpl newCursor)` Close a cursor.
`void`	`criticalEviction()`
`OperationResult`	`deleteCurrentRecord(ReplicationContext repContext)` Delete the item pointed to by the cursor.
`void`	`dump()` dump the cursor for debugging purposes.
`void`	`dump(boolean verbose)` Dump the cursor for debugging purposes.
`String`	`dumpToString(boolean verbose)`
`void`	`evictLN()` Evict the LN node at the cursor position.
`List<TrackingInfo>`	`getAncestorPath()` Returns the stack of ancestor TrackingInfo for the BIN at the cursor, or null if a split occurs and the information returned would be inconsistent.
`BIN`	`getBIN()`
`CacheMode`	`getCacheMode()`
`OperationResult`	`getCurrent(DatabaseEntry foundKey, DatabaseEntry foundData)` Copy current record into the key and data DatabaseEntry.
`byte[]`	`getCurrentKey()`
`byte[]`	`getCurrentKey(boolean isLatched)` Returns the key at the current position, regardless of whether the record is defunct.
`LN`	`getCurrentLN(boolean isLatched, boolean unlatch)`
`long`	`getCurrentLsn()`
`static long`	`getCurrentLsn(CursorImpl cursor)`
`long`	`getCurrentNodeId()` Called for creating trace messages without any latching.
`RecordVersion`	`getCurrentVersion(boolean allowFetch)` Returns the VLSN and LSN for the record at the current position.
`DatabaseImpl`	`getDb()`
`long`	`getExpirationTime()`
`int`	`getIndex()`
`Locker`	`getLocker()`
`StatGroup`	`getLockStats()`
`OperationResult`	`getNext(DatabaseEntry foundKey, DatabaseEntry foundData, LockType lockType, boolean dirtyReadAll, boolean forward, boolean isLatched, RangeConstraint rangeConstraint)` Move the cursor forward and return the next "valid" record.
`int`	`getNSecondaryWrites()` Returns the number of secondary records written by the last put/delete operation at the current cursor position.
`int`	`getStorageSize()` Returns the estimated disk storage size for the record at the current position.
`boolean`	`hasDuplicates()`
`int`	`hashCode()`
`void`	`incrementLNCount()`
`OperationResult`	`insertOrUpdateRecord(DatabaseEntry key, DatabaseEntry data, LN ln, ExpirationInfo expInfo, PutMode putMode, DatabaseEntry returnOldData, DatabaseEntry returnNewData, ReplicationContext repContext)` Insert or update a given record.
`boolean`	`insertRecord(byte[] key, LN ln, boolean blindInsertion, ReplicationContext repContext)` Insert the given record (key + LN) in the tree or return false if the key is already present.
`boolean`	`isClosed()`
`boolean`	`isInternalDbCursor()`
`boolean`	`isNotInitialized()`
`boolean`	`isOnBIN(BIN bin)`
`boolean`	`isOnSamePosition(CursorImpl other)`
`boolean`	`isProbablyExpired()`
`void`	`latchBIN()`
`static void`	`lockAfterLsnChange(DatabaseImpl dbImpl, long oldLsn, long newLsn, Locker excludeLocker)` After logging a deferred-write LN during eviction/checkpoint or a migrated LN during cleaning, for every existing lock on the old LSN held by another locker, we must lock the new LSN on behalf of that locker.
`OperationResult`	`lockAndGetCurrent(DatabaseEntry foundKey, DatabaseEntry foundData, LockType lockType)` Lock and copy current record into the key and data DatabaseEntry.
`OperationResult`	`lockAndGetCurrent(DatabaseEntry foundKey, DatabaseEntry foundData, LockType lockType, boolean dirtyReadAll, boolean isLatched, boolean unlatch)` Let S be the slot where this cursor is currently positioned on.
`LN`	`lockAndGetCurrentLN(LockType lockType)` Retrieve the current LN.
`void`	`lockEof(LockType lockType)` Locks the logical EOF node for the dbImpl.
`CursorImpl.LockStanding`	`lockLN(LockType lockType)` Does not allow uncontended locks.
`void`	`lockNextKeyForInsert(DatabaseEntry key)` Search for the next key following the given key, and acquire a range insert lock on it.
`boolean`	`positionFirstOrLast(boolean first)` Position the cursor at the first or last record of the dbImpl.
`void`	`releaseBIN()`
`void`	`reset()` Reset a cursor to an uninitialized state, but unlike close(), allow it to be used further.
`void`	`revertLock(CursorImpl.LockStanding standing)`
`boolean`	`searchExact(DatabaseEntry searchKey, LockType lockType)`
`CursorImpl.LockStanding`	`searchExact(DatabaseEntry searchKey, LockType lockType, boolean dirtyReadAll, boolean dataRequested)` Position this cursor on the slot (if any) whose key matches the given search key.
`int`	`searchRange(DatabaseEntry searchKey, Comparator<byte[]> comparator)` Position this cursor on the slot whose key is the max key less or equal to the given search key.
`void`	`setAllowEviction(boolean allowed)` Disables or enables eviction during cursor operations.
`void`	`setBIN(BIN newBin)`
`void`	`setCacheMode(CacheMode mode)` Sets the effective cache mode to use for the next operation.
`void`	`setClosingLocker(CursorImpl closingCursor)` Called when a cursor has been duplicated prior to being moved.
`void`	`setIndex(int idx)`
`void`	`setNSecondaryWrites(int nWrites)`
`void`	`setOnFirstSlot()`
`void`	`setOnLastSlot()`
`void`	`setPriInfo(CursorImpl sourceCursor)` When the primary record is read during a secondary operation, this method is called to copy the primary version and storage size here.
`void`	`setTestHook(TestHook hook)`
`void`	`setTreeStatsAccumulator(TreeWalkerStatsAccumulator tSA)`
`long`	`skip(boolean forward, long maxCount, RangeConstraint rangeConstraint)` Skips over entries until a boundary condition is satisfied, either because maxCount is reached or RangeConstraint.inBounds returns false.
`static void`	`traverseDbWithCursor(DatabaseImpl db, LockType lockType, boolean allowEviction, CursorImpl.WithCursor withCursor)` Enumerates all records in a dbImpl non-transactionally and calls the withCursor method for each record.
`OperationResult`	`updateCurrentRecord(DatabaseEntry key, DatabaseEntry data, ExpirationInfo expInfo, DatabaseEntry returnOldData, DatabaseEntry returnNewData, ReplicationContext repContext)` Modify the current record with the given data, and optionally replace the key.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - FOUND
```
public static final int FOUND
```
    See Also:
    
    Constant Field Values
  - EXACT_KEY
```
public static final int EXACT_KEY
```
    See Also:
    
    Constant Field Values
  - FOUND_LAST
```
public static final int FOUND_LAST
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - CursorImpl
```
public CursorImpl(DatabaseImpl database,
                  Locker locker)
```
    Creates a cursor with retainNonTxnLocks=true, isSecondaryCursor=false. These are the standard settings for an internal cursor.
  - CursorImpl
```
public CursorImpl(DatabaseImpl dbImpl,
                  Locker locker,
                  boolean retainNonTxnLocks,
                  boolean isSecondaryCursor)
```
    Creates a cursor. A cursor always retains transactional locks when it is reset or closed. Non-transaction locks may be retained or not, depending on the retainNonTxnLocks parameter value. Normally a user-created non-transactional Cursor releases locks on reset and close, and a ThreadLocker is normally used. However, by passing true for retainNonTxnLocks a ThreadLocker can be made to retain locks; this capability is used by SecondaryCursor.readPrimaryAfterGet. For internal (non-user) cursors, a BasicLocker is often used and locks are retained. In these internal use cases the caller explicitly calls BasicLocker.operationEnd() after the cursor is closed, and retainNonTxnLocks is set to true to prevent the locks acquired by the BasicLocker from being released when the cursor is closed. BasicLocker is also used for NameLN operations while opening a Database handle. Database handle locks must be retained, even if the Database is opened non-transactionally.
    
    Parameters:
    
    retainNonTxnLocks - is true if non-transactional locks should be retained (not released automatically) when the cursor is reset or closed.
    
    isSecondaryCursor - whether to treat this cursor as a secondary cursor, e.g., secondary records don't have record versions.
- Method Detail
  - cloneCursor
```
public CursorImpl cloneCursor(boolean samePosition)
```
    Performs a shallow copy and returns the new cursor.
    
    Parameters:
    
    samePosition - If true, this cursor's position is used for the new cursor, and addCursor is called on the new cursor to register it with the current BIN. If false, the new cursor will be uninitialized.
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - getLocker
```
public Locker getLocker()
```
  - getDb
```
public DatabaseImpl getDb()
```
  - setClosingLocker
```
public void setClosingLocker(CursorImpl closingCursor)
```
    Called when a cursor has been duplicated prior to being moved. The new locker is informed of the old locker, so that a preempted lock taken by the old locker can be ignored. [#16513]
    
    Parameters:
    
    closingCursor - the old cursor that will be closed if the new cursor is moved successfully.
  - clearClosingLocker
```
public void clearClosingLocker()
```
    Called when a cursor move operation is complete. Clears the closingLocker so that a reference to the old closed locker is not held.
  - getCacheMode
```
public CacheMode getCacheMode()
```
  - setCacheMode
```
public void setCacheMode(CacheMode mode)
```
    Sets the effective cache mode to use for the next operation. The cacheMode field will never be set to null, and can be passed directly to latching methods.
    
    See Also:
    
    performCacheModeEviction(com.sleepycat.je.dbi.CursorImpl)
  - setTreeStatsAccumulator
```
public void setTreeStatsAccumulator(TreeWalkerStatsAccumulator tSA)
```
  - incrementLNCount
```
public void incrementLNCount()
```
  - getIndex
```
public int getIndex()
```
  - getBIN
```
public BIN getBIN()
```
  - setIndex
```
public void setIndex(int idx)
```
  - setOnFirstSlot
```
public void setOnFirstSlot()
```
  - setOnLastSlot
```
public void setOnLastSlot()
```
  - isOnBIN
```
public boolean isOnBIN(BIN bin)
```
  - assertBIN
```
public void assertBIN(BIN bin)
```
  - isOnSamePosition
```
public boolean isOnSamePosition(CursorImpl other)
```
  - setBIN
```
public void setBIN(BIN newBin)
```
  - latchBIN
```
public void latchBIN()
```
  - releaseBIN
```
public void releaseBIN()
```
  - getCurrentNodeId
```
public long getCurrentNodeId()
```
    Called for creating trace messages without any latching.
  - getCurrentLsn
```
public static long getCurrentLsn(CursorImpl cursor)
```
  - getCurrentLsn
```
public long getCurrentLsn()
```
  - getCurrentKey
```
public byte[] getCurrentKey()
```
  - getCurrentKey
```
public byte[] getCurrentKey(boolean isLatched)
```
    Returns the key at the current position, regardless of whether the record is defunct. Does not lock. The key returned is not a copy and may not be returned directly to the user without copying it first. The cursor must be initialized. TODO: The returned byte array is normally, but not always a copied, and then copied again into the user's DatabaseEntry. If this method always returns a copy, the extra copy into DatabaseEntry could be avoided.
  - isProbablyExpired
```
public boolean isProbablyExpired()
```
  - getExpirationTime
```
public long getExpirationTime()
```
  - isClosed
```
public boolean isClosed()
```
    Returns:
    
    true if this cursor is closed
  - isNotInitialized
```
public boolean isNotInitialized()
```
    Returns:
    
    true if this cursor is not initialized
  - isInternalDbCursor
```
public boolean isInternalDbCursor()
```
  - hasDuplicates
```
public boolean hasDuplicates()
```
  - beforeNonStickyOp
```
public void beforeNonStickyOp()
```
    For a non-sticky cursor, this method is called when the cursor is initialized and an advancing operation (next/prev/skip) is about to be performed. The cursor position is not reset as it would be if the operation were a search or an insertion, for example.
  - afterNonStickyOp
```
public void afterNonStickyOp()
```
    For a non-sticky cursor, this method is called after a successful operation. The cursor position is not reset as it would be if the operation failed.
  - reset
```
public void reset()
```
    Reset a cursor to an uninitialized state, but unlike close(), allow it to be used further.
  - close
```
public void close()
```
  - close
```
public void close(CursorImpl newCursor)
```
    Close a cursor.
    
    Parameters:
    
    newCursor - is another cursor that is kept open by the parent Cursor object, or null if no other cursor is kept open.
  - setAllowEviction
```
public void setAllowEviction(boolean allowed)
```
    Disables or enables eviction during cursor operations. For example, a cursor used to implement eviction (e.g., in some UtilizationProfile and most DbTree and VLSNIndex methods) should not itself perform eviction, but eviction should be enabled for user cursors. Eviction is disabled by default.
  - criticalEviction
```
public void criticalEviction()
```
  - evictLN
```
public void evictLN()
```
    Evict the LN node at the cursor position.
  - deleteCurrentRecord
```
public OperationResult deleteCurrentRecord(ReplicationContext repContext)
```
    Delete the item pointed to by the cursor. If the item is already defunct, return KEYEMPTY. Returns with nothing latched.
  - updateCurrentRecord
```
public OperationResult updateCurrentRecord(DatabaseEntry key,
                                           DatabaseEntry data,
                                           ExpirationInfo expInfo,
                                           DatabaseEntry returnOldData,
                                           DatabaseEntry returnNewData,
                                           ReplicationContext repContext)
```
    Modify the current record with the given data, and optionally replace the key.
    
    Parameters:
    
    key - The new key value for the BIN slot S to be updated. Cannot be partial. For a no-dups DB, it is null. For dups DBs it is a 2-part key combining the current primary key of slot S with the original, user-provided data. "key" (if not null) must compare equal to S.key (otherwise DuplicateDataException is thrown), but the 2 keys may not be identical if custom comparators are used. So, S.key will actually be replaced by "key".
    
    data - The new data to (perhaps partially) replace the data of the LN associated with the BIN slot. For dups DBs it is EMPTY_DUPS_DATA. Note: for dups DBs the original, user-provided "data" must not be partial.
    
    returnOldData - To receive the old LN data (before the update). It is needed only by DBs with indexes/triggers; will be null otherwise.
    
    returnNewData - To receive the full data of the updated LN. It is needed only by DBs with indexes/triggers and only if "data" is partial; will be null otherwise. Note: "returnNewData" may be different than "data" only if "data" is partial.
    
    Returns:
    
    OperationResult, or null if an expired LN was purged and a partial 'data' param was supplied.
  - insertRecord
```
public boolean insertRecord(byte[] key,
                            LN ln,
                            boolean blindInsertion,
                            ReplicationContext repContext)
```
    Insert the given record (key + LN) in the tree or return false if the key is already present. The cursor must initially be uninitialized. This method is called directly internally for putting tree map LNs and file summary LNs.
    
    Returns:
    
    true if we inserted a slot or reused a slot having a defunct record, or false if the insertion failed because a non-defunct record exists with the given key.
  - insertOrUpdateRecord
```
public OperationResult insertOrUpdateRecord(DatabaseEntry key,
                                            DatabaseEntry data,
                                            LN ln,
                                            ExpirationInfo expInfo,
                                            PutMode putMode,
                                            DatabaseEntry returnOldData,
                                            DatabaseEntry returnNewData,
                                            ReplicationContext repContext)
```
    Insert or update a given record. The method searches for the record using its key. It will perform an update if the record is found, otherwise an insertion. The cursor must initially be uninitialized. Called by all the Cursor.putXXX() ops, except putCurrent().
    
    Parameters:
    
    key - The new key value for the BIN slot S to be inserted/updated. Cannot be partial. For dups DBs it is a 2-part key combining the original, user-provided key and data. In case of update, "key" must compare equal to S.key (otherwise DuplicateDataException is thrown), but the 2 keys may not be identical if custom comparators are used. So, S.key will actually be replaced by "key".
    
    data - In case of update, the new data to (perhaps partially) replace the data of the LN associated with the BIN slot. For dups DBs it is EMPTY_DUPS_DATA. Note: for dups DBs the original, user-provided "data" must not be partial.
    
    ln - is normally a new LN node that is created for insertion, and will be discarded if an update occurs. However, HA will pass an existing node.
    
    putMode - OVERWRITE or NO_OVERWRITE
    
    returnOldData - To receive, in case of update, the old LN data (before the update). It is needed only by DBs with indexes/triggers; will be null otherwise.
    
    returnNewData - To receive the full data of the new or updated LN. It is needed only by DBs with indexes/triggers and only if "data" is partial; will be null otherwise. Note: "returnNewData" may be different than "data" only if "data" is partial.
    
    Returns:
    
    OperationResult where isUpdate() distinguishes insertions and updates. Is null only if an expired LN was purged and a partial 'data' param was supplied.
  - positionFirstOrLast
```
public boolean positionFirstOrLast(boolean first)
```
    Position the cursor at the first or last record of the dbImpl. It's okay if this record is defunct. The cursor must initially be uninitialized. Returns with the target BIN latched!
    
    Returns:
    
    true if a first or last position is found, false if the tree being searched is empty.
  - searchRange
```
public int searchRange(DatabaseEntry searchKey,
                       Comparator<byte[]> comparator)
```
    Position this cursor on the slot whose key is the max key less or equal to the given search key. To be more precise, let K1 be search key. The method positions the cursor on the BIN that should contain K1. If the BIN does contain K1, this.index is set to the containing slot. Otherwise, this.index is set to the right-most slot whose key is < K1, or to -1 if K1 is < all keys in the BIN. The cursor must initially be uninitialized. The method returns with the BIN latched, unless an exception is raised. The method returns an integer that encodes the search outcome: If the FOUND bit is not set, the tree is completely empty (has no BINs). If the FOUND bit is set, the EXACT_KEY bit says whether K1 was found or not and the FOUND_LAST bit says whether the cursor is positioned to the very last slot of the BTree (note that this state can only be counted on as long as the BIN is latched). Even if the search returns an exact result, the record may be defunct. The caller must therefore check whether the cursor is positioned on a defunct record. This method does not lock the record. The caller is expected to call lockAndGetCurrent to perform locking.
  - searchExact
```
public boolean searchExact(DatabaseEntry searchKey,
                           LockType lockType)
```
  - searchExact
```
public CursorImpl.LockStanding searchExact(DatabaseEntry searchKey,
                                           LockType lockType,
                                           boolean dirtyReadAll,
                                           boolean dataRequested)
```
    Position this cursor on the slot (if any) whose key matches the given search key. If no such slot is found or the slot does not hold a "valid" record, return null. Otherwise, lock the found record with the specified lock type (which may be NONE) and return the LockStanding obj that was created by the locking op. Whether the slot contains a "valid" record or not depends on the slot's KD/PD flags and the lockType and dirtyReadAll parameters. Four cases are considered; they are described in the lockLNAndCheckDefunct() method. The cursor must initially be uninitialized. The method returns with the BIN latched, unless an exception is raised. In all cases, the method registers the cursor with the BIN that contains or should contain the search key.
    
    Returns:
    
    the LockStanding for the found record, or null if no record was found.
  - lockAndGetCurrent
```
public OperationResult lockAndGetCurrent(DatabaseEntry foundKey,
                                         DatabaseEntry foundData,
                                         LockType lockType)
```
    Lock and copy current record into the key and data DatabaseEntry. When calling this method, this.bin should not be latched already. On return, this.bin is unlatched.
  - lockAndGetCurrent
```
public OperationResult lockAndGetCurrent(DatabaseEntry foundKey,
                                         DatabaseEntry foundData,
                                         LockType lockType,
                                         boolean dirtyReadAll,
                                         boolean isLatched,
                                         boolean unlatch)
```
    Let S be the slot where this cursor is currently positioned on. If S does not hold a "valid" record, return null. Otherwise, lock the record in S with the specified lock type(which may be NONE), copy its key and data into the key and data DatabaseEntries, and return SUCCESS. Whether the slot contains a "valid" record or not depends on the slot's KD/PD flags, the lockType and dirtyReadAll parameters, and whether the record has expired. For details see lockLNAndCheckDefunct(com.sleepycat.je.txn.LockType, boolean, boolean). On entry, the isLatched param says whether this.bin is latched or not. On return, this.bin is unlatched if the unlatch param is true or an exception is thrown.
    
    Returns:
    
    OperationResult, or null if the LN has been cleaned and cannot be fetched.
  - getCurrent
```
public OperationResult getCurrent(DatabaseEntry foundKey,
                                  DatabaseEntry foundData)
```
    Copy current record into the key and data DatabaseEntry.
    
    Returns:
    
    OperationResult, or null if the LN has been cleaned and cannot be fetched.
  - getCurrentLN
```
public LN getCurrentLN(boolean isLatched,
                       boolean unlatch)
```
  - lockAndGetCurrentLN
```
public LN lockAndGetCurrentLN(LockType lockType)
```
    Retrieve the current LN. BIN is unlatched on entry and exit.
  - getCurrentVersion
```
public RecordVersion getCurrentVersion(boolean allowFetch)
```
    Returns the VLSN and LSN for the record at the current position. Must be called when the cursor is positioned on a record. If this method is called on a secondary cursor, the version of the associated primary record is returned. In that case, the allowFetch parameter is ignored, and the version is available only if the primary record was retrieved (see setPriInfo).
    
    Parameters:
    
    allowFetch - is true to fetch the LN to get the VLSN, or false to return -1 for the VLSN if both the LN and VLSN are not cached.
    
    Throws:
    
    IllegalStateException - if the cursor is closed or uninitialized, or this is a secondary cursor and the version is not cached.
  - getStorageSize
```
public int getStorageSize()
```
    Returns the estimated disk storage size for the record at the current position. The size includes an estimation of the JE overhead for the record, in addition to the user key/data sizes. But it does not include obsolete overhead related to the record, i.e., space that could potentially be reclaimed by the cleaner.
    This method does not fetch the LN. Must be called when the cursor is positioned on a record.
    
    When called on a secondary cursor that was used to return the primary data, the size of the primary record is returned by this method. Otherwise the size of the record at this cursor position is returned.
    
    Returns:
    
    the estimated storage size, or zero when the size is unknown because a non-embedded LN is not resident and the LN was logged with a JE version prior to 6.0.
    
    Throws:
    
    IllegalStateException - if the cursor is closed or uninitialized.
    
    See Also:
    
    StorageSize
  - setPriInfo
```
public void setPriInfo(CursorImpl sourceCursor)
```
    When the primary record is read during a secondary operation, this method is called to copy the primary version and storage size here. This allows the secondary cursor API to return the version and size of the primary record. Note that a secondary record does not have a version of its own.
    
    Parameters:
    
    sourceCursor - contains the primary info, but may be a primary or secondary cursor.
  - getNSecondaryWrites
```
public int getNSecondaryWrites()
```
    Returns the number of secondary records written by the last put/delete operation at the current cursor position. NOTE: this method does not work (returns 0) if primary deletions are performed via a secondary (SecondaryDatabase/SecondaryCursor.delete).
    
    Returns:
    
    number of writes, or zero if a put/delete operation was not performed.
  - setNSecondaryWrites
```
public void setNSecondaryWrites(int nWrites)
```
  - advanceCursor
```
public boolean advanceCursor(DatabaseEntry key,
                             DatabaseEntry data)
```
    Advance a cursor. Used so that verify can advance a cursor even in the face of an exception [12932].
    
    Parameters:
    
    key - on return contains the key if available, or null.
    
    data - on return contains the data if available, or null.
  - getNext
```
public OperationResult getNext(DatabaseEntry foundKey,
                               DatabaseEntry foundData,
                               LockType lockType,
                               boolean dirtyReadAll,
                               boolean forward,
                               boolean isLatched,
                               RangeConstraint rangeConstraint)
```
    Move the cursor forward and return the next "valid" record. Whether a slot contains a "valid" record or not depends on the slot's KD/PD flags and the lockType and dirtyReadAll parameters. Four cases are considered; they are described in the lockLNAndCheckDefunct() method. This will cross BIN boundaries. On return, no latches are held. If no exceptions, the cursor is registered with its new location.
    
    Parameters:
    
    foundKey - DatabaseEntry to use for returning key
    
    foundData - DatabaseEntry to use for returning data
    
    forward - if true, move forward, else move backwards
    
    isLatched - if true, the bin that we're on is already latched.
    
    rangeConstraint - if non-null, is called to determine whether a key is out of range.
  - checkForInsertion
```
public boolean checkForInsertion(GetMode getMode,
                                 CursorImpl dupCursor)
```
    Used to detect phantoms during "get next" operations with serializable isolation. If this method returns true, the caller should restart the operation from the prior position. Something may have been added to the original cursor (cursorImpl) while we were getting the next BIN. cursorImpl would have been adjusted properly but we would have skipped a BIN in the process. This can happen when all INs are unlatched in Tree.getNextBin. It can also happen without a split, simply due to inserted entries in the previous BIN.
    
    Returns:
    
    true if an unaccounted for insertion happened. TODO: Unfortunately, this method doesn't cover all cases where a phantom may have been inserted. Another case is described below. IN-0 ---------------------- | | 50 | 100 | | ---------------------- / / \ \ / \ /---- ----\ IN-1 / \ IN-2 ---------------- ---------------- | 60 | 70 | 80 | | | | | ---------------- ---------------- / | \ / / | \ / ---------------- ----------------- | 81 | 83 | 85 | | 110 | | | ---------------- ----------------- BIN-3 BIN-4 Initially, the tree looks as above and a cursor (C) is located on the last slot of BIN-3. For simplicity, assume no duplicates and no serializable isolation. Also assume that C is a sticky cursor. 1. Thread 1 calls C.getNext(), which calls retrieveNextAllowPhantoms(), which duplicates C's cursorImpl, and calls dup.getNext(). dup.getNext() latches BIN-3, sets dup.binToBeRemoved to BIN-3 and then calls Tree.getNextBin(BIN-3). Tree.getNextBin(BIN-3) does the following: - sets searchKey to 85 - calls Tree.getParentINForChildIN(BIN-3). - Tree.getParentINForChildIN(BIN-3) unlatches BIN-3 and searches for BIN-3 parent, thus reaching IN-1. - IN-1.findEntry(85) sets "index" to 2, - "index" is incremented, - "moreEntriesThisIn" is set to false, - "next" is set to IN-1, . - Tree.getParentINForChildIN(IN-1) is called and unlatches IN-1. Assume at this point thread 1 looses the cpu. 2. Thread 2 inserts keys 90 and 95, causing a split of both BIN-3 and IN-1. So the tree now looks like this: IN-0 --------------------------- | | 50 | 80 | 100 | | --------------------------- / / | \ \ / | \ /--------- | ----------\ IN-1 / | \ IN-2 / IN-5 | \ ----------- ----------- ---------------- | 60 | 70 | | 80 | 90 | | | | | ----------- ----------- ---------------- / | / \ / / | / \ / ---------------- ----------- ----------------- | 81 | 83 | 85 | | 90 | 95 | | 110 | | | ---------------- ----------- ----------------- BIN-3 BIN-6 BIN-4 Notice that C.cursorImpl still points to the last slot of BIN-3. 3. Thread 1 resumes: - Tree.getParentINForChildIN(IN-1) reaches IN-0. - IN-0.findEntry(85) sets "index" to 2, - "index" is incremented, - "nextIN" is set to IN-2, which is latched. - Tree.searchSubTree(IN-2, LEFT) is called, and returns BIN-4. - BIN-4 is the result of Tree.getNextBin(BIN-3), i.e., BIN-6 was skipped Now we are back in dup.getNext(): - dup.bin is set to BIN-4, dup.index to -1, and dup is added to BIN-4 - the while loop repeats, dup.index is set to 0, the 1st slot of BIN-4 is locked, and dup.getNext() returns SUCCESS. Now we are back in C.retrieveNextAllowPhantoms(): - C.checkForInsertion() is called - C.cursorImpl and dup are on different BINs, but the condition: origBIN.getNEntries() - 1 > origCursor.getIndex() is false, so C.checkForInsertion() returns false. The end result is that BIN-6 has been missed. This is not be a "bug" for non-serializable isolation, but the above scenario applies to serializable isolation as well, and in that case, BIN-6 should really not be missed. This could be solved by re-implementing Tree.getNext/PrevBIN() do a more "logical" kind of search.
  - skip
```
public long skip(boolean forward,
                 long maxCount,
                 RangeConstraint rangeConstraint)
```
    Skips over entries until a boundary condition is satisfied, either because maxCount is reached or RangeConstraint.inBounds returns false. If a maxCount is passed, this allows advancing the cursor quickly by N entries. If a rangeConstraint is passed, this allows returning the entry count after advancing until the predicate returns false, e.g., the number of entries in a key range. In either case, the number of entries advanced is returned. Optimized to scan using level two of the tree when possible, to avoid calling getNextBin/getPrevBin for every BIN of the database. All BINs beneath a level two IN can be skipped quickly, with the level two parent IN latched, when all of its children BINs are resident and can be latched without waiting. When a child BIN is not resident or latching waits, we revert to the getNextBin/getPrevBin approach, to avoid keeping the parent IN latched for long time periods. Although this method positions the cursor on the last non-defunct entry seen (before the boundary condition is satisfied), because it does not lock the LN it is possible that it is made defunct by another thread after the BIN is unlatched.
    
    Parameters:
    
    forward - is true to skip forward, false to skip backward.
    
    maxCount - is the maximum number of non-defunct entries to skip, and may be LTE zero if no maximum is enforced.
    
    rangeConstraint - is a predicate that returns false at a position where advancement should stop, or null if no predicate is enforced.
    
    Returns:
    
    the number of non-defunct entries that were skipped.
  - getAncestorPath
```
public List<TrackingInfo> getAncestorPath()
```
    Returns the stack of ancestor TrackingInfo for the BIN at the cursor, or null if a split occurs and the information returned would be inconsistent. Used by CountEstimator.
  - lockNextKeyForInsert
```
public void lockNextKeyForInsert(DatabaseEntry key)
```
    Search for the next key following the given key, and acquire a range insert lock on it. If there are no more records following the given key, lock the special EOF node for the dbImpl.
  - lockLN
```
public CursorImpl.LockStanding lockLN(LockType lockType)
                               throws LockConflictException
```
    Does not allow uncontended locks. See lockLN(LockType, boolean).
    
    Throws:
    
    LockConflictException
  - lockAfterLsnChange
```
public static void lockAfterLsnChange(DatabaseImpl dbImpl,
                                      long oldLsn,
                                      long newLsn,
                                      Locker excludeLocker)
```
    After logging a deferred-write LN during eviction/checkpoint or a migrated LN during cleaning, for every existing lock on the old LSN held by another locker, we must lock the new LSN on behalf of that locker. This is done while holding the BIN latch so that the new LSN does not change during the locking process. The BIN must be latched on entry and is left latched by this method. We release the lock on the oldLsn to prevent locks from accumulating over time on a HandleLocker, as the cleaner migrates LNs, because Database handle locks are legitimately very long-lived. It is important to first acquire all lsn locks and then release the oldLsn locks. Releasing an oldLsn lock might allow another locker to acquire it, and then acquiring another lsn lock may encounter a conflict. [#20617]
    
    See Also:
    
    HandleLocker, lockLN(com.sleepycat.je.txn.LockType)
  - checkCursorState
```
public void checkCursorState(boolean mustBeInitialized,
                             boolean mustNotBeInitialized)
```
    Check that the cursor is open and optionally if it is initialized or uninitialized.
    
    Throws:
    
    IllegalStateException - via all Cursor methods that call Cursor.checkState (all get and put methods, plus more).
  - revertLock
```
public void revertLock(CursorImpl.LockStanding standing)
```
  - lockEof
```
public void lockEof(LockType lockType)
```
    Locks the logical EOF node for the dbImpl.
  - checkEnv
```
public void checkEnv()
```
    Throws:
    
    EnvironmentFailureException - if the underlying environment is invalid.
  - traverseDbWithCursor
```
public static void traverseDbWithCursor(DatabaseImpl db,
                                        LockType lockType,
                                        boolean allowEviction,
                                        CursorImpl.WithCursor withCursor)
```
    Enumerates all records in a dbImpl non-transactionally and calls the withCursor method for each record. Stops the enumeration if the callback returns false.
    
    Parameters:
    
    db - DatabaseImpl to traverse.
    
    lockType - non-null LockType for reading records.
    
    allowEviction - should normally be true to evict when performing multiple operations, but may be false if eviction is disallowed in a particular context.
    
    withCursor - callback object.
  - dump
```
public void dump(boolean verbose)
```
    Dump the cursor for debugging purposes. Dump the bin that the cursor refers to if verbose is true.
  - dump
```
public void dump()
```
    dump the cursor for debugging purposes.
  - dumpToString
```
public String dumpToString(boolean verbose)
```
  - getLockStats
```
public StatGroup getLockStats()
```
  - setTestHook
```
public void setTestHook(TestHook hook)
```

Class CursorImpl

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FOUND

EXACT_KEY

FOUND_LAST

Constructor Detail

CursorImpl

CursorImpl

Method Detail

cloneCursor

hashCode

getLocker

getDb

setClosingLocker

clearClosingLocker

getCacheMode

setCacheMode

setTreeStatsAccumulator

incrementLNCount

getIndex

getBIN

setIndex

setOnFirstSlot

setOnLastSlot

isOnBIN

assertBIN

isOnSamePosition

setBIN

latchBIN

releaseBIN

getCurrentNodeId

getCurrentLsn

getCurrentLsn

getCurrentKey

getCurrentKey

isProbablyExpired

getExpirationTime

isClosed

isNotInitialized

isInternalDbCursor

hasDuplicates

beforeNonStickyOp

afterNonStickyOp

reset

close

close

setAllowEviction

criticalEviction

evictLN

deleteCurrentRecord

updateCurrentRecord

insertRecord

insertOrUpdateRecord

positionFirstOrLast

searchRange

searchExact

searchExact

lockAndGetCurrent

lockAndGetCurrent

getCurrent

getCurrentLN

lockAndGetCurrentLN

getCurrentVersion

getStorageSize

setPriInfo

getNSecondaryWrites

setNSecondaryWrites

advanceCursor

getNext

checkForInsertion

skip

getAncestorPath

lockNextKeyForInsert

lockLN

lockAfterLsnChange