Package com.sun.identity.saml2.idpdiscovery

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

    • 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

    • 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