multex
Class Failure

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--java.lang.RuntimeException
                    |
                    +--multex.Failure

Direct Known Subclasses:

Assertion.Failure, Copy.CopyFailure, MethodFailure

public abstract class Failure

extends java.lang.RuntimeException

implements MultexException

Indirectly caused exception with parameters, causal chain and message text. This class serves for the framework user as a base class for defining Failure-exceptions, which have the following benefits:

• coherent usage always for unexpected failure of an operation
• reduce the amount of exceptions to specify in the throws-clause from many unexpected exceptions to only one
• chance to provide the failure of an operation with a message text, message parameters and a chain of the unexpected causing exceptions.

The named exception parameters are handled the same way as in class Exc. For convenience ist is additionally possible to give unnamed parameters to this exception. But they cannot be inserted into a message text pattern. They will be only appended to the text in a standard way for diagnostics output.

Naming convention: All user-defined exception classes derived from Failure should have a name ending in Failure. The pattern is:

class OperationnameFailure extends Failure { ... }

Failure as unchecked exception?

It can be bothering always to specify Failure in the throws-clause of any method, that calls other non-trivial methods. This holds especially, when you are converting an existing software system to usage of MulTEx. Thus Failure inherits the unchecked java.lang.RuntimeException.

So you can specify Failure, but you need not to do this. This is in my opinion not the cleanest way, but even without Failure you could not base on the assumption, that a method without a throws-clause does not throw any exception. Any method could throw any java.lang.RuntimeException, e.g. the IndexOutOfBoundsException.

If you want to strictly check Failure, then you can change the superclass of Failure to the checked java.lang.Exception instead of the unchecked java.lang.RuntimeException. Up to now I am not sure, what is the best way. Please report your experiences.

See Also:

Serialized Form

Constructor Summary

Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Exception i_cause)
Constructs a parameterized Failure-exception, giving only the causing Exception object.

Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Exception i_cause, java.lang.Object[] i_unnamedParameters)
Constructs a Failure-exception, giving the causing Exception object for providing the diagnostics causer chain and unnamed message parameters as an Object[].

Method Summary

java.lang.Exception	cause() Result: The Exception, which caused the program to throw this Failure-exception.
static java.lang.Exception	cause(java.lang.Throwable i_throwable) Result: the causing Exception of i_throwable, if there is one, otherwise null.
java.lang.String	getDefaultMessageTextPattern() Returns the default message text pattern for i_throwable or null.
java.lang.String	getMessage() Returns the exception parameters of this object or null.
static void	printCompactStackTrace(java.lang.StringBuffer io_buffer, java.lang.Throwable i_reportee, java.lang.Exception i_here) Prints the stack trace of i_throwable and all its chained cause exceptions to io_printer.
void	printStackTrace() Prints the chained, redundant stack traces of this Failure object to the standard error stream System.err
void	printStackTrace(java.io.PrintStream io_printer) Prints the chained, redundant stack traces of this Failure object to io_printer.
void	printStackTrace(java.io.PrintWriter io_printer) Prints the chained, redundant stack traces of this Failure object to io_printer.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getLocalizedMessage, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Exception i_cause)

Constructs a parameterized Failure-exception, giving only the causing Exception object. All public nonstatic attributes of this Failure-exception are considered as named exception parameters and can be substituted into the corresponding message text. This is the preferred way to give parameters to an exception, as the meaning of the parameters is more self-documenting.

Example of defining an exception with cause and the named parameters {inFileName} and {outFileName}:

   public static class CopyFailure extends Failure {
     public final String inFileName;
     public final String outFileName;
     public CopyFailure(
       final Exception i_cause,
       final String    i_inFileName,
       final String    i_outFileName
     ){
       super("File '{inFileName}' could not be copied to '{outFileName}'",i_cause);
       inFileName = i_inFileName;
       outFileName = i_outFileName;
     }
   }//CopyFailure
 

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Exception i_cause,
               java.lang.Object[] i_unnamedParameters)

Constructs a Failure-exception, giving the causing Exception object for providing the diagnostics causer chain and unnamed message parameters as an Object[]. The preferred way to parameterize a Failure exception is by giving named parameters to a subclass of Failure, which is described at Failure(String,Exception) In order to shortly create unnamed message parameters, you could use the convenience class MethodFailure, which passes its unnamed parameters to the polymorphic Object[] i_unnamedParameters.

Method Detail

getDefaultMessageTextPattern

public java.lang.String getDefaultMessageTextPattern()

Description copied from interface: MultexException

Returns the default message text pattern for i_throwable or null. Inserting the exception parameters into the message text pattern is done by class MsgText. Locale specific message text patterns are handled by MsgText, too.

Specified by:

getDefaultMessageTextPattern in interface MultexException

cause

public final java.lang.Exception cause()

Result: The Exception, which caused the program to throw this Failure-exception. I.e. the Exception, which was redefined into this Failure object.

cause

public static final java.lang.Exception cause(java.lang.Throwable i_throwable)

Result: the causing Exception of i_throwable, if there is one, otherwise null.

getMessage

public java.lang.String getMessage()

Returns the exception parameters of this object or null. Firstly come the named parameters, then the unnamed ones. They are in a compact, human readable format, e.g.:

{name}=myfile.dat  {directory}=C:\temp\data  {0}=3353  {1}=rw

Overrides:

getMessage in class java.lang.Throwable

printStackTrace

public void printStackTrace()

Prints the chained, redundant stack traces of this Failure object to the standard error stream System.err

Overrides:

printStackTrace in class java.lang.Throwable

See Also:

printStackTrace(java.io.PrintWriter), java.lang.System#err

printStackTrace

public void printStackTrace(java.io.PrintStream io_printer)

Prints the chained, redundant stack traces of this Failure object to io_printer.

Overrides:

printStackTrace in class java.lang.Throwable

See Also:

printStackTrace(java.io.PrintWriter)

printStackTrace

public void printStackTrace(java.io.PrintWriter io_printer)

Prints the chained, redundant stack traces of this Failure object to io_printer. The output contains the name, message parameters and stack trace first of the causing Exception object, then of this Failure object to the specified print writer. Users should usually not call this method directly, but Msg.printStackTrace(java.lang.Throwable) instead, in order to avoid redundant and useless lines in the stack traces.

Overrides:

printStackTrace in class java.lang.Throwable

printCompactStackTrace

public static void printCompactStackTrace(java.lang.StringBuffer io_buffer,
                                          java.lang.Throwable i_reportee,
                                          java.lang.Exception i_here)

Prints the stack trace of i_throwable and all its chained cause exceptions to io_printer. All redundant location lines therein are suppressed. As well all location lines, which are also contained in the stack trace of i_here, are suppressed. This is useful, e.g. for reporting an error in a Swing-ActionListener, because the stack trace of an actionPerformed-method contains 19 lines inside of the AWT/Swing-Package. These lines are not useful for error searching, as they are always the same in any Swing application. Usually you should not directly call this method, but a report-method in class Msg.

Parameters:

io_printer - Where to print the compactified stack trace

i_reportee - The exception to report, possibly containing a chain of nested cause exceptions

i_here - An dummy exception, which should have been newly created there, where the reporting for i_reportee is invoked

See Also:

Msg.report(java.awt.Frame,Throwable)