Package com.sun.identity.shared.debug

Class Debug

java.lang.Object
com.sun.identity.shared.debug.Debug
@SupportedAll @Deprecated public class Debug extends Object
Deprecated.
Use Logger instead.
****************************************************************************

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.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ERROR
    Deprecated.
    flags the state where error debugging is enabled.
    static final int
    MESSAGE
    Deprecated.
    This state enables debugging of messages, warnings and errors.
    static final int
    OFF
    Deprecated.
    flags the disabled debug state.
    static final int
    ON
    Deprecated.
    flags the enabled debug state for warnings, errors and messages.
    static final String
    STR_ERROR
    Deprecated.
    flags the state where error debugging is enabled.
    static final String
    STR_MESSAGE
    Deprecated.
    This state enables debugging of messages, warnings and errors.
    static final String
    STR_OFF
    Deprecated.
    flags the disabled debug state.
    static final String
    STR_ON
    Deprecated.
    flags the enables debug state for warnings, errors and messages.
    static final String
    STR_WARNING
    Deprecated.
    flags the state where warning debugging is enabled, but message debugging is disabled.
    static final int
    WARNING
    Deprecated.
    flags the state where warning debugging is enabled, but message debugging is disabled.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    error(String msg)
    Deprecated.
    Prints error messages only when debug level is greater than DEBUG.OFF.
    void
    error(String msg, Object... params)
    Deprecated.
    A convenience method for error debug statements.
    void
    error(String msg, Throwable t)
    Deprecated.
    Prints error messages only if debug state is greater than Debug.OFF.
    boolean
    errorEnabled()
    Deprecated.
    Checks if error debugging is enabled.
    static Debug
    getInstance(String debugName)
    Deprecated.
    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()
    Deprecated.
    Returns a collection of all Debug instances that exist in the system at the current instance.
    String
    getName()
    Deprecated.
    Convinience method to query the name being used for this Debug instance.
    int
    getState()
    Deprecated.
    Returns one of the five possible values: Debug.OFF Debug.ERROR Debug.WARNING Debug.MESSAGE Debug.ON
    void
    message(String msg)
    Deprecated.
    Prints messages only when the debug state is either Debug.MESSAGE or Debug.ON.
    void
    message(String msg, Object... params)
    Deprecated.
    A convenience method for message debug statements.
    void
    message(String msg, Throwable t)
    Deprecated.
    Prints debug and exception messages only when the debug state is either Debug.MESSAGE or Debug.ON.
    boolean
    messageEnabled()
    Deprecated.
    Checks if message debugging is enabled.
    void
    resetDebug(String mf)
    Deprecated.
    Allows runtime modification of the backend used by this instance.
    void
    setDebug(int debugType)
    Deprecated.
    Sets the debug capabilities based on the values of the debugType argument.
    void
    setDebug(String debugType)
    Deprecated.
    Sets the debug capabilities based on the values of the debugType argument.
    void
    warning(String msg)
    Deprecated.
    Prints warning messages only when debug level is greater than Debug.ERROR.
    void
    warning(String msg, Object... params)
    Deprecated.
    A convenience method for warning debug statements.
    void
    warning(String msg, Throwable t)
    Deprecated.
    Prints warning messages only when debug level is greater than Debug.ERROR.
    boolean
    warningEnabled()
    Deprecated.
    Checks if warning debugging is enabled.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • OFF

      public static final int OFF
      Deprecated.
      flags the disabled debug state.
      See Also:

    • ERROR

      public static final int ERROR
      Deprecated.
      flags the state where error debugging is enabled. When debugging is set to less than ERROR, error debugging is also disabled.
      See Also:

    • WARNING

      public static final int WARNING
      Deprecated.
      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:

    • MESSAGE

      public static final int MESSAGE
      Deprecated.
      This state enables debugging of messages, warnings and errors.
      See Also:

    • ON

      public static final int ON
      Deprecated.
      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:

    • STR_OFF

      public static final String STR_OFF
      Deprecated.
      flags the disabled debug state.
      See Also:

    • STR_ERROR

      public static final String STR_ERROR
      Deprecated.
      flags the state where error debugging is enabled. When debugging is set to less than ERROR, error debugging is also disabled.
      See Also:

    • STR_WARNING

      public static final String STR_WARNING
      Deprecated.
      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:

    • STR_MESSAGE

      public static final String STR_MESSAGE
      Deprecated.
      This state enables debugging of messages, warnings and errors.
      See Also:

    • STR_ON

      public static final String STR_ON
      Deprecated.
      flags the enables debug state for warnings, errors and messages. Printing to a file is disabled. All printing is done on System.out.
      See Also:

  • Method Details

    • getInstance

      public static Debug getInstance(String debugName)
      Deprecated.
      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 setDebug(int) or 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()
      Deprecated.
      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()
      Deprecated.
      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()
      Deprecated.

      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()
      Deprecated.

      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()
      Deprecated.

      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()
      Deprecated.
      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)
      Deprecated.

      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

      public void message(String msg, Throwable t)
      Deprecated.

      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:

    • message

      public void message(String msg, Object... params)
      Deprecated.

      A convenience method for message debug statements. The message will only be formatted if the debug level is greater than 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 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)
      Deprecated.

      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

      public void warning(String msg, Throwable t)
      Deprecated.

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

      A convenience method for warning debug statements. The message will only be formatted if the debug level is greater than 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 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)
      Deprecated.
      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

      public void error(String msg, Throwable t)
      Deprecated.

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

      A convenience method for error debug statements. The message will only be formatted if the debug level is greater than 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 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)
      Deprecated.
      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)
      Deprecated.
      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)
      Deprecated.
      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