Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD | DETAIL: ENUM CONSTANTS | FIELD | METHOD

## com.sleepycat.je
Enum LockMode

    java.lang.Object
      java.lang.Enum<LockMode>
          com.sleepycat.je.LockMode

All Implemented Interfaces:
  Serializable, Comparable<LockMode>

    public enum LockMode

extends Enum<LockMode>

Record lock modes for read operations. Lock mode parameters may be specified for all operations that retrieve data.

Locking Rules

Together with `CursorConfig`, `TransactionConfig` and `EnvironmentConfig` settings, lock mode parameters determine how records are locked during read operations. Record locking is used to enforce the isolation modes that are configured. Record locking is summarized below for read and write operations. For more information on isolation levels and transactions, see Writing Transactional Applications.

With one exception, a record lock is always acquired when a record is read or written, and a cursor will always hold the lock as long as it is positioned on the record. The exception is when `READ_UNCOMMITTED` is specified, which allows a record to be read without any locking.

Both read (shared) and write (exclusive) locks are used. Read locks are normally acquired on read (`get` method} operations and write locks on write (`put` method) operations. However, a write lock will be acquired on a read operation if `RMW` is specified.

Because read locks are shared, multiple accessors may read the same record. Because write locks are exclusive, if a record is written by one accessor it may not be read or written by another accessor. An accessor is either a transaction or a thread (for non-transactional operations).

Whether additional locking is performed and how locks are released depend on whether the operation is transactional and other configuration settings.

Transactional Locking

Transactional operations include all write operations for a transactional database, and read operations when a non-null `Transaction` parameter is passed. When a null transaction parameter is passed for a write operation for a transactional database, an auto-commit transaction is automatically used.

With transactions, read and write locks are normally held until the end of the transaction (commit or abort). Write locks are always held until the end of the transaction. However, if `READ_COMMITTED` is configured, then read locks for cursor operations are only held during the operation and while the cursor is positioned on the record. The read lock is released when the cursor is moved to a different record or closed. When `READ_COMMITTED` is used for a database (non-cursor) operation, the read lock is released before the method returns.

When neither `READ_UNCOMMITTED` nor `READ_COMMITTED` is specified, read and write locking as described above provide Repeatable Read isolation, which is the default transactional isolation level. If Serializable isolation is configured, additional "next key" locking is performed to prevent "phantoms" -- records that are not visible at one point in a transaction but that become visible at a later point after being inserted by another transaction. Serializable isolation is configured via `TransactionConfig.setSerializableIsolation(boolean)` or `EnvironmentConfig.setTxnSerializableIsolation(boolean)`.

Non-Transactional Locking

Non-transactional operations include all operations for a non-transactional database (including a Deferred Write database), and read operations for a transactional database when a null `Transaction` parameter is passed.

For non-transactional operations, both read and write locks are only held while a cursor is positioned on the record, and are released when the cursor is moved to a different record or closed. For database (non-cursor) operations, the read or write lock is released before the method returns.

This behavior is similar to `READ_COMMITTED`, except that both read and write locks are released. Configuring `READ_COMMITTED` for a non-transactional database cursor has no effect.

Because the current thread is the accessor (locker) for non-transactional operations, a single thread may have multiple cursors open without locking conflicts. Two non-transactional cursors in the same thread may access the same record via write or read operations without conflicts, and the changes make by one cursor will be visible to the other cursor.

However, a non-transactional operation will conflict with a transactional operation for the same record even when performed in the same thread. When using a transaction in a particular thread for a particular database, to avoid conflicts you should use that transaction for all access to that database in that thread. In other words, to avoid conflicts always pass the transction parameter, not null, for all operations. If you don't wish to hold the read lock for the duration of the transaction, specify `READ_COMMITTED`.

Enum Constant Summary
`DEFAULT` Uses the default lock mode and is equivalent to passing `null` for the lock mode parameter.
`READ_COMMITTED` Read committed isolation provides for cursor stability but not repeatable reads.
`READ_UNCOMMITTED` Reads modified but not yet committed data.
`RMW` Acquire write locks instead of read locks when doing the retrieval.

Method Summary
`String` | `toString()`
`static LockMode` | `valueOf(String name)` Returns the enum constant of this type with the specified name.
`static LockMode[]` | `values()` Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum
`clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, valueOf`

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, wait, wait, wait`

Enum Constant Detail

### DEFAULT

    public static final LockMode DEFAULT

  Uses the default lock mode and is equivalent to passing `null` for the lock mode parameter.

  The default lock mode is `READ_UNCOMMITTED` when this lock mode is configured via `CursorConfig.setReadUncommitted(boolean)` or `TransactionConfig.setReadUncommitted(boolean)`. The Read Uncommitted mode overrides any other configuration settings.

  Otherwise, the default lock mode is `READ_COMMITTED` when this lock mode is configured via `CursorConfig.setReadCommitted(boolean)` or `TransactionConfig.setReadCommitted(boolean)`. The Read Committed mode overrides other configuration settings except for `READ_UNCOMMITTED`.

  Otherwise, the default lock mode is to acquire read locks and release them according to the `default locking rules` for transactional and non-transactional operations.

### READ_UNCOMMITTED

    public static final LockMode READ_UNCOMMITTED

  Reads modified but not yet committed data.

  The Read Uncommitted mode is used if this lock mode is explicitly passed for the lock mode parameter, or if null or `DEFAULT` is passed and Read Uncommitted is the default -- see `DEFAULT` for details.

  See the `locking rules` for information on how Read Uncommitted impacts transactional and non-transactional locking.

### READ_COMMITTED

    public static final LockMode READ_COMMITTED

  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. Note that this LockMode may only be passed to `Database` get methods, not to `Cursor` methods. To configure a cursor for Read Committed isolation, use `CursorConfig.setReadCommitted(boolean)`.

  See the `locking rules` for information on how Read Committed impacts transactional and non-transactional locking.

### RMW

    public static final LockMode RMW

  Acquire write locks instead of read locks when doing the retrieval.

  Because it causes a write lock to be acquired, specifying this lock mode as a `Cursor` or `Database` `get` (read) method parameter will override the Read Committed or Read Uncommitted isolation mode that is configured using `CursorConfig` or `TransactionConfig`. The write lock will acquired and held until the end of the transaction. For non-transactional use, the write lock will be released when the cursor is moved to a new position or closed.

  Setting this flag can eliminate deadlock during a read-modify-write cycle by acquiring the write lock during the read part of the cycle so that another thread of control acquiring a read lock for the same item, in its own read-modify-write cycle, will not result in deadlock.

Method Detail

### values

    public static LockMode[] values()

  Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

      for (LockMode c : LockMode.values())
          System.out.println(c);

  Returns:
    an array containing the constants of this enum type, in the order they are declared

### valueOf

    public static LockMode valueOf(String name)

  Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

  Parameters:
    `name` - the name of the enum constant to be returned.
  Returns:
    the enum constant with the specified name
  Throws:
    `IllegalArgumentException` - if this enum type has no constant with the specified name
    `NullPointerException` - if the argument is null

### toString

    public String toString()

  Overrides:
    `toString` in class `Enum<LockMode>`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DB Java Edition version 4.0.103
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | ENUM CONSTANTS | FIELD | METHOD | DETAIL: ENUM CONSTANTS | FIELD | METHOD

Copyright (c) 2004-2010 Oracle. All rights reserved.