jv.object

## Class PsDebug

- java.lang.Object
- - jv.object.PsDebug

- All Implemented Interfaces:
    java.lang.Runnable

      public final class PsDebug
      extends java.lang.Object
      implements java.lang.Runnable

  Allows to issue messages and debug information on the console of JavaView, which is different from Java console. These calls are intended to replace System.out calls. Textual debug information may be issued with either of the following calls

              if (PsDebug.NOTIFY) PsDebug.notify(String)    // Default: disabled in release version
              if (PsDebug.WARNING) PsDebug.warning(String)  // Default: enabled
              PsDebug.error(String, PsObject)               // Default: enabled

  and textual messages may be directly issued with

              PsDebug.message(String)                       // Default: enabled

  All information is collected in a text area and shown in the dialog `PsConsole`. The checkboxes located in the header of the console allow to enable different warning levels. Remark: All messages are cached and flushed to console after some short intervals.

  Debug methods parse the current stack trace and print additional information about the calling method and class.

  See Also:
    `PsConsole`
  Author:
    Konrad Polthier
  Version:
    23.11.14, 3.80 revised (kp) Special checks to assure a clean jvLite setup.
    11.03.10, 3.70 revised (fk) Add `messageWithoutNewline(String)`.
    19.11.06, 3.60 revised (kp) New methods to popStatus and pushStatus.
    24.04.05, 3.50 revised (kp) New method to issue outOfMemory warning.
    20.11.04, 3.41 revised (kp) New global variable DEBUG for development purposes.
    22.09.02, 3.40 revised (kp) Console not created until it is really shown.
    21.09.02, 3.30 revised (kp) New static variables added MESSAGE and STATUS.
    16.12.00, 3.20 revised (kp) New methods to get/set maximal number of beeps.
    04.11.00, 3.10 revised (kp) New private variables to identify debug messages.
    03.11.00, 3.00 revised (kp) Message use method stack to print information about calling method.
    30.09.99, 2.20 revised (kp) Thread in PsConsole deactivated because of mysterious dead lock.
    11.07.99, 2.10 revised (kp) NOTIFY flag added.
    09.06.99, 2.00 revised (kp) Caching of messages added to method append().
    02.06.99, 1.60 revised (kp) Invoke a reset of static PsDebug when console is disposed.
    20.05.99, 1.50 revised (kp) Handling of console moved here from PvViewer.
    23.01.99, 1.20 revised (kp) method `message(String)` added.
    16.11.98, 1.10 revised (kp) cleaned.
    00.00.97, 1.00 created (kp)

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG` Determines if JavaView runs in debug mode.
    `static boolean` | `ERROR` Global flag used during compile time to include or exclude all PsDebug.error() calls.
    `static int` | `MAX_MESSAGE_LENGTH` Determines the message type 'message'.
    `static boolean` | `MEMORY` Determines if JavaView performs memory measurements.
    `static boolean` | `MESSAGE` Global flag used during compile time to include or exclude all PsDebug.message() calls.
    `static boolean` | `NOTIFY` Global flag used during compile time to include or exclude all PsDebug.notify() calls.
    `static boolean` | `PROFILE` Determines if JavaView performs profiling measurements.
    `static boolean` | `STATUS` Global flag used during compile time to include or exclude all PsDebug.showStatus() calls.
    `static boolean` | `WARNING` Global flag used during compile time to include or exclude all PsDebug.warning() calls.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PsDebug()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `beep(java.lang.String message)` Issue a beep and print message to System.out.
    `static void` | `disposeConsole()` Dispose console window, e.g. when applet stops, remove textArea and reset variables.
    `static void` | `error(java.lang.String aString)` Error messages indicate fatal errors which cannot be handled.
    `static void` | `error(java.lang.String aString, java.lang.Object what)` Error messages indicate fatal errors which cannot be handled.
    `static void` | `flushMessages()` Flush cached messages into console window.
    `static PsConsole` | `getConsole()` Get console window.
    `static java.awt.Rectangle` | `getConsoleSize()` Get rectangle with size of JavaView console window.
    `static long` | `getFlushInterval()` Get length of least time interval between two successive flushes.
    `static int` | `getMaxNumBeeps()` Get maximal number of warning beeps.
    `static long` | `getMemoryIncr()` Get amount of newly allocated memory since last call of initMemory() or getMemoryIncr().
    `static long` | `getMemoryTotal()` Get total amount of memory which is total memory minus free memory of current runtime.
    `static java.awt.Panel` | `getStatusPanel()` Get panel which shows status information.
    `static long` | `getTimeIncr()` Get number of milliseconds since last call of getIncrTime() or initTime().
    `static long` | `getTimeUsed()` Get number of milliseconds since last call of initTime().
    `static boolean` | `hasConsole()` Get state of console.
    `static boolean` | `hasMessages()` Check whether message buffer contains non-flushed messages.
    `static void` | `initMemory()` Compute initial amount of memory for use with getMemoryIncr().
    `static void` | `initTime()` Initialize timer for use with getTimeUsed() and getTimeIncr().
    `static boolean` | `isDebug()` Check switch if debugging is enabled.
    `static boolean` | `isError()` Check switch to record heavy errors in JavaView console.
    `static boolean` | `isMessage()` Check switch to record info message in JavaView console.
    `static boolean` | `isNotify()` Check switch to record notify message, i.e. debug messages, in JavaView console.
    `static boolean` | `isWarning()` Check switch to record warning messages in JavaView console.
    `static void` | `message(java.lang.String aString)` Print messages immediately to console, make rare use since no button to turn it off.
    `static void` | `message(java.lang.String aString, boolean bShowConsole)` Print messages immediately to console, make rare use since no button to turn it off.
    `static void` | `messageWithoutNewline(java.lang.String aString)` Print messages immediately to console, make rare use since no button to turn it off.
    `static void` | `messageWithoutNewline(java.lang.String aString, boolean bShowConsole)` Print messages immediately to console, make rare use since no button to turn it off.
    `static void` | `notify(java.lang.String aString)` Heavily used during development process for all different messages.
    `static void` | `outOfMemory(java.lang.OutOfMemoryError oom)` Issue an OutOfMemory warning and perform garbage collection.
    `static void` | `popStatus()` Recall and show the previous status message.
    `static void` | `pushStatus(java.lang.String aString)` Store previous status on stack and show this new status message.
    `static void` | `pushStatus(java.lang.String aString, int seconds)` Display message in status bar of applet, and in console window.
    `void` | `run()` Flush messages collected with PsDebug to console.
    `static void` | `setConsole(PsConsole console)` Set console.
    `static void` | `setDebug(boolean aFlag)` Enable debugging.
    `static void` | `setError(boolean aFlag)` Enable recording of heavy errors in JavaView console.
    `static void` | `setMaxNumBeeps(int num)` Set maximal number of warning beeps.
    `static void` | `setMessage(boolean aFlag)` Enable recording of info message in JavaView console.
    `static void` | `setNotify(boolean aFlag)` Enable recording of notify message, i.e. debug messages, in JavaView console.
    `static void` | `setWarning(boolean aFlag)` Enable recording of warning messages in JavaView console.
    `static void` | `showStatus(java.lang.String aString)` Display message in status bar of applet, and in console window.
    `static void` | `warning(java.lang.Exception ex, java.lang.String aString)` Warning messages indicate real errors which are handled.
    `static void` | `warning(java.lang.String aString)` Warning messages indicate real errors which are handled.
    `static void` | `warning(java.lang.String aString, java.lang.Object what)` Warning messages indicate real errors which are handled.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### STATUS

          public static final boolean STATUS

      Global flag used during compile time to include or exclude all PsDebug.showStatus() calls. If `STATUS==false` then all notification methods are removed by a Java compiler during optimization since the methods would never be executed.

      The Microsoft conditional directive is used to simplify the conditional switch, and the conditional statements can be removed without any influence if the developer sets the variable STATUS by hand.

      See Also:
        Constant Field Values
      Version:
        21.09.02, 1.00 created (kp)

    - #### MESSAGE

          public static final boolean MESSAGE

      Global flag used during compile time to include or exclude all PsDebug.message() calls. If `MESSAGE==false` then all notification methods are removed by a Java compiler during optimization since the methods would never be executed.

      The Microsoft conditional directive is used to simplify the conditional switch, and the conditional statements can be removed without any influence if the developer sets the variable MESSAGE by hand.

      See Also:
        Constant Field Values
      Version:
        21.09.02, 1.00 created (kp)

    - #### NOTIFY

          public static final boolean NOTIFY

      Global flag used during compile time to include or exclude all PsDebug.notify() calls. If `NOTIFY==false` then all notification methods are removed by a Java compiler during optimization since the methods would never be executed.

      The Microsoft conditional directive is used to simplify the conditional switch, and the conditional statements can be removed without any influence if the developer sets the variable NOTIFY by hand.

      See Also:
        Constant Field Values
      Version:
        06.05.17, 1.02 revised (kp) Activate notify framework, though might be switch off initially.
        31.08.99, 1.01 revised (kp) Microsoft conditional directive added.

    - #### WARNING

          public static final boolean WARNING

      Global flag used during compile time to include or exclude all PsDebug.warning() calls. If `WARNING==false` then all warning methods are removed by a Java compiler during optimization since the methods would never be executed.

      The Microsoft conditional directive is used to simplify the conditional switch, and the conditional statements can be removed without any influence if the developer sets the variable WARNING by hand.

      See Also:
        Constant Field Values
      Version:
        31.08.99 1.01 revised (kp) Microsoft conditional directive added.

    - #### ERROR

          public static final boolean ERROR

      Global flag used during compile time to include or exclude all PsDebug.error() calls. If `ERROR==false` then all error methods are removed by a Java compiler during optimization since the methods would never be executed.

      The Microsoft conditional directive is used to simplify the conditional switch, and the conditional statements can be removed without any influence if the developer sets the variable ERROR by hand.

      Since:
        JavaView 2.37
      See Also:
        Constant Field Values
      Version:
        13.09.02 1.00 created (kp)

    - #### DEBUG

          public static final boolean DEBUG

      Determines if JavaView runs in debug mode.
      Since:
        JavaView 3.54.000
      See Also:
        Constant Field Values
      Version:
        29.08.04 1.00 created (kp)

    - #### MEMORY

          public static final boolean MEMORY

      Determines if JavaView performs memory measurements.
      Since:
        JavaView 3.84.012
      See Also:
        Constant Field Values
      Version:
        04.02.05 1.00 created (kp)

    - #### PROFILE

          public static boolean PROFILE

      Determines if JavaView performs profiling measurements.
      Since:
        JavaView 4.10.003
      Version:
        12.03.14 1.00 created (kp)

    - #### MAX_MESSAGE_LENGTH

          public static final int MAX_MESSAGE_LENGTH

      Determines the message type 'message'.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PsDebug

          public PsDebug()

  - ### Method Detail

    - #### getConsole

          public static PsConsole getConsole()

      Get console window. It is no error if console window is not available, e.g. when during startup frame has not been registered in PsConfig. The text area is available from the very beginning and records all information. If console is opened this information is displayed in the console.
      Version:
        12.06.99, 1.70 revised (kp) Flush message when creating a new console.

    - #### getStatusPanel

          public static java.awt.Panel getStatusPanel()

      Get panel which shows status information.
      Version:
        05.05.07, 1.10 revised (kp) Background color of status panel.
        18.11.06, 1.00 created (kp)

    - #### disposeConsole

          public static void disposeConsole()

      Dispose console window, e.g. when applet stops, remove textArea and reset variables. Since PsDebug is a static class it is essential to remove the console and textArea when an applet stops, since otherwise the next applet will get the same console window and textArea.
      Version:
        02.06.99, 1.60 revised (kp) Invoke a reset of static PsDebug when console is disposed.
        20.05.99, 1.50 created (kp) Handling of console moved here from PvViewer.

    - #### setConsole

          public static void setConsole(PsConsole console)

      Set console.

    - #### hasConsole

          public static boolean hasConsole()

      Get state of console.

    - #### getConsoleSize

          public static java.awt.Rectangle getConsoleSize()

      Get rectangle with size of JavaView console window.

    - #### isMessage

          public static boolean isMessage()

      Check switch to record info message in JavaView console.

    - #### setMessage

          public static void setMessage(boolean aFlag)

      Enable recording of info message in JavaView console.

    - #### isNotify

          public static boolean isNotify()

      Check switch to record notify message, i.e. debug messages, in JavaView console.

    - #### setNotify

          public static void setNotify(boolean aFlag)

      Enable recording of notify message, i.e. debug messages, in JavaView console.

    - #### isWarning

          public static boolean isWarning()

      Check switch to record warning messages in JavaView console.

    - #### setWarning

          public static void setWarning(boolean aFlag)

      Enable recording of warning messages in JavaView console.

    - #### isError

          public static boolean isError()

      Check switch to record heavy errors in JavaView console.

    - #### setError

          public static void setError(boolean aFlag)

      Enable recording of heavy errors in JavaView console.

    - #### isDebug

          public static boolean isDebug()

      Check switch if debugging is enabled.

    - #### setDebug

          public static void setDebug(boolean aFlag)

      Enable debugging.

    - #### getFlushInterval

          public static long getFlushInterval()

      Get length of least time interval between two successive flushes.

    - #### hasMessages

          public static boolean hasMessages()

      Check whether message buffer contains non-flushed messages.

    - #### flushMessages

          public static final void flushMessages()

      Flush cached messages into console window. Console window is the Runnable and calls this method from time to time.

    - #### popStatus

          public static final void popStatus()

      Recall and show the previous status message.
      Version:
        19.11.06, 1.00 created (kp)

    - #### pushStatus

          public static final void pushStatus(java.lang.String aString)

      Store previous status on stack and show this new status message.
      Version:
        19.11.06, 1.00 created (kp)

    - #### pushStatus

          public static final void pushStatus(java.lang.String aString,
                                              int seconds)

      Display message in status bar of applet, and in console window.
      Parameters:
        `aString` - status message
      Version:
        04.11.00, 1.10 revised (kp) No longer print a notify message of status.

    - #### run

          public void run()

      Flush messages collected with PsDebug to console. All handling is done inside PsDebug, but PsDebug cannot implement functionality of a Runnable since it is static. Therefore, the instance of PsConsole is used.
      Specified by:
        `run` in interface `java.lang.Runnable`

    - #### showStatus

          public static final void showStatus(java.lang.String aString)

      Display message in status bar of applet, and in console window.
      Parameters:
        `aString` - status message
      Version:
        04.11.00, 1.10 revised (kp) No longer print a notify message of status.

    - #### message

          public static final void message(java.lang.String aString)

      Print messages immediately to console, make rare use since no button to turn it off.
      Version:
        12.06.01, 1.00 created (kp)

    - #### messageWithoutNewline

          public static final void messageWithoutNewline(java.lang.String aString)

      Print messages immediately to console, make rare use since no button to turn it off.
      Version:
        11.03.10, 1.00 created (fk)

    - #### message

          public static final void message(java.lang.String aString,
                                           boolean bShowConsole)

      Print messages immediately to console, make rare use since no button to turn it off. Additional message method which allows to avoid automatic display of the JavaView console.
      Version:
        11.03.10, 1.10 revised (fk) Delegate to messageWithoutNewline.
        12.06.01, 1.00 created (kp)

    - #### messageWithoutNewline

          public static final void messageWithoutNewline(java.lang.String aString,
                                                         boolean bShowConsole)

      Print messages immediately to console, make rare use since no button to turn it off. Additional message method which allows to avoid automatic display of the JavaView console.
      Version:
        11.03.10, 1.00 created (fk) created from `message(String, boolean)`

    - #### notify

          public static final void notify(java.lang.String aString)

      Heavily used during development process for all different messages. Many calls should remain even after in the release version but with disabled notification.

    - #### warning

          public static final void warning(java.lang.String aString)

      Warning messages indicate real errors which are handled. A warning message indicates that something is wrong with the system, and further running may lead to unexpected behaviour.
      Parameters:
        `aString` - warning message

    - #### warning

          public static final void warning(java.lang.Exception ex,
                                           java.lang.String aString)

      Warning messages indicate real errors which are handled. A warning message indicates that something is wrong with the system, and further running may lead to unexpected behaviour.

      Print stack trace either of the method which invoked this warning method, or, if ex!=null print the stack trace of the exception.

      Parameters:
        `ex` - Stack trace of exception is printed rather than of invocation of warning.
        `aString` - warning message

    - #### warning

          public static final void warning(java.lang.String aString,
                                           java.lang.Object what)

      Warning messages indicate real errors which are handled. A warning message indicates that something is wrong with the system, and further running may lead to unexpected behaviour.
      Parameters:
        `aString` - warning message
        `what` - object containing more information, what.toString() is appended to message

    - #### error

          public static final void error(java.lang.String aString)

      Error messages indicate fatal errors which cannot be handled. The system is completely out of order. Method calls `PsDebug.error(String, Object)` with `object==null`. Console window pops up automatically if method is called.
      Parameters:
        `aString` - error message

    - #### error

          public static final void error(java.lang.String aString,
                                         java.lang.Object what)

      Error messages indicate fatal errors which cannot be handled. The system is completely out of order. Console window pops up automatically if method is called.
      Parameters:
        `aString` - error message.
        `what` - object containing more information, what.toString() is appended to message.

    - #### getMaxNumBeeps

          public static int getMaxNumBeeps()

      Get maximal number of warning beeps.
      Returns:
        the maximal number of warning beeps.

    - #### setMaxNumBeeps

          public static void setMaxNumBeeps(int num)

      Set maximal number of warning beeps.
      Parameters:
        `num` - maximal number of warning beeps.

    - #### beep

          public static void beep(java.lang.String message)

      Issue a beep and print message to System.out. Only the first invocations of this method lead to an actually beep.

      The beep() method attempts to play an audio beep. You have no control over pitch, duration, or volume; it is like putting echo ^G in a UNIX shell script.

      If run as application this method calls the beep method of the default toolkit. If run as applet then a beep from an audio file is played (pending).

      Method is called if an error occurs, or, when in debug mode, also if a warning occurs. Information about the beep is given in the console window of JavaView.

      Version:
        10.08.00, 1.00 created (kp)

    - #### initTime

          public static void initTime()

      Initialize timer for use with getTimeUsed() and getTimeIncr().
      Since:
        JavaView v3.84.012
      Version:
        05.02.05, 1.00 created (kp)

    - #### getTimeUsed

          public static long getTimeUsed()

      Get number of milliseconds since last call of initTime().
      Returns:
        number of milliseconds since last call of initTime().
      Since:
        JavaView v3.84.012
      Version:
        05.02.05, 1.00 created (kp)

    - #### getTimeIncr

          public static long getTimeIncr()

      Get number of milliseconds since last call of getIncrTime() or initTime().
      Returns:
        number of milliseconds since last call of getTimeIncr() or initTime().
      Since:
        JavaView v3.84.012
      Version:
        05.02.05, 1.00 created (kp)

    - #### initMemory

          public static void initMemory()

      Compute initial amount of memory for use with getMemoryIncr(). It is a good idea to garbage collect before, e.g. using PsConfig.runCG().
      Since:
        JavaView v3.84.012
      Version:
        05.02.05, 1.00 created (kp)

    - #### getMemoryTotal

          public static long getMemoryTotal()

      Get total amount of memory which is total memory minus free memory of current runtime.
      Since:
        JavaView v3.84.012
      Version:
        05.02.05, 1.00 created (kp)

    - #### getMemoryIncr

          public static long getMemoryIncr()

      Get amount of newly allocated memory since last call of initMemory() or getMemoryIncr().
      Since:
        JavaView v3.84.012
      Version:
        05.02.05, 1.00 created (kp)

    - #### outOfMemory

          public static void outOfMemory(java.lang.OutOfMemoryError oom)

      Issue an OutOfMemory warning and perform garbage collection.
      Since:
        JavaView v3.85.002
      Version:
        23.04.05, 1.00 created (kp)

"

The software JavaView? is copyright protected. All Rights Reserved.
"