com.iplanet.portalserver.util
Class Debug

java.lang.Object
  |
  +--com.iplanet.portalserver.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 files are created in the directory specified by the property, ips.debug.dir, in /etc/opt/SUNWips/platform.conf file. The default value for this property is /var/opt/SUNWips/debug.

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.

Constructor Summary

Debug(java.lang.String debugName)
This constructor takes as an argument the name of the debug file.

Method Summary

boolean	debugEnabled() Checks if message debugging is enabled.
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:
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() Enables or disables degbugging based on the value of debug attribute, ips.debug, in the platform config file, /etc/opt/SUNWips/platform.conf.
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.

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.

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.

MESSAGE

public static final int MESSAGE

This state enables debugging of messages, warnings and errors.

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.

Constructor Detail

Debug

public Debug(java.lang.String debugName)

This constructor takes as an argument the name of the debug file. The debug file is neither created nor opened until the first time message(), warning() or error() is invoked and the debug state is neither OFF nor ON.

NOTE:The recommended and preferred method to create Debug objects is getInstance(String). This constructor may be deprecated in future.

Parameters:

debugFileName - name of the debug file to create or use

See Also:

getInstance(java.lang.String)

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.

debugEnabled

public boolean debugEnabled()

Checks if message debugging is enabled.

NOTE: It is recommended that messageEnabled() be used instead of debugEnabled() as the former is more intuitive.

Returns:

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

See Also:

messageEnabled()

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

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. 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.

See Also:

message(String msg, Throwable t)

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 timestamp 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 msg, Throwable t)

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. 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.

See Also:

warning(String msg, Throwable t)

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 debuging is enabled, the message along with a timestamp 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.

See Also:

error(String msg, Throwable t)

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 timestamp 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()

Enables or disables degbugging based on the value of debug attribute, ips.debug, in the platform config file, /etc/opt/SUNWips/platform.conf. If the attribute is not defined, debugging is disabled by default.

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.