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 | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  Serializable

Direct Known Subclasses:
  DatabaseExistsException, DatabaseNotFoundException, DatabasePreemptedException, DeletedClassException, DuplicateDataException, IncompatibleClassException, IndexNotAvailableException, InsufficientAcksException, InsufficientReplicasException, LockConflictException, LogOverwriteException, 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 thrown which `OperationFailureException`s 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` and `StoredMap.get`. 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.
- `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
`fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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 | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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