Top Description Fields Constructors Methods
org.apache.derby.shared.common.sanity

public Class SanityManager

extends Object
Class Inheritance
Imports
java.util.Hashtable, .Enumeration
The SanityService provides assertion checking and debug control.

Assertions and debug checks can only be used for testing conditions that might occur in development code but not in production code. They are compiled out of production code.

Uses of assertions should not add AssertFailure catches or throws clauses; AssertFailure is under RuntimeException in the java exception hierarchy. Our outermost system block will bring the system down when it detects an assertion failure.

In addition to ASSERTs in code, classes can choose to implement an isConsistent method that would be used by ASSERTs, UnitTests, and any other code wanting to check the consistency of an object.

Assertions are meant to be used to verify the state of the system and bring the system down if the state is not correct. Debug checks are meant to display internal information about a running system.

See Also
org.apache.derby.shared.common.sanity.AssertFailure

Field Summary

Modifier and TypeField and Description
private static boolean
AllDebugOff

private static boolean
AllDebugOn

AllDebugOn and AllDebugOff override individual flags

public static final boolean
ASSERT

The build tool may be configured to alter this source file to reset the static final variables so that assertion and debug checks can be compiled out of the code.

public static final boolean
DEBUG

public static final String
DEBUGDEBUG

private static Hashtable<String, Boolean>
DebugFlags

DebugFlags holds the values of all debug flags in the configuration file.

private static PrintWriter
debugStream

debugStream holds a pointer to the debug stream for writing out debug messages.

Constructor Summary

AccessConstructor and Description
public
SanityManager()

Method Summary

Modifier and TypeMethod and Description
public static final void
ASSERT(boolean
A boolean expression which must evaluate to true
mustBeTrue)

ASSERT checks the condition, and if it is false, throws AssertFailure.

public static final void
ASSERT(boolean
An expression which must evaluate to true
mustBeTrue, String
A message to emit if the expression evaluates to false
msgIfFail)

ASSERT checks the condition, and if it is false, throws AssertFailure.

public static final void
DEBUG(String
The name of a debug flag
flag, String
A message to print
message)

The DEBUG calls provide the ability to print information or perform actions based on whether a debug flag is set or not.

public static final void
DEBUG_ALL_OFF()

This can be used to have the SanityManager return FALSE for any DEBUG_ON check.

public static final void
DEBUG_ALL_ON()

This can be used to have the SanityManager return TRUE for any DEBUG_ON check.

public static final void
DEBUG_CLEAR(String
The name of the debug flag to set to false
flag)

Set the named debug flag to false.

public static final boolean

Returns:

true if the flag has been set to "true"; false if the flag is not set, or is set to something other than "true".
DEBUG_ON(String
The name of a debug flag
flag)

This can be called directly if you want to control what is done once the debug flag has been verified -- for example, if you are calling a routine that prints to the trace stream directly rather than returning a string to be printed, or if you want to perform more (or fewer!)

Calls to this method should be surrounded with if (SanityManager.DEBUG) { } so that they can be compiled out completely.

public static void
DEBUG_PRINT(String
The name of a debug flag
flag, String
A message to print
message)

The DEBUG_PRINT calls provides a convenient way to print debug information to the db2j.LOG file, The message includes a header

DEBUG $flag OUTPUT: before the message

If the debugStream stream cannot be found, the message is printed to System.out.

public static final void
DEBUG_SET(String
The name of the debug flag to set to true
flag)

Set the named debug flag to true.

public static PrintWriter
GET_DEBUG_STREAM()

public static void
NOTREACHED()

public static void
SET_DEBUG_STREAM(PrintWriter pw)

private static void
showTrace(AssertFailure af)

public static void
showTrace(Throwable t)

public static final void
THROWASSERT(String
message to print with the assertion
msgIfFail)

THROWASSERT throws AssertFailure.

public static final void
THROWASSERT(String
message to print with the assertion
msg, Throwable
exception to print with the assertion
t)

THROWASSERT throws AssertFailure.

public static final void
THROWASSERT(Throwable
exception to print with the assertion
t)

THROWASSERT throws AssertFailure.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

AllDebugOffback to summary
private static boolean AllDebugOff
AllDebugOnback to summary
private static boolean AllDebugOn

AllDebugOn and AllDebugOff override individual flags

ASSERTback to summary
public static final boolean ASSERT

The build tool may be configured to alter this source file to reset the static final variables so that assertion and debug checks can be compiled out of the code.

DEBUGback to summary
public static final boolean DEBUG
DEBUGDEBUGback to summary
public static final String DEBUGDEBUG
DebugFlagsback to summary
private static Hashtable<String, Boolean> DebugFlags

DebugFlags holds the values of all debug flags in the configuration file.

debugStreamback to summary
private static PrintWriter debugStream

debugStream holds a pointer to the debug stream for writing out debug messages. It is cached at the first debug write request.

