com.sleepycat.je

Class OperationFailureException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.sleepycat.je.DatabaseException

com.sleepycat.je.OperationFailureException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

DatabaseExistsException, DatabaseNotFoundException, DatabasePreemptedException, DeletedClassException, DiskLimitException, DiskOrderedCursorProducerException, DuplicateDataException, IncompatibleClassException, IndexNotAvailableException, InsufficientAcksException, InsufficientReplicasException, LockConflictException, LogOverwriteException, MasterTransferFailureException, MemberNotFoundException, ReplicaConsistencyException, SecondaryReferenceException, SequenceExistsException, SequenceIntegrityException, SequenceNotFoundException, SequenceOverflowException, StateChangeException, StoreExistsException, StoreNotFoundException, XAFailureException

public abstract class OperationFailureException
extends DatabaseException

Indicates that a failure has occurred that impacts the current operation and/or transaction. For failures that impact the environment as a whole, see EnvironmentFailureException. For an overview of all exceptions thrown by JE, see DatabaseException.

If an explicit transaction applies to a method which threw this exception, the exception may indicate that Transaction.abort() must be called, depending on the nature of the failure. A transaction is applicable to a method call in two cases.

1. When an explicit (non-null) Transaction instance is specified. This applies when the Transaction is passed as a parameter to the method that throws the exception, or when the Transaction is passed to Database.openCursor(com.sleepycat.je.Transaction, com.sleepycat.je.CursorConfig) and a Cursor method throws the exception.
2. When a per-thread Transaction applies to the method that throws the exception. Per-thread transactions apply when using persistent collections with CurrentTransaction or TransactionRunner, or when using XA transactions with XAEnvironment.

When a transaction is applicable to a method call, the application should catch OperationFailureException and then call Transaction.isValid(). If false is returned, all Cursor instances that were created with the transaction must be closed and then Transaction.abort() must be called. Also note that Transaction.isValid() may be called at any time, not just during exception handling.

The use of the Transaction.isValid() method allows JE to determine dynamically whether the failure requires an abort or not, and allows for this determination to change in future releases. Over time, internal improvements to error handling may allow more error conditions to be handled without invalidating the Transaction.

The specific handling that is necessary for an OperationFailureException depends on the specific subclass thrown. See the javadoc for each method for information on which methods throw which OperationFailureExceptions and why.

If Transaction.abort() is not called after an OperationFailureException invalidates the Transaction, all subsequent method calls using the Transaction will throw the same exception. This provides more than one opportunity to catch and handle the specific exception subclass that caused the failure.

OperationFailureException is also thrown by methods where no transaction applies. In most cases the action required to handle the exception is the same as with a transaction, although of course no abort is necessary.

However, please be aware that for some operations on a non-transactional Database or EntityStore, an OperationFailureException may cause data corruption. For example, see SecondaryReferenceException.

There are two groups of operation failure subclasses worth noting since they apply to many methods: read operation failures and write operation failures. These are described below.

Read Operation Failures

Read operations are all those performed by the get family of methods, for example, Database.get, Cursor.getNext, EntityIndex.get, EntityCursor.next, StoredMap.get, and ForwardCursor.getNext. These methods may cause the following operation failures.

• OperationFailureException is the superclass of all read operation failures.
• LockConflictException is thrown if a lock conflict prevents the operation from completing. A read operation may be blocked by another locker (transaction or non-transactional cursor) that holds a write lock on the record.
• LockPreemptedException is a subclass of LockConflictException that is thrown in a replicated environment on the Replica node, when the Master node has changed a record that was previously locked by the reading transaction or cursor.
• SecondaryIntegrityException is thrown if a primary-secondary relationship integrity problem is detected while reading a primary database record via a secondary index.
• DatabasePreemptedException is thrown in a replicated environment on the Replica node, when the Master node has truncated, removed or renamed the database.
• Other OperationFailureException subclasses may be thrown if such an exception was thrown earlier and caused the transaction to be invalidated.

Write Operation Failures

Write operations are all those performed by the put and delete families of methods, for example, Database.put, Cursor.delete, PrimaryIndex.put, EntityCursor.delete and StoredMap.put. These methods may cause the following operation failures, although certain failures are only caused by put methods and others only by delete methods, as noted below.

• OperationFailureException is the superclass of all write operation failures.
• LockConflictException is thrown if a lock conflict prevents the operation from completing. A write operation may be blocked by another locker (transaction or non-transactional cursor) that holds a read or write lock on the record.
• DiskLimitException is thrown if a disk limit has been violated and this prevents the operation from completing.

• SecondaryConstraintException is the superclass of all exceptions thrown when a write operation fails because of a secondary constraint.
• ForeignConstraintException is thrown when an attempt to write a primary database record would insert a secondary record with a key that does not exist in a foreign key database, when the secondary key is configured as a foreign key. This exception is only thrown by put methods.
• UniqueConstraintException is thrown when an attempt to write a primary database record would insert a secondary record with a duplicate key, for secondaries that represent one-to-one and one-to-many relationships. This exception is only thrown by put methods.
• DeleteConstraintException is thrown when an attempt is made to delete a key from a foreign key database, when that key is referenced by a secondary database, and the secondary is configured to cause an abort in this situation. This exception is only thrown by delete methods.
• SecondaryIntegrityException is thrown if a primary-secondary relationship integrity problem is detected while writing a record in a primary database that has one or more secondary indices.
• DatabasePreemptedException is thrown in a replicated environment on a Replica node, when the Master node has truncated, removed or renamed the database.
• ReplicaWriteException is always thrown in a replicated environment on a Replica node, since write operations are not allowed on a Replica.
• Other OperationFailureException subclasses may be thrown if such an exception was thrown earlier and caused the transaction to be invalidated.

Since:

4.0

See Also:

Serialized Form

Method Summary

Methods inherited from class com.sleepycat.je.DatabaseException

getMessage

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

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