com.iplanet.am.util
Class Debug

java.lang.Object
  com.iplanet.am.util.Debug

public class Debug

extends java.lang.Object

Allows a uniform interface to file debug and exception information in a uniform format. Debug supports different levels/states of filing debug information (in the ascending order): OFF, ERROR, WARNING, MESSAGE and ON. A given debug level/state is enabled if the debug state/level is set to at least that state/level. For example, if the debug state is ERROR, only errors will be filed. If the debug state is WARNING, only errors and warnings will be filed. If the debug state is MESSAGE, everything will be filed. MESSAGE and ON are of the same levels; the difference between them being MESSAGE writes to a file, whereas ON writes to System.out.

Debug service uses the property file, AMConfig.properties, to set the default debug level and the output directory where the debug files will be placed. The properties file is located (using ResourceBundle semantics) from one of the directories in the CLASSPATH.

The following keys are used to configure the Debug service. Possible values for the key 'level' are: off | error | warning | message The key 'directory' specifies the output directory where the debug files will be created.

com.iplanet.services.debug.level
com.iplanet.services.debug.directory

If there is an error reading or loading the properties, debug service will redirect all debug information to System.out If these properties are changed, the server must be restarted for the changes to take effect.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates the arguments to message() and warning() even when debugging is turned off. It is recommended that the debug state be checked before invoking any message() or warning() methods to avoid unnecessary argument evaluation and to maximize application performance.

Field Summary

static int	ERROR flags the state where error debugging is enabled.
static int	MESSAGE This state enables debugging of messages, warnings and errors.
static int	OFF flags the disabled debug state.
static int	ON flags the enabled debug state for warnings, errors and messages.
static int	WARNING flags the state where warning debugging is enabled, but message debugging is disabled.

Method Summary

void	destroy() Destroys the debug object, closes the debug file and releases any system resources.
void	error(java.lang.String msg) Prints error messages only when debug level is greater than DEBUG.OFF.
void	error(java.lang.String msg, java.lang.Throwable t) Prints error messages only if debug state is greater than Debug.OFF.
static Debug	getInstance(java.lang.String debugName) Gets an existing instance of Debug for the specified debug file or a new one if no such instance already exists.
int	getState() Returns one of the five possible values: Debug.OFF Debug.ERROR Debug.WARNING Debug.MESSAGE Debug.ON
void	message(java.lang.String msg) Prints messages only when the debug state is either DEBUG.MESSAGE or Debug.ON.
void	message(java.lang.String msg, java.lang.Throwable t) Prints debug and exception messages only when the debug state is either DEBUG.MESSAGE or Debug.ON.
boolean	messageEnabled() Checks if message debugging is enabled.
void	setDebug(int debugType) Sets the debug capabilities based on the values of the debugType argument.
void	setDebug(java.lang.String debugType) Sets the debug capabilities based on the values of the debugType argument.
void	warning(java.lang.String msg) Prints warning messages only when debug level is greater than DEBUG.ERROR.
void	warning(java.lang.String msg, java.lang.Throwable t) Prints warning messages only when debug level is greater than DEBUG.ERROR.
boolean	warningEnabled() Checks if warning debugging is enabled.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OFF

public static final int OFF

flags the disabled debug state.

See Also:

Constant Field Values

ERROR

public static final int ERROR

flags the state where error debugging is enabled. When debugging is set to less than ERROR, error debugging is also disabled.

See Also:

Constant Field Values

WARNING

public static final int WARNING

flags the state where warning debugging is enabled, but message debugging is disabled. When debugging is set to less than WARNING, warning debugging is also disabled.

See Also:

Constant Field Values

MESSAGE

public static final int MESSAGE

This state enables debugging of messages, warnings and errors.

See Also:

Constant Field Values

ON

public static final int ON

flags the enabled debug state for warnings, errors and messages. Printing to a file is disabled. All printing is done on System.out.

See Also:

Constant Field Values

Method Detail

getInstance

public static Debug getInstance(java.lang.String debugName)

Gets an existing instance of Debug for the specified debug file or a new one if no such instance already exists. If a Debug object has to be created, its level is set to the level defined in the AMConfig.properties file. The level can be changed later by using setDebug(int) or setDebug(String)

Parameters:

debugName - the name of the debug file to create or use

Returns:

a debug instance corresponding to the specified debug file

messageEnabled

public boolean messageEnabled()

Checks if message debugging is enabled.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to message() even when debugging is turned off. It is recommended that messageEnabled() be called to check the debug state before invoking any message() methods to avoid unnecessary argument evaluation and maximize application performance.

Returns:

true if message debugging is enabled false if message debugging is disabled

warningEnabled

public boolean warningEnabled()

Checks if warning debugging is enabled.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to warning() even when warning debugging is turned off. It is recommended that warningEnabled() be called to check the debug state before invoking any warning() methods to avoid unnecessary argument evaluation and maximize application performance.

Returns:

true if warning debugging is enabled false if warning debugging is disabled

getState

public int getState()

Returns one of the five possible values:

• Debug.OFF
• Debug.ERROR
• Debug.WARNING
• Debug.MESSAGE
• Debug.ON

