Class Debug


  • public class Debug
    extends java.lang.Object
    Miscellaneous debugging functionality such as error logging, assertion checking and exception reporting. All output produced by this class goes to debugStream which is configurable. This class is thread safe. This is JDK1.3 legacy as this functionality is now provided natively by Java 1.4.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Debug()
      This utility class not meant to be instantiated.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void Assert​(boolean check)
      Check the provided assertion.
      static void Assert​(boolean check, java.lang.String message)
      Check the provided assertion.
      static void flush()
      Make sure any messages are flushed to the stream.
      static java.io.PrintStream getDebuggingStream()
      Get the debugging stream.
      static boolean getLogExceptions()
      Determine if exception logging is enabled.
      static boolean getLogMessages()
      Determine if message logging is enabled.
      static java.lang.String p​(java.lang.String message)
      Same function as printDebuggingMessage(String) but easier to type.
      static void p​(java.lang.String location, java.lang.String message)
      Same function as printDebuggingMessage(String,String) but easier to type.
      static java.lang.String printDebuggingMessage​(java.lang.String message)
      Print the provided message to the debug log (if message logging is on).
      static void printDebuggingMessage​(java.lang.String location, java.lang.String message)
      Print the provided message to the debug log (if message logging is on).
      static void reportException​(java.lang.Throwable e)
      Report the Exception (or Throwable) to the debug log.
      static void reportException​(java.lang.Throwable e, java.lang.String message)
      Report the exception to the debug log.
      (package private) static void reportFatalException​(java.lang.Throwable e)
      Report a fatal exception to the error stream.
      static void setDebuggingStream​(java.io.PrintStream w)
      Set the debugging stream.
      static void setLogExceptions​(boolean on)
      Turn on/off the logging of reported exceptions.
      static void setLogMessages​(boolean on)
      Set whether debugging messages will be logged to the debug stream.
      static void setThreadNameOutput​(boolean on)
      Turn on/off the reporting of thread name in the debug log.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • log_messages

        private static volatile boolean log_messages
      • log_exceptions

        private static volatile boolean log_exceptions
      • output_thread_name

        private static boolean output_thread_name
      • debugStream

        private static java.io.PrintStream debugStream
      • formatter

        private static java.text.DateFormat formatter
      • now

        private static java.util.Date now
    • Constructor Detail

      • Debug

        private Debug()
        This utility class not meant to be instantiated.
    • Method Detail

      • setDebuggingStream

        public static void setDebuggingStream​(java.io.PrintStream w)
        Set the debugging stream. If no debug stream is explicitly set, then System.err is used.
        Parameters:
        w - The stream where debug output will be directed.
      • getDebuggingStream

        public static java.io.PrintStream getDebuggingStream()
        Get the debugging stream.
        Returns:
        The stream currently used for debug output.
      • setLogMessages

        public static void setLogMessages​(boolean on)
        Set whether debugging messages will be logged to the debug stream. Default is true.
        Parameters:
        on - Whether or not printed debug messages will go to the log.
      • getLogMessages

        public static boolean getLogMessages()
        Determine if message logging is enabled.
        Returns:
        true if message logging is enabled
      • setLogExceptions

        public static void setLogExceptions​(boolean on)
        Turn on/off the logging of reported exceptions. Default is on.
        Parameters:
        on - Whtehr or not reported exceptions will be directed to the log.
      • getLogExceptions

        public static boolean getLogExceptions()
        Determine if exception logging is enabled.
        Returns:
        true if message logging is enabled
      • setThreadNameOutput

        public static void setThreadNameOutput​(boolean on)
        Turn on/off the reporting of thread name in the debug log. Default is off.
        Parameters:
        on - Whether or not the thread name will appear in the output.
      • reportException

        public static void reportException​(java.lang.Throwable e,
                                           java.lang.String message)
        Report the exception to the debug log. Usually used to record exceptions that are unexpected, yet do not indicate fatal conditions (e.g. they are recoverable).
        Parameters:
        e - The exception to report.
        message - Additional information to report along with the exception.
      • reportException

        public static void reportException​(java.lang.Throwable e)
        Report the Exception (or Throwable) to the debug log. Usually used to record exceptions that are unexpected, yet do not indicate fatal conditions (e.g. they are recoverable).
        Parameters:
        e - The exception to report.
      • printDebuggingMessage

        public static java.lang.String printDebuggingMessage​(java.lang.String message)
        Print the provided message to the debug log (if message logging is on). Does not automatically flush the message to the log. Call flush() if you need to ensure the message is immediately flushed.
        Parameters:
        message - The message to report.
        Returns:
        The string provided as an argument (to support log chaining).
      • printDebuggingMessage

        public static void printDebuggingMessage​(java.lang.String location,
                                                 java.lang.String message)
        Print the provided message to the debug log (if message logging is on). Does not automatically flush the message to the log. Call flush() if you need to ensure the message is immediately flushed.
        Parameters:
        location - A string indicating which part of code is generating the message.
        message - The message to log.
      • p

        public static java.lang.String p​(java.lang.String message)
        Same function as printDebuggingMessage(String) but easier to type.
        Parameters:
        message - -
        Returns:
        -
      • p

        public static void p​(java.lang.String location,
                             java.lang.String message)
        Same function as printDebuggingMessage(String,String) but easier to type.
        Parameters:
        location - -
        message - -
      • Assert

        public static void Assert​(boolean check)
                           throws AssertionFailedException
        Check the provided assertion. Used to be named "assert" but renamed to "Assert" to avoid name conflict with the native JDK 1.4 assert function.
        Parameters:
        check - The result of the assertion check, which should be false if it fails.
        Throws:
        AssertionFailedException - thrown if the method parameter is false.
      • Assert

        public static void Assert​(boolean check,
                                  java.lang.String message)
                           throws AssertionFailedException
        Check the provided assertion. Used to be named "assert" but renamed to "Assert" to avoid name conflict with the native JDK 1.4 assert function.
        Parameters:
        check - Whether or not to throw the exception.
        message - A message to include in the thrown exception.
        Throws:
        AssertionFailedException - thrown if the condition evaluates to false.
      • reportFatalException

        static void reportFatalException​(java.lang.Throwable e)
        Report a fatal exception to the error stream. This is package protected because the way to handle fatal errors is to create and throw a FatalException, which takes care of calling this method for you.
        Parameters:
        e - The exception which will be logged as a fatal error.
      • flush

        public static void flush()
        Make sure any messages are flushed to the stream. Printing debug messages does not flush the stream automatically, though reporting exceptions does.