org.apache.derby.iapi.services.sanity
Class SanityManager

java.lang.Object
  extended byorg.apache.derby.iapi.services.sanity.SanityManager

public class SanityManager
extends java.lang.Object

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:
AssertFailure

Field Summary
private static boolean AllDebugOff
           
private static boolean AllDebugOn
          AllDebugOn and AllDebugOff override individual flags
static 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.
static boolean DEBUG
           
static java.lang.String DEBUGDEBUG
           
private static java.util.Hashtable DebugFlags
          DebugFlags holds the values of all debug flags in the configuration file.
private static java.io.PrintWriter debugStream
          debugStream holds a pointer to the debug stream for writing out debug messages.
 
Constructor Summary
SanityManager()
           
 
Method Summary
static void ASSERT(boolean mustBeTrue)
          ASSERT checks the condition, and if it is false, throws AssertFailure.
static void ASSERT(boolean mustBeTrue, java.lang.String msgIfFail)
          ASSERT checks the condition, and if it is false, throws AssertFailure.
static void DEBUG_ALL_OFF()
          This can be used to have the SanityManager return FALSE for any DEBUG_ON check.
static void DEBUG_ALL_ON()
          This can be used to have the SanityManager return TRUE for any DEBUG_ON check.
static void DEBUG_CLEAR(java.lang.String flag)
          Set the named debug flag to false.
static boolean DEBUG_ON(java.lang.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!)
static void DEBUG_PRINT(java.lang.String flag, java.lang.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 OUTPUT: before the message If the debugStream stream cannot be found, the message is printed to System.out.
static void DEBUG_SET(java.lang.String flag)
          Set the named debug flag to true.
static void DEBUG(java.lang.String flag, java.lang.String message)
          The DEBUG calls provide the ability to print information or perform actions based on whether a debug flag is set or not.
static java.io.PrintWriter GET_DEBUG_STREAM()
           
static void NOTREACHED()
           
static void SET_DEBUG_STREAM(java.io.PrintWriter pw)
           
private static void showTrace(AssertFailure af)
           
static void showTrace(java.lang.Throwable t)
           
static void THROWASSERT(java.lang.String msgIfFail)
          THROWASSERT throws AssertFailure.
static void THROWASSERT(java.lang.String msg, java.lang.Throwable t)
          THROWASSERT throws AssertFailure.
static void THROWASSERT(java.lang.Throwable t)
          THROWASSERT throws AssertFailure.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ASSERT

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.

See Also:
Constant Field Values

DEBUG

public static final boolean DEBUG
See Also:
Constant Field Values

DEBUGDEBUG

public static final java.lang.String DEBUGDEBUG
See Also:
Constant Field Values

debugStream

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


DebugFlags

private static java.util.Hashtable DebugFlags
DebugFlags holds the values of all debug flags in the configuration file.


AllDebugOn

private static boolean AllDebugOn
AllDebugOn and AllDebugOff override individual flags


AllDebugOff

private static boolean AllDebugOff
Constructor Detail

SanityManager

public SanityManager()
Method Detail

ASSERT

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.

See Also:
AssertFailure

ASSERT

public static final void ASSERT(boolean mustBeTrue,
                                java.lang.String msgIfFail)
ASSERT checks the condition, and if it is false, throws AssertFailure. The message will be printed and included in the assertion.

See Also:
AssertFailure

THROWASSERT

public static final void THROWASSERT(java.lang.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 - message to print with the assertion
See Also:
AssertFailure

THROWASSERT

public static final void THROWASSERT(java.lang.String msg,
                                     java.lang.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 - message to print with the assertion
t - exception to print with the assertion
See Also:
AssertFailure

THROWASSERT

public static final void THROWASSERT(java.lang.Throwable t)
THROWASSERT throws AssertFailure. This flavor will print the stack associated with the exception.

Parameters:
t - exception to print with the assertion
See Also:
AssertFailure

DEBUG

public static final void DEBUG(java.lang.String flag,
                               java.lang.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 OUTPUT: before the message.

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


DEBUG_ON

public static final boolean DEBUG_ON(java.lang.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.

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_SET

public static final void DEBUG_SET(java.lang.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 - The name of the debug flag to set to true
Returns:
Nothing

DEBUG_CLEAR

public static final void DEBUG_CLEAR(java.lang.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 - The name of the debug flag to set to false
Returns:
Nothing

DEBUG_ALL_ON

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_ALL_OFF

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.


SET_DEBUG_STREAM

public static void SET_DEBUG_STREAM(java.io.PrintWriter pw)

GET_DEBUG_STREAM

public static java.io.PrintWriter GET_DEBUG_STREAM()

showTrace

private static void showTrace(AssertFailure af)

showTrace

public static void showTrace(java.lang.Throwable t)

DEBUG_PRINT

public static void DEBUG_PRINT(java.lang.String flag,
                               java.lang.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 OUTPUT: before the message

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


NOTREACHED

public static void NOTREACHED()

Built on Tue 2006-10-10 19:23:47+0200, from revision exported

Apache Derby V10.1 Engine Documentation - Copyright © 1997,2005 The Apache Software Foundation or its licensors, as applicable.