com.sleepycat.je

Class EnvironmentFailureException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.sleepycat.je.DatabaseException

com.sleepycat.je.RunRecoveryException

com.sleepycat.je.EnvironmentFailureException

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

EnvironmentLockedException, EnvironmentNotFoundException, EnvironmentWedgedException, GroupShutdownException, LogWriteException, RestartRequiredException, ThreadInterruptedException, VersionMismatchException

public class EnvironmentFailureException
extends RunRecoveryException

Indicates that a failure has occurred that could impact the Environment as a whole. For failures that impact only the current operation and/or transaction, see OperationFailureException). For an overview of all exceptions thrown by JE, see DatabaseException.

Depending on the nature of the failure, this exception may indicate that Environment.close() must be called. The application should catch EnvironmentFailureException and then call Environment.isValid(). If false is returned, all Environment handles (instances) must be closed and re-opened in order to run recovery and continue operating. If true is returned, the Environment can continue operating without being closed and re-opened. Also note that Environment.isValid() may be called at any time, not just during exception handling.

The use of the Environment.isValid() method allows JE to determine dynamically whether the failure requires recovery 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 Environment.

(Although this exception class extends RunRecoveryException, it does not always indicate that recovery is necessary, as described above. RunRecoveryException has been deprecated and EnvironmentFailureException should be used instead.)

If an EnvironmentFailureException consistently occurs soon after opening the Environment, this may indicate a persistent problem. It may indicate a system problem or a persistent storage problem. In this case, human intervention is normally required and restoring from a backup may be necessary.

Note that subclasses of EnvironmentFailureException indicate how to handle the exception in more specific ways.

• If Thread.interrupt is called for a thread performing JE operations, a ThreadInterruptedException is thrown. Since interrupting a thread is intentional, it does not indicate a persistent problem and human intervention is not normally required.
• If an IOException occurs while writing to the JE log, a LogWriteException is thrown. Although an IOException can occur for different reasons, it is a hint that the disk may be full and applications may wish to attempt recovery after making more disk space available.
• For replicated environments, see the subclasses of EnvironmentFailureException in the com.sleepycat.je.rep package for more information. Such exceptions may require special handling.

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

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
java.lang.String	getMessage()
boolean	isCorrupted() Whether the EnvironmentFailureException indicates that the log is corrupt, meaning that a network restore (or restore from backup) should be performed.

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

Method Detail

getMessage

public java.lang.String getMessage()

Overrides:

getMessage in class DatabaseException

isCorrupted

public boolean isCorrupted()

Whether the EnvironmentFailureException indicates that the log is corrupt, meaning that a network restore (or restore from backup) should be performed.

This method currently returns true only when corruption has been detected and is persistent. This may have been detected by verifying checksums in the disk data log, and in this case the corruption indicates a media/disk failure. The checksum error may have been detected when accessing data normally via the JE API, or by the background data verifier (see EnvironmentConfig.VERIFY_LOG). Or a persistent Btree corruption may have been detected by the data verifier (see EnvironmentConfig.VERIFY_BTREE) or by the Environment.verify(VerifyConfig, PrintStream) or Database.verify(VerifyConfig) methods. This method will returns true in all such cases.

Additionally, when a persistent corruption is detected and the Environment is open for read-write access, a marker file named 7fffffff.jdb is created in the Environment directory that will prevent re-opening the environment. If an attempt is made to re-open the Environment, the original EnvironmentFailureException will be thrown. This is meant to safeguard against using a corrupt environment when the original exception is accidentally overlooked. While the marker file can be deleted to allow re-opening the environment, this is normally unsafe and is not recommended.

Returns:

true if the environment is corrupt.

Since:

7.3