Debug (OpenAM Server Only 6.5.5 Documentation)

java.lang.Object
- com.sun.identity.shared.debug.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, 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 'com.iplanet.services.debug.level' are: off | error | warning | message. The key 'com.iplanet.services.debug.directory' specifies the output directory where the debug files will be created. Optionally, the key 'com.sun.identity.util.debug.provider' may be used to plugin a non-default implementation of the debug service where necessary.
```
  com.iplanet.services.debug.level
  com.iplanet.services.debug.directory
  com.sun.identity.util.debug.provider
 
```
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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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, Object... params)` A convenience method for error debug statements.
`void`	`error(String msg, Throwable t)` Prints error messages only if debug state is greater than Debug.OFF.
`boolean`	`errorEnabled()` Checks if error debugging is enabled.
`static Debug`	`getInstance(String debugName)` Gets an existing instance of Debug for the specified debug name or a new one if no such instance already exists.
`static Collection<Debug>`	`getInstances()` Returns a collection of all Debug instances that exist in the system at the current instance.
`String`	`getName()` Convinience method to query the name being used for this Debug instance.
`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, Object... params)` A convenience method for message debug statements.
`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`	`resetDebug(String mf)` Allows runtime modification of the backend used by this instance.
`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, Object... params)` A convenience method for warning debug statements.
`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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getInstance
```
public static Debug getInstance(String debugName)
```
    Gets an existing instance of Debug for the specified debug name 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 Debug.setDebug(int) or Debug.setDebug(String) methods.
    
    Parameters:
    
    debugName - name of the debug instances to be created
    
    Returns:
    
    a Debug instance corresponding to the specified debug name.
  - getInstances
```
public static Collection<Debug> getInstances()
```
    Returns a collection of all Debug instances that exist in the system at the current instance. This is a live collection that will be updated as and when new Debug instances are created. Note that if an iterator is used, it could potentially cause a ConcurrentModificationException if during the process of iteration, the collection is modified by the system.
    
    Returns:
    
    a collection of all Debug instances in the system.
  - getName
```
public String getName()
```
    Convinience method to query the name being used for this Debug instance. The return value of this method is a string exactly equal to the name that was used while creating this instance.
    
    Returns:
    
    the name of this Debug instance
  - 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
  - errorEnabled
```
public boolean errorEnabled()
```
    Checks if error debugging is enabled.
    
    NOTE: Debugging is an IO intensive operation and may hurt application performance when abused. Particularly, note that Java evaluates arguments to error() even when error debugging is turned off. It is recommended that errorEnabled() be called to check the debug state before invoking any error() methods to avoid unnecessary argument evaluation and maximize application performance.
    
    Returns:
    
    true if error debugging is enabled false if error 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(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:
    
    Debug.message(String, Throwable)
  - 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:
    
    Debug.error(String, Throwable)
  - message
```
public void message(String msg,
                    Object... params)
```
    A convenience method for message debug statements. The message will only be formatted if the debug level is greater than Debug.WARNING, and then it will be formatted using the MessageFormatter class. The relevant message method is then called depending on whether the last parameter is an instance of Throwable.
    
    This method is convenient way of issuing warning level debug statements without having to guard the call with a check to Debug.messageEnabled(), as that check is done before evaluating the method parameters.
    
    For this optimisation to work properly, this method should not be called using string concatenation. If concatenation is required, it can be achieved using format patterns.
    
    In this way, the only cost to execution is the assembly of the varargs parameter.
    
    Parameters:
    
    msg - The debug message format, using MessageFormatter style format patterns.
    
    params - The parameters to the message, optionally with a Throwable as the last parameter.
  - 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:
    
    Debug.warning(String, Throwable)
  - 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.
  - warning
```
public void warning(String msg,
                    Object... params)
```
    A convenience method for warning debug statements. The message will only be formatted if the debug level is greater than Debug.ERROR, and then it will be formatted using the MessageFormatter class. The relevant warning method is then called depending on whether the last parameter is an instance of Throwable.
    
    This method is convenient way of issuing warning level debug statements without having to guard the call with a check to Debug.warningEnabled(), as that check is done before evaluating the method parameters.
    
    For this optimisation to work properly, this method should not be called using string concatenation. If concatenation is required, it can be achieved using format patterns.
    
    In this way, the only cost to execution is the assembly of the varargs parameter.
    
    Parameters:
    
    msg - The debug message format, using MessageFormatter style format patterns.
    
    params - The parameters to the message, optionally with a Throwable as the last parameter.
  - 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:
    
    Debug.error(String, Throwable)
  - 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.
  - error
```
public void error(String msg,
                  Object... params)
```
    A convenience method for error debug statements. The message will only be formatted if the debug level is greater than Debug.OFF, and then it will be formatted using the MessageFormatter class. The relevant error method is then called depending on whether the last parameter is an instance of Throwable.
    
    This method is convenient way of issuing warning level debug statements without having to guard the call with a check to Debug.errorEnabled(), as that check is done before evaluating the method parameters.
    
    For this optimisation to work properly, this method should not be called using string concatenation. If concatenation is required, it can be achieved using format patterns.
    
    In this way, the only cost to execution is the assembly of the varargs parameter.
    
    Parameters:
    
    msg - The debug message format, using MessageFormatter style format patterns.
    
    params - The parameters to the message, optionally with a Throwable as the last parameter.
  - 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
  - resetDebug
```
public void resetDebug(String mf)
```
    Allows runtime modification of the backend used by this instance. by resetting the debug instance to reinitialize itself.
    
    Parameters:
    
    mf - merge flag - on for creating a single debug file.
  - 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:
    
    Debug.STR_OFF
    
    Debug.STR_ERROR
    
    Debug.STR_WARNING
    
    Debug.STR_MESSAGE
    
    Debug.STR_ON
  - 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.

Class Debug

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getInstances

getName

messageEnabled

warningEnabled

errorEnabled

getState

message

message

message

warning

warning

warning

error

error

error

setDebug

resetDebug

setDebug

destroy