com.sleepycat.je

Class CursorConfig

java.lang.Object

com.sleepycat.je.CursorConfig

All Implemented Interfaces:

java.lang.Cloneable

public class CursorConfig
extends java.lang.Object
implements java.lang.Cloneable

Specifies the attributes of database cursor. An instance created with the default constructor is initialized with the system's default settings.

Field Summary

Fields

Modifier and Type	Field and Description
static CursorConfig	DEFAULT Default configuration used if null is passed to methods that create a cursor.
static CursorConfig	READ_COMMITTED A convenience instance to configure a cursor for read committed isolation.
static CursorConfig	READ_UNCOMMITTED A convenience instance to configure read operations performed by the cursor to return modified but not yet committed data.

Constructor Summary

Constructors

Constructor and Description
CursorConfig() An instance created using the default constructor is initialized with the system's default settings.

Method Summary

Modifier and Type	Method and Description
CursorConfig	clone() Returns a copy of this configuration object.
boolean	getNonSticky() Returns the non-sticky setting.
boolean	getReadCommitted() Returns true if read operations performed by the cursor are configured to obey read committed isolation.
boolean	getReadUncommitted() Returns true if read operations performed by the cursor are configured to return modified but not yet committed data.
CursorConfig	setNonSticky(boolean nonSticky) Configures the behavior of the cursor when a cursor movement operation returns OperationStatus.NOTFOUND.
CursorConfig	setReadCommitted(boolean readCommitted) Configures read operations performed by the cursor to obey read committed isolation.
CursorConfig	setReadUncommitted(boolean readUncommitted) Configures read operations performed by the cursor to return modified but not yet committed data.
java.lang.String	toString() Returns the values for each configuration attribute.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT

public static final CursorConfig DEFAULT

Default configuration used if null is passed to methods that create a cursor.

READ_UNCOMMITTED

public static final CursorConfig READ_UNCOMMITTED

A convenience instance to configure read operations performed by the cursor to return modified but not yet committed data.

READ_COMMITTED

public static final CursorConfig READ_COMMITTED

A convenience instance to configure a cursor for read committed isolation. This ensures the stability of the current data item read by the cursor but permits data read by this cursor to be modified or deleted prior to the commit of the transaction.

Constructor Detail

CursorConfig

public CursorConfig()

An instance created using the default constructor is initialized with the system's default settings.

Method Detail

setReadUncommitted

public CursorConfig setReadUncommitted(boolean readUncommitted)

Configures read operations performed by the cursor to return modified but not yet committed data.

Parameters:

readUncommitted - If true, configure read operations performed by the cursor to return modified but not yet committed data.

Returns:

this

See Also:

LockMode.READ_UNCOMMITTED

getReadUncommitted

public boolean getReadUncommitted()

Returns true if read operations performed by the cursor are configured to return modified but not yet committed data.

Returns:

true if read operations performed by the cursor are configured to return modified but not yet committed data.

See Also:

LockMode.READ_UNCOMMITTED

setReadCommitted

public CursorConfig setReadCommitted(boolean readCommitted)

Configures read operations performed by the cursor to obey read committed isolation. Read committed isolation provides for cursor stability but not repeatable reads. Data items which have been previously read by this transaction may be deleted or modified by other transactions before the cursor is closed or the transaction completes.

Parameters:

readCommitted - If true, configure read operations performed by the cursor to obey read committed isolation.

Returns:

this

See Also:

LockMode.READ_COMMITTED

getReadCommitted

public boolean getReadCommitted()

Returns true if read operations performed by the cursor are configured to obey read committed isolation.

Returns:

true if read operations performed by the cursor are configured to obey read committed isolation.

See Also:

LockMode.READ_COMMITTED

setNonSticky

public CursorConfig setNonSticky(boolean nonSticky)

Configures the behavior of the cursor when a cursor movement operation returns OperationStatus.NOTFOUND. 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. For example, if Cursor.getFirst(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode) is called successfully, and then Cursor.getNext(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode) is called, if getNext returns NOTFOUND the cursor will remain positioned on the first record.

Also, as part of maintaining the prior position, the lock on the record at the current position will be held (at least) until after a cursor movement operation succeeds and acquires a lock on the record at the new position. In the example above, a lock on the first record will still be held after getNext returns NOTFOUND.

If the cursor is configured to be non-sticky, the prior position is not maintained, and this has certain performance advantages:

• Some processing is avoided because the prior position is not maintained.
• The lock on the record at the prior position is released before acquiring the lock on the record at the new position (when the cursor movement operation succeeds.) This can help to prevent deadlocks in certain situations. Namely, if the cursor's isolation mode allows locks to be released when moving to a new position, then only one lock at a time will be held by the cursor. Holding multiple locks at a time can cause deadlocks, when locks are acquired in different orders by different threads, for example, when one cursor is scanning forward and another cursor is scanning backward. Note that this optimization does not apply to repeatable-read or serializable isolation, since these modes require that locks are not released by cursor movement operations.

However, when the cursor is configured as non-sticky and getNext returns NOTFOUND in the example above, the cursor position will be uninitialized, as if it had just been opened. Also, the lock on the first record will have been released (except when repeatable-read or serializable isolation is configured.) To move to the first record (and lock it), getFirst must be called again.

Also note that in certain circumstances, internal algorithms require that the prior position is retained, and the operation will behave as if the cursor is sticky. Specifically, these are only the following methods, and only when called on a database with duplicates configured:

• Cursor.putNoOverwrite(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry)
• Cursor.getNextDup(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode)}
• Cursor.getPrevDup(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode)}
• Cursor.getNextNoDup(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode)}
• Cursor.getPrevNoDup(com.sleepycat.je.DatabaseEntry, com.sleepycat.je.DatabaseEntry, com.sleepycat.je.LockMode)}

Parameters:

nonSticky - if false (the default), the prior position is maintained by cursor movement operations, and the cursor stays at the prior position when NOTFOUND is returned. If true, the prior position is not maintained, and the cursor is reinitialized when NOTFOUND is returned.

Returns:

this

getNonSticky

public boolean getNonSticky()

Returns the non-sticky setting.

See Also:

setNonSticky(boolean)

clone

public CursorConfig clone()

Returns a copy of this configuration object.

Overrides:

clone in class java.lang.Object

toString

public java.lang.String toString()

Returns the values for each configuration attribute.

Overrides:

toString in class java.lang.Object

Returns:

the values for each configuration attribute.