Constructor Detail

SanityManagerback to summary
public SanityManager()

Method Detail

ASSERTback to summary
public static final void ASSERT(boolean mustBeTrue)

ASSERT checks the condition, and if it is false, throws AssertFailure. A message about the assertion failing is printed.

Parameters
mustBeTrue:boolean

A boolean expression which must evaluate to true

See Also
org.apache.derby.shared.common.sanity.AssertFailure
ASSERTback to summary
public static final void ASSERT(boolean mustBeTrue, String msgIfFail)

ASSERT checks the condition, and if it is false, throws AssertFailure. The message will be printed and included in the assertion.

Parameters
mustBeTrue:boolean

An expression which must evaluate to true

msgIfFail:String

A message to emit if the expression evaluates to false

See Also
org.apache.derby.shared.common.sanity.AssertFailure
DEBUGback to summary
public static final void DEBUG(String flag, String message)

The DEBUG calls provide the ability to print information or perform actions based on whether a debug flag is set or not. debug flags are set in configurations and picked up by the sanity manager when the monitor finds them (see CONFIG below).

The message is output to the trace stream, so it ends up in db2j.LOG. It will include a header line of DEBUG $flagname OUTPUT: before the message.

If the debugStream stream cannot be found, the message is printed to System.out.

Parameters
flag:String

The name of a debug flag

message:String

A message to print

DEBUG_ALL_OFFback to summary
public static final void DEBUG_ALL_OFF()

This can be used to have the SanityManager return FALSE for any DEBUG_ON check. DEBUG_SET of an individual flag will appear to have no effect.

DEBUG_ALL_ONback to summary
public static final void DEBUG_ALL_ON()

This can be used to have the SanityManager return TRUE for any DEBUG_ON check. DEBUG_CLEAR of an individual flag will appear to have no effect.

DEBUG_CLEARback to summary
public static final void DEBUG_CLEAR(String flag)

Set the named debug flag to false.

Calls to this method should be surrounded with if (SanityManager.DEBUG) { } so that they can be compiled out completely.

Parameters
flag:String

The name of the debug flag to set to false

DEBUG_ONback to summary
public static final boolean DEBUG_ON(String flag)

This can be called directly if you want to control what is done once the debug flag has been verified -- for example, if you are calling a routine that prints to the trace stream directly rather than returning a string to be printed, or if you want to perform more (or fewer!)

Calls to this method should be surrounded with if (SanityManager.DEBUG) { } so that they can be compiled out completely.

Parameters
flag:String

The name of a debug flag

Returns:boolean

true if the flag has been set to "true"; false if the flag is not set, or is set to something other than "true".

DEBUG_PRINTback to summary
public static void DEBUG_PRINT(String flag, String message)

The DEBUG_PRINT calls provides a convenient way to print debug information to the db2j.LOG file, The message includes a header

DEBUG $flag OUTPUT: before the message

If the debugStream stream cannot be found, the message is printed to System.out.

Parameters
flag:String

The name of a debug flag

message:String

A message to print

DEBUG_SETback to summary
public static final void DEBUG_SET(String flag)

Set the named debug flag to true.

Calls to this method should be surrounded with if (SanityManager.DEBUG) { } so that they can be compiled out completely.

Parameters
flag:String

The name of the debug flag to set to true

GET_DEBUG_STREAMback to summary
public static PrintWriter GET_DEBUG_STREAM()
NOTREACHEDback to summary
public static void NOTREACHED()
SET_DEBUG_STREAMback to summary
public static void SET_DEBUG_STREAM(PrintWriter pw)
showTraceback to summary
private static void showTrace(AssertFailure af)
showTraceback to summary
public static void showTrace(Throwable t)
THROWASSERTback to summary
public static final void THROWASSERT(String msgIfFail)

THROWASSERT throws AssertFailure. This is used in cases where the caller has already detected the assertion failure (such as in the default case of a switch). This method should be used, rather than throwing AssertFailure directly, to allow us to centralize all sanity checking. The message argument will be printed and included in the assertion.

Parameters
msgIfFail:String

message to print with the assertion

See Also
org.apache.derby.shared.common.sanity.AssertFailure
THROWASSERTback to summary
public static final void THROWASSERT(String msg, Throwable t)

THROWASSERT throws AssertFailure. This flavor will print the stack associated with the exception. The message argument will be printed and included in the assertion.

Parameters
msg:String

message to print with the assertion

t:Throwable

exception to print with the assertion

See Also
org.apache.derby.shared.common.sanity.AssertFailure
THROWASSERTback to summary
public static final void THROWASSERT(Throwable t)

THROWASSERT throws AssertFailure. This flavor will print the stack associated with the exception.

Parameters
t:Throwable

exception to print with the assertion

See Also
org.apache.derby.shared.common.sanity.AssertFailure