multex
Class Failure

java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--java.lang.RuntimeException
                    |
                    +--multex.Failure
All Implemented Interfaces:
MultexException, java.io.Serializable
Direct Known Subclasses:
AssertionFailure

public class Failure
extends java.lang.RuntimeException
implements MultexException

Indirectly caused exception with parameters, causal chain and internationalizable message text. This class serves for the framework user as a base class for defining Failure-exceptions. It can be used to be thrown directly, too, but such exceptions cannot be handled individually nor get internationalized. Failure-exceptions have the following benefits:

The (unnamed, indexed) exception parameters are handled the same way as in class Exc.

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.

Author:
Christoph Knabe, knabe@tfh-berlin.de, TFH Berlin, 1999-2000 Copyrighted
See Also:
Serialized Form

Field Summary
static java.lang.String className
           
static java.lang.String lineSeparator
          Returns the line separator for the actual platform.
static java.lang.String wasCausing
          The string used to delimit the stack trace part of a causing exception from the following stack trace of the caused Failure-exception.
 
Constructor Summary
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause)
          Convenience constructor null
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0)
          Convenience constructor 0
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object[] i_parameters)
          Constructs a Failure-exception, giving complete diagnostic information.
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1)
          Convenience constructor 1
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2)
          Convenience constructor 2
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3)
          Convenience constructor 3
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3, java.lang.Object i_object4)
          Convenience constructor 4
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3, java.lang.Object i_object4, java.lang.Object i_object5)
          Convenience constructor 5
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3, java.lang.Object i_object4, java.lang.Object i_object5, java.lang.Object i_object6)
          Convenience constructor 6
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3, java.lang.Object i_object4, java.lang.Object i_object5, java.lang.Object i_object6, java.lang.Object i_object7)
          Convenience constructor 7
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3, java.lang.Object i_object4, java.lang.Object i_object5, java.lang.Object i_object6, java.lang.Object i_object7, java.lang.Object i_object8)
          Convenience constructor 8
Failure(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3, java.lang.Object i_object4, java.lang.Object i_object5, java.lang.Object i_object6, java.lang.Object i_object7, java.lang.Object i_object8, java.lang.Object i_object9)
          Convenience constructor 9
Failure(java.lang.Throwable i_cause)
          Usable as tunneling exception.
 
Method Summary
static void appendCompactStackTrace(java.lang.StringBuffer io_buffer, java.lang.Throwable i_reportee, java.lang.Exception i_here)
          Deprecated. Obsolete from multex 2, deprecated from 3g.
protected  void checkClass()
          Checks that the class of this object is OK.
 java.lang.Throwable getCause()
          Result: The Throwable object, which directly caused the program to throw this Failure-exception.
static java.lang.Throwable getCause(java.lang.Throwable i_throwable)
          Result: the directly causing Throwable object of i_throwable, if there is one, otherwise null.
static java.lang.Throwable getContainedException(java.lang.Throwable i_throwableChain, java.lang.Class i_expectedThrowableClass)
          Returns the upmost exception in i_throwableChain, which is of class i_expectedThrowableClass, helpwise null.
 java.lang.String getDefaultMessageTextPattern()
          Returns the default message text pattern for this exception object or null.
 java.lang.String getMessage()
          Returns all user-provided information contained in the exception object in an internal, but human readable format.
static java.lang.Throwable getOriginalException(java.lang.Throwable i_throwable)
          Result: The deepest Throwable object, which indirectly caused the program to throw i_throwable, if there is one, otherwise i_throwable itself.
 java.lang.Object[] getParameters()
          Returns the exception parameters
static boolean jreHasExceptionChaining()
          Returns true, if class java.lang.Throwable has an operation getCause() in this Java Runtime Environment
 void printStackTrace()
          Prints the chained, raw stack traces of this Failure object to the standard error stream System.err.
 void printStackTrace(java.io.PrintStream io_printer)
          Prints the chained, raw stack traces of this Failure object to io_printer.
 void printStackTrace(java.io.PrintWriter io_printer)
          Prints the chained, raw stack traces of this Failure object to io_printer.
static void setCauseGetter(CauseGetter i_causeGetter)
          Sets a CauseGetter to be used by method getCause(Throwable) in order to get the cause of a Throwable object, which is not a subclass of Failure.
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getLocalizedMessage, getStackTrace, initCause, setStackTrace, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

className

public static final java.lang.String className
See Also:
Constant Field Values

wasCausing

public static final java.lang.String wasCausing
The string used to delimit the stack trace part of a causing exception from the following stack trace of the caused Failure-exception.

See Also:
Constant Field Values

lineSeparator

public static final java.lang.String lineSeparator
Returns the line separator for the actual platform. This is the line separator for the platform the Java virtual machine is running on. It is the value of the system property 'line.separator'.

Constructor Detail

Failure

public Failure(java.lang.Throwable i_cause)
Usable as tunneling exception. When reporting the message chain, instances of multex.Failure without any own information, will be suppressed by method Msg.printMessages(StringBuffer,Throwable,ResourceBundle) and the similar convenience methods. This is a convenience constructor with only a cause, but null for both i_defaultMessageTextPattern, and i_parameters.

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause)
Convenience constructor null

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0)
Convenience constructor 0

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1)
Convenience constructor 1

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2)
Convenience constructor 2

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3)
Convenience constructor 3

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3,
               java.lang.Object i_object4)
Convenience constructor 4

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3,
               java.lang.Object i_object4,
               java.lang.Object i_object5)
