Module org.bzdev.base
Package org.bzdev.util

Class ErrorMessage

java.lang.Object
org.bzdev.util.ErrorMessage
Direct Known Subclasses:
SwingErrorMessage
public class ErrorMessage extends Object
Error-Message Handling with GUI support. This class handles the display of error messages. It is intended for applications that may generate multiple errors or warnings and that might run without a GUI. For some GUI-related operations, one should use the class SwingErrorMessage. Both this class and SwingErrorMessage provide static methods, but are designed to be used interchangably for methods common to both. They were originally a single class, but due to the introduction of Java modules, it was desirable to split these into two classes in order to allow some applications to be run with fewer JAR files.

If nothing is configured, the messages by default are printed on System.err. Where the messages are sent can be modified by calling setAppendable(Appendable).

For methods that cause a message to be displayed the order of arguments are:

  1. a String giving a title for a dialog box. A dialog box will be provided only if the method SwingErrorMessage.setComponent(Component) has been called, including with a null argument.
  2. a Locale giving the locale to use (null implies the default locale.
  3. a String containing format directives or the messsage itself
  4. a variable number of Objects providing arguments specified by a format string.
Depending on the method, some of these may be missing. The order is different from that used by JOptionPane. The rationale for a different order is to make any format string used appear directly before its arguments and to keep the order of arguments consistent among methods defined by this class.

The method setStackTrace(boolean) can be used to programatically turn the display of stack traces on and off for those "display" methods that take a Throwable as an argument, Error messages will sometimes be directed to a console. The documentation for SimpleConsole explains how do do this.

See Also:

  • Field Details

    • needSeparator

      protected static boolean needSeparator
      A field indicating if a separator is needed. This should be treated as a read-only value.

    • err

      protected static Appendable err
      The Appendable to which error messages will be written. The default is System.err.

  • Constructor Details

    • ErrorMessage

      public ErrorMessage()

  • Method Details

    • setOps

      protected static void setOps(ErrorMsgOps newops)
      Set the message operations object. This class is used by SwingErrorMessage to override the default behavior of this class.
      Parameters:
      newops - a replacement for the object that handles error messages.

    • addSeparatorIfNeeded

      public static void addSeparatorIfNeeded()
      Add separator if needed.

    • addSeparatorIfNeededAux

      protected static void addSeparatorIfNeededAux()
      Implemtation method for an instance of ErrorMsgOps.

    • addSeparator

      public static void addSeparator()
      Add a separator.

    • addSeparatorAux

      protected static void addSeparatorAux()
      Implemtation method for an instance of ErrorMsgOps.

    • setStackTrace

      public static void setStackTrace(boolean value)
      Set stack-trace recording. Determines if a stack trace is shown when a Throwable is displayed.
      Parameters:
      value - true if stack traces should be recorded; false otherwise
      See Also:

    • setStackTraceAux

      protected static void setStackTraceAux(boolean value)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      value - an argument

    • stackTraceEnabled

      public static boolean stackTraceEnabled()
      Check if stack traces are enabled.
      Returns:
      true if stack traces are enabled; false otherwise
      See Also:

    • stackTraceEnabledAux

      protected static boolean stackTraceEnabledAux()
      Implemtation method for an instance of ErrorMsgOps.
      Returns:
      status

    • setAppendable

      public static void setAppendable(Appendable out)
      Set the Appendable recording error messages. The default is System.err. The method displayConsoleIfNeeded() will display a console if it is passed to this method and if it is an instance of SimpleConsole. To use the Java console for output (the TTY associated with a process on Unix/Linux), try setAppendable(System.console().writer()); however, normally one would just use System.err.
      Parameters:
      out - the Appendable for error messages; null for the default.

    • setAppendableAux

      protected static void setAppendableAux(Appendable out)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      out - an argument

    • display

      public static void display(String fn, int lineno, String msg)
      Display a message with a file name and line number.
      Parameters:
      fn - the file name
      lineno - the line number
      msg - the message to display

    • displayAux

      protected static void displayAux(String fn, int lineno, String msg)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      fn - an argument
      lineno - an argument
      msg - an argumnt

    • displayConsoleIfNeeded

      public static void displayConsoleIfNeeded()
      Display a console if there is one, if it is an instance of SimpleConsole, and if there is new text to display. For a SimpleConsole to be available, it must have * been passed to setAppendable(Appendable).

    • display

      public static void display(String prefix, Throwable t)
      Display a Throwable with a prefix. at a minimum, the Throwable's message will be displayed. Optionally, a stack trace may be displayed as well.
      Parameters:
      prefix - a prefix to show before a stack trace, typically consisting of spaces
      t - the Throwable
      See Also:

    • displayAux

      protected static void displayAux(String prefix, Throwable t)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      prefix - an argument
      t - an argument

    • display

      public static void display(Throwable t)
      Display a Throwable. at a minimum, the Throwable's message will be displayed. Optionally, a stack trace may be displayed as well.
      Parameters:
      t - the Throwable
      See Also:

    • displayAux

      protected static void displayAux(Throwable t)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      t - an argument

    • display

      public static void display(String msg)
      Display a message.
      Parameters:
      msg - the message to display

    • displayAux

      protected static void displayAux(String msg)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      msg - an argument

    • format

      public static void format(String format, Object... args)
      Display formatted text using the default locale. See Formatter for a description of the format string.
      Parameters:
      format - a format string
      args - the arguments to format

    • formatAux

      protected static void formatAux(String format, Object... args)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      format - an argument
      args - arguments

    • format

      public static void format(Locale locale, String format, Object... args)
      Display formatted text for a specific locale. See Formatter for a description of the format string.
      Parameters:
      locale - the Locale, null for no localization
      format - a format string
      args - the arguments to format

    • formatAux

      protected static void formatAux(Locale locale, String format, Object... args)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      locale - an argument
      format - an argument
      args - arguments

    • displayFormat

      public static void displayFormat(String title, String format, Object... args)
      Display formatted text with a title using the default locale. See Formatter for a description of the format string.

      The title argument is ignored. This method is provided for compatibility with SwingErrorMessage.

      Parameters:
      title - the title; null for the default title
      format - a format string
      args - the arguments to format

    • displayFormatAux

      protected static void displayFormatAux(String title, String format, Object... args)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      title - an argument
      format - an argument
      args - arguments

    • displayFormat

      public static void displayFormat(String title, Locale locale, String format, Object... args)
      Display formatted text with a title for a specific locale. See Formatter for a description of the format string.
      Parameters:
      title - the title; null for the default title
      locale - the Locale, null for no localization
      format - a format string
      args - the arguments to format

    • displayFormatAux

      protected static void displayFormatAux(String title, Locale locale, String format, Object... args)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      title - an argument
      locale - an argument
      format - an argument
      args - arguments

    • display

      public static void display(String title, String msg)
      Display a message with a title. The title argument is ignored. This method is provided for compatibility with SwingErrorMessage.
      Parameters:
      msg - the message to display
      title - the title; null for the default title
      See Also:

    • displayAux

      protected static void displayAux(String title, String msg)
      Implemtation method for an instance of ErrorMsgOps.
      Parameters:
      title - an argument
      msg - an argument

    • getLineAndColumn

      public static int[] getLineAndColumn(String s, int index)
      Get the line, column number, and end of line for a specified offset into a string.
      Parameters:
      s - the string
      index - the offset from the start of the string (the offset for the 1st character is 0)
      Returns:
      an array whose first element is the line number, whose second element is the column number, and whose third element is the offset for the end of the line, excluding any trailing white space

    • addToMessageMap

      public static void addToMessageMap(Class<? extends Throwable> clasz, Function<Throwable,String> mapping)
      Add a mapping from a subclass of Throwable to a function that provides the message for that Throwable without any modifications. This method should be called at most once for each class: subsequent calls for a given class will be ignored.

      Note: a mapping is provided for the class ObjectParser.Exception as it will annotate its message with a description of the location where an error occurred. ObjectParser.Exception provides a method ObjectParser.Exception.getPlainMessage() that recovers the unannotated message.

      Parameters:
      clasz - the class of the Throwable
      mapping - a function that maps the Throwable to its message.

    • getMessageForThrowable

      public static String getMessageForThrowable(Throwable t)
      Get an unannotated message for a Throwable. In most casses, this simply calls the throwable's getMessage() method. That behavior can be modified by calling addToMessageMap(Class,Function).

      This method is used by getMultilineString(String,String,String,int,Exception,boolean,boolean), which in turn is used by ObjectParser.Exception.getMessage() to prevent a strange loop (i.e., infinite recursion).

      Parameters:
      t - the Throwable.a
      Returns:
      the message

    • getMultilineString

      public static String getMultilineString(String prefix, String fn, String input, int index, Exception e, boolean verbose, boolean useLocation)
      Generate a multi-line string for an error message, based on an exception, with a line from some input. The default format in English shows the filename in quotes followed by the line number, the class for the exception, and the corresponding message. The next line contains a portion of the input, with a subsequent line including a caret indicating the point where the error occurred, followed by some information about the column number.
      Parameters:
      prefix - a string that starts each line when verbose is true and each line other than the first line when verbose is false
      fn - a file name or other name for the input
      input - the input being processed
      index - a location in the input where an error occurred
      e - the exception that generated an error
      verbose - true if a long format should be used
      useLocation - true if the location should appended
      Returns:
      a string spaning multiple lines

    • getMultilineString

      public static String getMultilineString(String prefix, String fn, String input, int index, ArrayList<String> fnList, ArrayList<String> inputList, ArrayList<Integer> indexList, Exception e, boolean verbose, boolean useLocation)
      Generate a multi-line string for an error message, based on an exception, with a line from some input. The default format in English shows the filename in quotes followed by the line number, the class for the exception, and the corresponding message. The next line contains a portion of the input, with a subsequent line including a caret indicating the point where the error occurred, followed by some information about the column number.

      The ArrayList arguments are used to provide additional lines showing source-code locations to trace method and function calls.

      Parameters:
      prefix - a string that starts each line when verbose is true and each line other than the first line when verbose is false
      fn - a file name or other name for the input
      input - the input being processed
      index - a location in the input where an error occurred
      fnList - a list of names for additional source-code locations
      inputList - a list of inputs for additional souce-code inputs
      indexList - a list of indices for additional input locations.
      e - the exception that generated an error
      verbose - true if a long format should be used
      useLocation - true if the location should appended
      Returns:
      a string spaning multiple lines

    • display

      public static void display(String fn, String input, int index, Exception e, boolean verbose, boolean showLocation)
      Display an error message, based on an exception, with a line from some input. The default format in English shows the filename in quotes followed by the line number, the class for the exception, and the corresponding message. The next line contains a portion of the input, with a subsequent line including a caret indicating the point where the error occurred, followed by some information about the column number.
      Parameters:
      fn - a file name or other name for the input
      input - the input being processed
      index - a location in the input where an error occurred
      e - the exception that generated an error
      verbose - true if a long format should be used
      showLocation - true if line number and column numbers should be shown; false otherwise

    • displayAux

      protected static void displayAux(String fn, String input, int index, Exception e, boolean verbose, boolean showLocation)
      Implementation to display an error message, based on an exception, with a line from some input. The default format in English shows the filename in quotes followed by the line number, the class for the exception, and the corresponding message. The next line contains a portion of the input, with a subsequent line including a caret indicating the point where the error occurred, followed by some information about the column number.
      Parameters:
      fn - a file name or other name for the input
      input - the input being processed
      index - a location in the input where an error occurred
      e - the exception that generated an error
      verbose - true if a long format should be used
      showLocation - true if line number and column numbers should be shown; false otherwise