Package com.sun.identity.shared.debug

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

    • Field Summary

      Fields 
      Modifier and Type Field 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 String STR_ERROR
      flags the state where error debugging is enabled.
      static String STR_MESSAGE
      This state enables debugging of messages, warnings and errors.
      static String STR_OFF
      flags the disabled debug state.
      static String STR_ON
      flags the enables debug state for warnings, errors and messages.
      static String STR_WARNING
      flags the state where warning debugging is enabled, but message debugging is disabled.
      static int WARNING
      flags the state where warning debugging is enabled, but message debugging is disabled.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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 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.

    • Field Detail

      • 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

      • STR_ERROR

        public static final String STR_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

      • STR_WARNING

        public static final String STR_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

      • STR_MESSAGE

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

      • STR_ON

        public static final String STR_ON
        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:
        Constant Field Values

    • 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 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 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:
        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:
        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 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)
        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​(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 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)
        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​(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 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)
        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.