Returns:

the debug level

message

public void message(java.lang.String msg)

Prints messages only when the debug state is either DEBUG.MESSAGE or Debug.ON.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to message() even when debugging is turned off. So when the argument to this method involves the String concatenation operator '+' or any other method invocation, messageEnabled MUST be used. It is recommended that the debug state be checked by invoking messageEnabled() before invoking any message() methods to avoid unnecessary argument evaluation and maximize application performance.

Parameters:

msg - debug message.

See Also:

message(String, Throwable)

message

public void message(java.lang.String msg,
                    java.lang.Throwable t)

Prints debug and exception messages only when the debug state is either DEBUG.MESSAGE or Debug.ON. If the debug file is not accessible and debugging is enabled, the message along with a time stamp and thread info will be printed on System.out.

This method creates the debug file if does not exist; otherwise it starts appending to the existing debug file. When invoked for the first time on this object, the method writes a line delimiter of '*'s.

Note that the debug file will remain open until destroy() is invoked. To conserve file resources, you should invoke destroy() explicitly rather than wait for the garbage collector to clean up.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to message() even when debugging is turned off. It is recommended that the debug state be checked by invoking messageEnabled() before invoking any message() methods to avoid unnecessary argument evaluation and to maximize application performance.

Parameters:

msg - message to be printed. A newline will be appended to the message before printing either to System.out or to the debug file. If msg is null, it is ignored.

t - Throwable, on which printStackTrace will be invoked to print the stack trace. If t is null, it is ignored.

See Also:

error(String, Throwable)

warning

public void warning(java.lang.String msg)

Prints warning messages only when debug level is greater than DEBUG.ERROR.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to warning() even when debugging is turned off. So when the argument to this method involves the String concatenation operator '+' or any other method invocation, warningEnabled MUST be used. It is recommended that the debug state be checked by invoking warningEnabled() before invoking any warning() methods to avoid unnecessary argument evaluation and to maximize application performance.

Parameters:

msg - message to be printed. A newline will be appended to the message before printing either to System.out or to the debug file. If msg is null, it is ignored.

See Also:

warning(String, Throwable)

warning

public void warning(java.lang.String msg,
                    java.lang.Throwable t)

Prints warning messages only when debug level is greater than DEBUG.ERROR.

NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to warning() even when debugging is turned off. It is recommended that the debug state be checked by invoking warningEnabled() before invoking any warning() methods to avoid unnecessary argument evaluation and to maximize application performance.

If the debug file is not accessible and debugging is enabled, the message along with a time stamp and thread info will be printed on System.out.

This method creates the debug file if does not exist; otherwise it starts appending to the existing debug file. When invoked for the first time on this object, the method writes a line delimiter of '*'s.

Note that the debug file will remain open until destroy() is invoked. To conserve file resources, you should invoke destroy() explicitly rather than wait for the garbage collector to clean up.

Parameters:

msg - message to be printed. A newline will be appended to the message before printing either to System.out or to the debug file. If msg is null, it is ignored.

t - Throwable, on which printStackTrace() will be invoked to print the stack trace. If t is null, it is ignored.

error

public void error(java.lang.String msg)

Prints error messages only when debug level is greater than DEBUG.OFF.

Parameters:

msg - message to be printed. A newline will be appended to the message before printing either to System.out or to the debug file. If msg is null, it is ignored.

See Also:

error(String, Throwable)

error

public void error(java.lang.String msg,
                  java.lang.Throwable t)

Prints error messages only if debug state is greater than Debug.OFF. If the debug file is not accessible and debugging is enabled, the message along with a time stamp and thread info will be printed on System.out.

This method creates the debug file if does not exist; otherwise it starts appending to the existing debug file. When invoked for the first time on this object, the method writes a line delimiter of '*'s.

Note that the debug file will remain open until destroy() is invoked. To conserve file resources, you should invoke destroy() explicitly rather than wait for the garbage collector to clean up.

Parameters:

msg - message to be printed. A newline will be appended to the message before printing either to System.out or to the debug file. If msg is null, it is ignored.

t - Throwable, on which printStackTrace() will be invoked to print the stack trace. If t is null, it is ignored.

setDebug

public void setDebug(int debugType)

Sets the debug capabilities based on the values of the debugType argument.

Parameters:

debugType - is any one of five possible values:

• Debug.OFF
• Debug.ERROR
• Debug.WARNING
• Debug.MESSAGE
• Debug.ON

setDebug

public void setDebug(java.lang.String debugType)

Sets the debug capabilities based on the values of the debugType argument.

Parameters:

debugType - is any one of the following possible values:

off - debugging is disabled

on - all debugging is enabled and written to System.out

message - message debugging is enabled and written to the debug file

warning - warning debugging is enabled and written to the debug

file

error - error debugging is enabled and written to the debug

file

destroy

public void destroy()

Destroys the debug object, closes the debug file and releases any system resources. Note that the debug file will remain open until destroy() is invoked. To conserve file resources, you should invoke destroy() explicitly rather than wait for the garbage collector to clean up.

If this object is accessed after destroy() has been invoked, the results are undefined.