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:

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

Constructor Summary

Constructors

Modifier	Constructor and Description
	EnvironmentFailureException(EnvironmentImpl envImpl, EnvironmentFailureReason reason) For internal use only.
	EnvironmentFailureException(EnvironmentImpl envImpl, EnvironmentFailureReason reason, String message) For internal use only.
	EnvironmentFailureException(EnvironmentImpl envImpl, EnvironmentFailureReason reason, String message, Throwable cause) For internal use only.
	EnvironmentFailureException(EnvironmentImpl envImpl, EnvironmentFailureReason reason, Throwable cause) For internal use only.
protected	EnvironmentFailureException(String message, EnvironmentFailureException cause) For internal use only.

Method Summary

Modifier and Type	Method and Description
static void	assertState(boolean cond) For internal use only.
static void	assertState(boolean cond, String message) For internal use only.
String	getMessage()
EnvironmentFailureReason	getReason() For internal use only.
boolean	isCorrupted() Whether the EnvironmentFailureException indicates that the log is corrupt, meaning that a network restore (or restore from backup) should be performed.
static EnvironmentFailureException	makeJavaErrorWrapper() For internal use only.
static EnvironmentFailureException	promote(EnvironmentImpl envImpl, EnvironmentFailureReason reason, String message, Throwable cause) For internal use only.
void	setAlreadyThrown(boolean alreadyThrown) For internal use only.
static EnvironmentFailureException	unexpectedException(EnvironmentImpl envImpl, Exception cause) For internal use only.
static EnvironmentFailureException	unexpectedException(EnvironmentImpl envImpl, String message, Exception cause) For internal use only.
static EnvironmentFailureException	unexpectedException(Exception cause) For internal use only.
static EnvironmentFailureException	unexpectedException(String message, Exception cause) For internal use only.
static EnvironmentFailureException	unexpectedState() For internal use only.
static EnvironmentFailureException	unexpectedState(EnvironmentImpl envImpl) For internal use only.
static EnvironmentFailureException	unexpectedState(EnvironmentImpl envImpl, String message) For internal use only.
static EnvironmentFailureException	unexpectedState(String message) For internal use only.
EnvironmentFailureException	wrapSelf(String msg) For internal use only.

Methods inherited from class com.sleepycat.je.DatabaseException

addErrorMessage, addRethrownStackTrace, getVersionHeader

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

Constructor Detail

EnvironmentFailureException

public EnvironmentFailureException(EnvironmentImpl envImpl,
                                   EnvironmentFailureReason reason)

For internal use only.

EnvironmentFailureException

public EnvironmentFailureException(EnvironmentImpl envImpl,
                                   EnvironmentFailureReason reason,
                                   Throwable cause)

For internal use only.

EnvironmentFailureException

public EnvironmentFailureException(EnvironmentImpl envImpl,
                                   EnvironmentFailureReason reason,
                                   String message)

For internal use only.

EnvironmentFailureException

public EnvironmentFailureException(EnvironmentImpl envImpl,
                                   EnvironmentFailureReason reason,
                                   String message,
                                   Throwable cause)

For internal use only.

EnvironmentFailureException

protected EnvironmentFailureException(String message,
                                      EnvironmentFailureException cause)

For internal use only.

Method Detail

wrapSelf

public EnvironmentFailureException wrapSelf(String msg)

For internal use only.

setAlreadyThrown

public void setAlreadyThrown(boolean alreadyThrown)

For internal use only.

getMessage

public String getMessage()

Overrides:

getMessage in class DatabaseException

getReason

public EnvironmentFailureReason getReason()

For internal use only.

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

makeJavaErrorWrapper

public static EnvironmentFailureException makeJavaErrorWrapper()

For internal use only.

promote

public static EnvironmentFailureException promote(EnvironmentImpl envImpl,
                                                  EnvironmentFailureReason reason,
                                                  String message,
                                                  Throwable cause)

For internal use only.

Returns:

the resulting EnvironmentFailureException.

unexpectedException

public static EnvironmentFailureException unexpectedException(Exception cause)

For internal use only.

unexpectedException

public static EnvironmentFailureException unexpectedException(EnvironmentImpl envImpl,
                                                              Exception cause)

For internal use only.

unexpectedException

public static EnvironmentFailureException unexpectedException(String message,
                                                              Exception cause)

For internal use only.

unexpectedException

public static EnvironmentFailureException unexpectedException(EnvironmentImpl envImpl,
                                                              String message,
                                                              Exception cause)

For internal use only.

unexpectedState

public static EnvironmentFailureException unexpectedState()

For internal use only.

unexpectedState

public static EnvironmentFailureException unexpectedState(EnvironmentImpl envImpl)

For internal use only.

unexpectedState

public static EnvironmentFailureException unexpectedState(String message)

For internal use only.

unexpectedState

public static EnvironmentFailureException unexpectedState(EnvironmentImpl envImpl,
                                                          String message)

For internal use only.

assertState

public static void assertState(boolean cond)

For internal use only.

assertState

public static void assertState(boolean cond,
                               String message)

For internal use only.