com.sun.identity.saml2.idpdiscovery

Class Debug

java.lang.Object

com.sun.identity.saml2.idpdiscovery.Debug

public class Debug
extends 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, DebugConfig.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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
Debug(String debugName) Deprecated. Use getInstance(java.lang.String)

Method Summary

Modifier and Type	Method and Description
boolean	debugEnabled() Deprecated. Use messageEnabled()
void	destroy() Destroys the debug object, closes the debug file and releases any system resources.
void	error(String msg) Prints error messages only when debug level is greater than DEBUG.OFF.
void	error(String msg, Throwable t) Prints error messages only if debug state is greater than Debug.OFF.
protected void	finalize() Flushes and then closes the debug file.
static Debug	getInstance(String debugName) Returns 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(String msg) Prints messages only when the debug state is either DEBUG.MESSAGE or Debug.ON.
void	message(String msg, 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() Deprecated. Use getInstance(java.lang.String). getInstance(java.lang.String) will automatically set the debug level based on the information in DebugConfig.properties file.
void	setDebug(int debugType) Sets the debug capabilities based on the values of the debugType argument.
void	setDebug(String debugType) Sets the debug capabilities based on the values of the debugType argument.
void	warning(String msg) Prints warning messages only when debug level is greater than DEBUG.ERROR.
void	warning(String msg, 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

clone, 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

Constructor Detail

Debug

public Debug(String debugName)

Deprecated. Use getInstance(java.lang.String)

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:

debugName - name of the debug file to create or use

Method Detail

getInstance

public static Debug getInstance(String debugName)

Returns 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 DebugConfig.properties file. The level can be changed later by using setDebug(int) or setDebug(String)

Parameters:

debugName - name of debug instance.

Returns:

an instance of Debug.

debugEnabled

public boolean debugEnabled()

Deprecated. Use messageEnabled()

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

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:

debug state.

message

public void message(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 - 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:

message(String msg, Throwable t)

message

public void message(String msg,
                    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 msg, Throwable t)

warning

public void warning(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 msg, Throwable t)

warning

public void warning(String msg,
                    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(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 msg, Throwable t)

error

public void error(String msg,
                  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()

Deprecated. Use getInstance(java.lang.String). getInstance(java.lang.String) will automatically set the debug level based on the information in DebugConfig.properties file.

Enables or disables debugging based on the value of debug attribute, com.iplanet.services.debug.level, in the DebugConfig.properties file. DebugConfig.properties file should be accessible from CLASSPATH. If the property is not defined, debug level is set to error.

setDebug

public void setDebug(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.

finalize

protected void finalize()

Flushes and then closes the debug file.

Overrides:

finalize in class Object