com.sleepycat.je.CursorConfig Maven / Gradle / Ivy
The newest version!
/*-
* Copyright (C) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
*
* This file was distributed by Oracle as part of a version of Oracle Berkeley
* DB Java Edition made available at:
*
* http://www.oracle.com/technetwork/database/database-technologies/berkeleydb/downloads/index.html
*
* Please see the LICENSE file included in the top-level directory of the
* appropriate version of Oracle Berkeley DB Java Edition for a copy of the
* license and additional information.
*/
package com.sleepycat.je;
/**
* Specifies the attributes of database cursor. An instance created with the
* default constructor is initialized with the system's default settings.
*/
public class CursorConfig implements Cloneable {
/**
* Default configuration used if null is passed to methods that create a
* cursor.
*/
public static final CursorConfig DEFAULT = new CursorConfig();
/**
* A convenience instance to configure read operations performed by the
* cursor to return modified but not yet committed data.
*/
public static final CursorConfig READ_UNCOMMITTED = new CursorConfig();
/**
* 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.
*/
public static final CursorConfig READ_COMMITTED = new CursorConfig();
static {
READ_UNCOMMITTED.setReadUncommitted(true);
READ_COMMITTED.setReadCommitted(true);
}
private boolean readUncommitted = false;
private boolean readCommitted = false;
private boolean nonSticky = false;
/**
* An instance created using the default constructor is initialized with
* the system's default settings.
*/
public CursorConfig() {
}
/**
* Configures read operations performed by the cursor to return modified
* but not yet committed data.
*
* @param readUncommitted If true, configure read operations performed by
* the cursor to return modified but not yet committed data.
*
* @see LockMode#READ_UNCOMMITTED
*
* @return this
*/
public CursorConfig setReadUncommitted(boolean readUncommitted) {
setReadUncommittedVoid(readUncommitted);
return this;
}
/**
* @hidden
* The void return setter for use by Bean editors.
*/
public void setReadUncommittedVoid(boolean readUncommitted) {
this.readUncommitted = readUncommitted;
}
/**
* Returns true if read operations performed by the cursor are configured
* to return modified but not yet committed data.
*
* @return true if read operations performed by the cursor are configured
* to return modified but not yet committed data.
*
* @see LockMode#READ_UNCOMMITTED
*/
public boolean getReadUncommitted() {
return readUncommitted;
}
/**
* 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.
*
* @param readCommitted If true, configure read operations performed by
* the cursor to obey read committed isolation.
*
* @see LockMode#READ_COMMITTED
*
* @return this
*/
public CursorConfig setReadCommitted(boolean readCommitted) {
setReadCommittedVoid(readCommitted);
return this;
}
/**
* @hidden
* The void return setter for use by Bean editors.
*/
public void setReadCommittedVoid(boolean readCommitted) {
this.readCommitted = readCommitted;
}
/**
* Returns true if read operations performed by the cursor are configured
* to obey read committed isolation.
*
* @return true if read operations performed by the cursor are configured
* to obey read committed isolation.
*
* @see LockMode#READ_COMMITTED
*/
public boolean getReadCommitted() {
return readCommitted;
}
/**
* Configures the behavior of the cursor when a cursor movement operation
* returns {@link 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
* {@link Cursor#getFirst} is called successfully, and then
* {@link Cursor#getNext} is called, if {@code getNext} returns
* {@code 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 {@code getNext} returns {@code 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 {@code getNext}
* returns {@code 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), {@code 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:
*
* - {@link Cursor#putNoOverwrite}
* - {@link Cursor#getNextDup}}
* - {@link Cursor#getPrevDup}}
* - {@link Cursor#getNextNoDup}}
* - {@link Cursor#getPrevNoDup}}
*
*
* @param nonSticky if false (the default), the prior position is
* maintained by cursor movement operations, and the cursor stays at the
* prior position when {@code NOTFOUND} is returned. If true, the prior
* position is not maintained, and the cursor is reinitialized when
* {@code NOTFOUND} is returned.
*
* @return this
*/
public CursorConfig setNonSticky(boolean nonSticky) {
setNonStickyVoid(nonSticky);
return this;
}
/**
* @hidden
* The void return setter for use by Bean editors.
*/
public void setNonStickyVoid(boolean nonSticky) {
this.nonSticky = nonSticky;
}
/**
* Returns the non-sticky setting.
*
* @see #setNonSticky
*/
public boolean getNonSticky() {
return nonSticky;
}
/**
* Returns a copy of this configuration object.
*/
@Override
public CursorConfig clone() {
try {
return (CursorConfig) super.clone();
} catch (CloneNotSupportedException willNeverOccur) {
return null;
}
}
/**
* Returns the values for each configuration attribute.
*
* @return the values for each configuration attribute.
*/
@Override
public String toString() {
return "readUncommitted=" + readUncommitted +
"\nreadCommitted=" + readCommitted +
"\n";
}
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy