Interface DebugTrace


  • public interface DebugTrace
    A DebugTrace is used to record debug trace statements, based on the current option settings in a corresponding DebugOptions class. The trace implementation will automatically insert additional contextual information such as the bundle, class, and method performing the tracing.

    Trace statements may be written to a file, or onto standard output, depending on how the DebugOptions is configured (See DebugOptions.setFile(java.io.File)).

    All methods on this class have an optional option argument. When specified, this argument will cause the tracing to be conditional on the value of DebugOptions.getBooleanOption(String, boolean), where the bundle's symbolic name will automatically be prepended to the provided option string. For example, if your bundle symbolic name is "com.acme.bundle", and you provide an option argument of "/debug/parser", the trace will only be printed if the option "com.acme.bundle/debug/parser" has a value of "true".

    Note that the pipe character ("|") is reserved for internal use. If this character happens to occur in any of the thread name, the option, the message or an Exception message, it will be escaped to the corresponding HTML representation ("|").

    Since:
    3.5
    Restriction:
    This interface is not intended to be implemented by clients.
    Restriction:
    This interface is not intended to be extended by clients.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void trace​(String option, String message)
      Traces a message for the specified option.
      void trace​(String option, String message, Throwable error)
      Traces a message and exception for the specified option.
      void traceDumpStack​(String option)
      Adds a trace message showing a thread stack dump for the current class and method being executed for the specified option.
      void traceEntry​(String option)
      Add a trace message level stating that a method is being executed for the specified option.
      void traceEntry​(String option, Object methodArgument)
      Add a trace message level stating that a method with the specified argument values is being executed for the specified option.
      void traceEntry​(String option, Object[] methodArguments)
      Add a trace message level stating that a method with the specified arguments values is being executed for the specified option.
      void traceExit​(String option)
      Add a trace message level stating that a method has completed execution for the specified option.
      void traceExit​(String option, Object result)
      Add a trace message level stating that a method with the specified result value has completed execution for the specified option.
    • Method Detail

      • trace

        void trace​(String option,
                   String message)
        Traces a message for the specified option.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
        message - The trace message to display
      • trace

        void trace​(String option,
                   String message,
                   Throwable error)
        Traces a message and exception for the specified option.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
        message - The trace message to display
        error - The exception to trace
      • traceDumpStack

        void traceDumpStack​(String option)
        Adds a trace message showing a thread stack dump for the current class and method being executed for the specified option.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
      • traceEntry

        void traceEntry​(String option)
        Add a trace message level stating that a method is being executed for the specified option.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
      • traceEntry

        void traceEntry​(String option,
                        Object methodArgument)
        Add a trace message level stating that a method with the specified argument values is being executed for the specified option. The result of String.valueOf(Object) on the methodArgument will be written to the trace file.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
        methodArgument - The single argument for the method being executed
      • traceEntry

        void traceEntry​(String option,
                        Object[] methodArguments)
        Add a trace message level stating that a method with the specified arguments values is being executed for the specified option. The result of String.valueOf(Object) on each argument will be written to the trace file.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
        methodArguments - A list of object arguments for the method being executed
      • traceExit

        void traceExit​(String option)
        Add a trace message level stating that a method has completed execution for the specified option.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
      • traceExit

        void traceExit​(String option,
                       Object result)
        Add a trace message level stating that a method with the specified result value has completed execution for the specified option. The result of String.valueOf(Object) on the result object will be written to the trace file.
        Parameters:
        option - The name of the boolean option that will control whether the trace statement is printed (e.g., "/debug/myComponent"), or null
        result - The result being returned from the method that was executed