Convenience constructor 5

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3,
               java.lang.Object i_object4,
               java.lang.Object i_object5,
               java.lang.Object i_object6)
Convenience constructor 6

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3,
               java.lang.Object i_object4,
               java.lang.Object i_object5,
               java.lang.Object i_object6,
               java.lang.Object i_object7)
Convenience constructor 7

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3,
               java.lang.Object i_object4,
               java.lang.Object i_object5,
               java.lang.Object i_object6,
               java.lang.Object i_object7,
               java.lang.Object i_object8)
Convenience constructor 8

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object i_object0,
               java.lang.Object i_object1,
               java.lang.Object i_object2,
               java.lang.Object i_object3,
               java.lang.Object i_object4,
               java.lang.Object i_object5,
               java.lang.Object i_object6,
               java.lang.Object i_object7,
               java.lang.Object i_object8,
               java.lang.Object i_object9)
Convenience constructor 9

See Also:
Failure(String, Throwable, Object[])

Failure

public Failure(java.lang.String i_defaultMessageTextPattern,
               java.lang.Throwable i_cause,
               java.lang.Object[] i_parameters)
Constructs a Failure-exception, giving complete diagnostic information.

Example of defining an exception with default text, cause and parameters:

   public static class CopyFailure extends Failure {
     public CopyFailure(
       final Throwable i_cause,
       final String    i_inFileName,
       final String    i_outFileName
     ){
       super("File ''{0}'' could not be copied to ''{1}''",
         i_cause, new Object[]{i_inFileName, i_outFileName}
       );
     }
   }//CopyFailure
 
Instead of creating an Object[] yourself you can use the corresponding convenience constructors.

Parameters:
i_defaultMessageTextPattern - The default message text pattern in the syntax of java.text.MessageFormat or null, if message text patterns shall only be taken from a ResourceBundle
i_cause - The causing Throwable object for providing the diagnostics causer chain
i_parameters - Exception parameters as an polymorphic Object[], which can be inserted into the message text pattern by placeholders {0} ... {9}. null is allowed here, if you do not want to provide exception parameters.
Method Detail

getDefaultMessageTextPattern

public java.lang.String getDefaultMessageTextPattern()
Description copied from interface: MultexException
Returns the default message text pattern for this exception object 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

getParameters

public java.lang.Object[] getParameters()
Description copied from interface: MultexException
Returns the exception parameters

Specified by:
getParameters in interface MultexException

getCause

public final java.lang.Throwable getCause()
Result: The Throwable object, which directly caused the program to throw this Failure-exception. I.e. the Throwable object, which was redefined into this Failure object, if there is one, otherwise null.

Overrides:
getCause in class java.lang.Throwable

getCause

public static final java.lang.Throwable getCause(java.lang.Throwable i_throwable)
Result: the directly causing Throwable object of i_throwable, if there is one, otherwise null.


getContainedException

public static java.lang.Throwable getContainedException(java.lang.Throwable i_throwableChain,
                                                        java.lang.Class i_expectedThrowableClass)
Returns the upmost exception in i_throwableChain, which is of class i_expectedThrowableClass, helpwise null. Usage e.g. for a FieldValueExc, which is thrown from the business logic layer to the user interface layer, wrapped some times on this way, but should trigger a uniform reaction on the user interface layer (Marking the named form field as erroneous, and issuing its error message).


getOriginalException

public static final java.lang.Throwable getOriginalException(java.lang.Throwable i_throwable)
Result: The deepest Throwable object, which indirectly caused the program to throw i_throwable, if there is one, otherwise i_throwable itself.

See Also:
getCause(Throwable)

setCauseGetter

public static final void setCauseGetter(CauseGetter i_causeGetter)
Sets a CauseGetter to be used by method getCause(Throwable) in order to get the cause of a Throwable object, which is not a subclass of Failure. Default is Jdk1_4CauseGetter


getMessage

public java.lang.String getMessage()
Description copied from interface: MultexException
Returns all user-provided information contained in the exception object in an internal, but human readable format. The information are the default message text pattern and the exception parameters of this object or null if none of these is provided. E.g.:
  TEXT: Unable to create file {0} in directory {1}
  {0}=myfile.dat  {1}=C:\temp\data
   
Overrides the same method of java.lang.Throwable

Specified by:
getMessage in interface MultexException
Overrides:
getMessage in class java.lang.Throwable

printStackTrace

public void printStackTrace()
Prints the chained, raw 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)

printStackTrace

public void printStackTrace(java.io.PrintStream io_printer)
Prints the chained, raw 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, raw stack traces of this Failure object to io_printer. Depending on the version of the Java Runtime Environment we get for

appendCompactStackTrace

public static void appendCompactStackTrace(java.lang.StringBuffer io_buffer,
                                           java.lang.Throwable i_reportee,
                                           java.lang.Exception i_here)
Deprecated. Obsolete from multex 2, deprecated from 3g.

Appends the stack trace of i_throwable and all its chained cause exceptions to io_buffer. All redundant location lines therein are suppressed. Usually you should not directly call this method, but a printStackTrace-method in class Msg.

Parameters:
io_buffer - Where to append 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; No longer interpreted.
See Also:
Msg.printStackTrace(StringBuffer,Throwable)

checkClass

protected void checkClass()
Checks that the class of this object is OK. In the moment this means, that its name ends in className


jreHasExceptionChaining

public static boolean jreHasExceptionChaining()
Returns true, if class java.lang.Throwable has an operation getCause() in this Java Runtime Environment