bcds.phison
Class StdAppExceptionHandler

java.lang.Object
  bcds.phison.StdAppExceptionHandler

public class StdAppExceptionHandler
extends java.lang.Object

Provides an exception handler which applications (command-line programs) can use to print the exception message and, in some cases, the stack trace.

Example of use: Typically, this class is used as follows:

   import udg.bcds.phison.StdAppExceptionHandler;

   public static void main(String...args)
   {
      try {
         ...
         // do whatever throws exceptions (both checked and unchecked).

      } catch (Exception ex) {
         System.out.flush();
         StdAppExceptionHandler.handle(ex, "\nERROR: ");
         System.exit(1);      // Signal a failure.
      }
   }
 

If needed, other catch clauses can be used before the one accepting Exception.

Author:

Juan Segovia S.

Constructor Summary

StdAppExceptionHandler()

Method Summary

static void

handle(java.lang.Throwable exception, java.lang.String prefix) Print the message of the given exception andor the stack trace.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StdAppExceptionHandler

public StdAppExceptionHandler()

Method Detail

handle

public static void handle(java.lang.Throwable exception,
                          java.lang.String prefix)

Print the message of the given exception andor the stack trace. The exception's message, when printed, is always preceeded by prefix. The stack trace does not include the current method, so that the original, real context of the error is preserved. All output is sent to System.err.

If the exception is an instance of AnyException, the inner exception is "unwrapped" and handled. The actions performed for each exception class, which are arranged in the order shown, is as follows (ST means "stack trace is printed" and M means "the exception's message is printed"):

1. NullPointerException: ST.
2. ExitException: M (if it is not null) and System.exit is called with an exit value set to whatever is returned by the exception's getCode method. Thus, in this case, the program is terminated.
3. ArgsParserException or IllegalFormatException: M, ST.
4. IllegalArgumentException or IOException: M.
5. RuntimeException, or Throwable: M, ST.

If the process' environment variable PRINT_STACK_TRACE has a boolean value that amounts to true, the stack trace is printed on stderr, unless the exception is an instance of ExitExcetion, for which the stack trace is never shown. The values 1, yes, true, as well as the uppercase variants, are all considered true.

The cases in which the stack trace is printed are considered "programming errors". The rest are assumed to represent essentially cases of erroneous input (user error). System.err is flushed before returning.