CursorConfig (Oracle - Berkeley DB Java Edition API)
Date: 2014-12-16

com.sleepycat.je

## Class CursorConfig

- java.lang.Object
- - com.sleepycat.je.CursorConfig

- All Implemented Interfaces:
    Cloneable

      public class CursorConfig
      extends Object
      implements 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

    Methods
    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.
    `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 `NOTFOUND` is returned or an exception is thrown. 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.

      Note that `CacheMode.EVICT_BIN` and `CacheMode.MAKE_COLD` are incompatible with the non-sticky feature. When these cache modes are used, the cursor will behave as if were sticky, regardless of whether non-sticky is set to true using this method.

      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 `Object`

    - #### toString

          public String toString()

      Returns the values for each configuration attribute.
      Overrides:
        `toString` in class `Object`
      Returns:
        the values for each configuration attribute.

Copyright (c) 2004, 2014 Oracle and/or its affiliates. All rights reserved.