MulTEx - the Multi-Tier Exception Handling Framework.
MulTEx is a simple, but powerful framework for organizing exceptions
and messages is a multi-tier Java software system.
It offers the key features:
- Causal chains/trees as a means to capture low-level error information
- Redundancy-free stack traces and message chains in the case of indirectly caused exceptions
- Internationalized message texts and parameters for exceptions
- Services for reporting an exception chain/tree onto streams and dialogs
- A standard way for writing method bodies with regard to exceptions
- A collection of utilities for centralized exception reporting
For introductory information you should first read the technical paper or the user's guide.
Naming conventions
The following naming conventions are used throughout the package multex
.
- i_name for an in-parameter of a method, i.e. either a parameter of a primitive
type or a parameter of a reference type, which will not be modified
by the invoked method.
- o_name for an out-parameter of a method, i.e. a parameter of a reference type,
where the referred object will be completely initialized by the method,
ignoring all its previous content.
- io_name for an in/out-parameter of a method, i.e. a parameter of a reference type,
where the referred object will be modified by the method,
possibly using its previous content.
- _name for attributes or methods, which should not be used from
outside the class or its subclasses.
Plans
The plans are ordered by priority (most important as No. 1)
- 2002-03-26 Prepared means for reporting exceptions with its complete
diagnostic information in a servlet/JSP application. You can obtain a
project specific Struts solution for this from the author.
See applying site http://fb6.tfh-berlin.de/
- 2003-05-28 Add a class SwingAction with a method actionPerformedWithThrows,
which will extend javax.swing.AbstractAction and report any exception coming
from lower layers.
- 2002-04-20 Add buttons for printing or copying the contents of the
message window of multex.Awt; place the buttons before the message TextArea.
- 2005-01-13 Include wrapper exceptions for some exceptions, which do not show
all their diagnostic info by toString(). Maybe on reflection basis.
I think SQLException is a candidate for this, as its attributes
SQLState, and vendorCode are not included in its toString().
- 2005-01-13 Include private attributes of type Throwable into the
{@link multex.ReflectionCauseGetter} in order to get the cause for
an exception, which does not implement the getCause() of JDK 1.4.
Is there still any such exception?
Version history
- 7.1 of 2006-11-04
Added {@link multex.tool.ExceptionMessagesDoclet}.
You can use this doclet to extract the main comment of each Throwable into a .properties file as message text.
Added constructor {@link multex.Failure#Failure(String)} without a cause.
- 7 of 2006-05-11: Added parameter cause in constructors of class {@link multex.Exc};
Added method getCause() in interface {@link multex.MultexException}.
Added list exception facility: All parameters of a {@link multex.MultexException}, which are of type java.lang.Throwable,
are reported by {@link multex.Msg#printMessages}, thus resulting in a causal exception tree instead of an exception chain.
{@link multex.Msg#printStackTrace} prints thus a redundancy-free stack trace of all exceptions,
contained in the causal exception tree.
As the tree is symbolized by an indentation by multiple +
signs,
the layout of printMessages and printStackTrace is no longer the same as in MulTEx 6.
- 6c of 2006-02-16
Added in User's Guide: How to assure centralized exception reporting in a Java Server Faces application.
- 6b of 2005-04-26
Added User's Guide documenting, how to introduce MulTEx.
Main chapter: How to assure centralized exception reporting.
- 6a of 2005-04-14
Added method {@link multex.Awt#setAwtExceptionHandlerClass} to set a general exception handler,
which can report any exception propagated through to the AWT EventDispatchThread.
Uses the undocumented system property "sun.awt.exception.handler",
which enables a single place handling for all exceptions in methods called from a
AWT or Swing GUI. See example in class multex.demo.AwtFile.
- 6 of 2005-01-13
Improvement: The methods in class {@link multex.Msg}
for printing the stack trace of a Throwable chain betterly recognize
low level causes in an exception chain. They follow the chain by the
{@link multex.ReflectionCauseGetter} instead of leaving this to
Throwable.printStackTrace().
Restriction: Now needs JRE >= 1.4, which exists already >= 3 years.
Incompatible: Much utility functionality moved from class
{@link multex.Failure} to the new class {@link multex.Util}.
- 5d of 2004-12-10:
Restriction: MulTEx now needs JRE >= 1.2 for execution, JDK >= 1.4 for testing.
Improvement: The methods in class {@link multex.Msg}
for printing the messages of a Throwable chain,
suppress redundant info caused by legacy exception chaining as String,
e.g. Root cause is ..., or nested exception is ...
- 5c of 2004-11-05:
Bugfix: The methods in class {@link multex.Msg}
for printing the stack trace of a Throwable chain, report a null Throwable
instead of throwing NullPointerException.
Improvement: The methods in class {@link multex.Msg}
for printing the messages of a Throwable chain,
a) report a null Throwable instead of printing nothing,
b) suppress reporting an object of the exact class Failure
without any own info. See {@link multex.Failure#Failure(Throwable)} shortly
for the concept of a tunneling exception.
Packaging: The release is a .zip file, which contains a -class.jar file
with all core framework classes, and a -java.jar file with the source code
of the framework, the test suite, and the demo programs.
- 5b of 2004-05-11:
Bugfix: Method {@link multex.Msg#printReport(StringBuffer, Throwable, ResourceBundle)}
now passes its ResourceBundle to multex.Msg.printMessages(...).
Bug avoiding: Now {@link multex.Awt} and {@link multex.Swing} show the reporting dialog
in the AWT event queue thread, instead of the callers thread.
See http://java.sun.com/developer/JDCTechTips/2003/tt1208.html
Comfort: Method {@link multex.Awt#countLines(String)} is now public.
- 5a of 2003-11-25:
Bugfix: Report any exception with message text pattern, but without
exception parameters or Throwable.getMessage() without
": null"
.. Corresponding testcases added.
- 5 of 2003-09-12:
Added class {@link multex.Swing} for reporting into a Swing dialog
with dynamic or static internationalization.
Interface of class {@link multex.Awt} simplified (incompatible change) and made
uniform with Swing.
Added method {@link multex.Util#getContainedException(java.lang.Throwable,java.lang.Class)}, originally to class Failure.
Simpler dynamic internationalization using only a java.util.ResourceBundle
Takes the cause marker from the used ResourceBundle
by key {@link multex.MsgText#causeMarker} instead of giving it as a separate
argument (incompatible change).
Class MultexLocale deprecated, see there (incompatible change).
Unnecessary parameter i_lineSeparator removed in all methods.
See class description {@link multex.Msg} (incompatible change).
- 4a of 2003-07-01 (unpublished) Bugfix: Failure.getOriginalException(Throwable):
corrected endless loop.
- 4 of 2003-05-22: With dynamic internationalization as for web servers.
The new class multex.MultexLocale bundles a ResourceBundle for the message texts,
the Locale for the message parameter substitution, and a cause marker text.
The MultexLocale is electable for each exception message report.
The line separator for low level exception reports is electable, too.
See {@link multex.Msg#printMessages(StringBuffer,Throwable,java.util.ResourceBundle)}.
- 3e of 2002-07-02: Compiles unchanged on JDK 1.1 up to 1.4. Uses by default ReflectionCauseGetter.
Thus code compiled on one JDK-version should run on another version.
Includes JUnit tests in subdirectory 'test'.
- 3d of 2002-06-27: Will compile unchanged on JDK 1.4 and on earlier ones,
automatically adapting itself to using Jdk1_4CauseGetter or Jdk1_1CauseGetter.
- 3c of 2002-06-26: Corrected compilation error of classes Awt and Msg using MsgText.appendMessageChain()
- 3b of 2002-06-25: Added java.sql.SQLWarning to JDK1_1CauseGetter and JDK1_4CauseGetter,
Corrected package name in demo/MsgText_de.properties to 'multex.demo',
MsgText.appendMessageChain() allows to specify a lineSeparator, useful for HTML-output,
first version of errorPage.jsp.
- 3a of 2002-05-21: New presentation slides: Actualized, landscape format.
- 3 of 2002-04-29: Adaptation to JDK 1.4
- As JDK 1.4 finally introduced the concept of a causal chain for the
exception base class
Throwable,
MulTEx 3 now makes use of this feature instead of managing the causal chain itself.
- Thus requires JDK 1.4.
- gendocs.bat: Generation error in JDK 1.4 corrected
- 2c of 2002-03-26:
- class Failure: Example message text parameters in constructor correctly
quoted. Analoguous correction in demo class File.
- This is the last release destinated for JDK versions 1.1 up to 1.3
and produced with JDK 1.3.
- 2b of 2001-12-18:
- source files in package correct directory multex, achieved by
introducing an automated release procedure.
- 2a of 2001-06-28:
- Awt.report(...): Now accepts any AWT-Component as owner hook.
The owner Window is determined by searching the Window which is the
nearest parent of the hook component. Although some report-methods
were deleted, this should be upwards compatible to version 2.
- 2 of 2001-04-19:
- Msg.printStackTrace(...) does no longer delete the last lines,
which indicate the place, where it has been invoked. So the compactified
multi-tier trace contains all lines of the trace of the lowest
exception.
- Again only unnamed indexed exception parameters for message text
placeholders {0} ... {9}, but with a default text pattern in the
exception object.
In the stack trace is included the default text pattern (if provided).
The parameters are each on a separate line.
- Added convenience constructors to multex.Exc and multex.Failure with
0..10 parameters of type Object for filling the parameter Object[].
- class Failure: Method name getCause(...) instead of cause(...),
getOriginalException(...) instead of originalException(...)
- All inner classes repositioned as outer classes: CauseGetter,
Jdk1_1CauseGetter, AssertionFailure.
- class MethodFailure removed, Failure as non-abstract class.
For a more comfortable ad hoc usage you can directly throw a newly
created Failure-object, each time
with an individual message text, but then without internationalization
possibility.
- Now its possible to redefine the method checkClass() in order to
modify or deactivate the checking of the naming conventions of the
descendants of Exc and Failure.
- class multex.Awt: After showing the stack trace scrolls upwards in
order to show its beginning.
- 1c of 2000-02-27:
- Internationalization of message texts is now optional.
You can activate it by initially calling
multex.MsgText.setInternationalization(true);
- Failure.Jdk1_1CauseGetter now knows java.sql.SQLException
- 1b of 2000-12-13:
- class multex.Awt: a) Now offers new methods reportNonmodal in order to
report into a non-modal dialog.
b) Now offers a new method report(Throwable),
which reports using an anomymous, shared, hidden Frame as owner.
- class multex.Msg: Now offers methods for reporting a) only the message
chain, b) only the compact stack trace, c) both in one.
- class multex.Failure:
- Enabled to encapsulate a cause of type Throwable rather than
only Exception.
- cause(Throwable) returns by default for all known exceptions of
JDK 1.1 with a causing exception this causing exception. The method
for getting the causing exception of an exception is configurable
by a call to Failure.setCauseGetter(...);
- Added function
Throwable originalException(Throwable i_throwable)
to get the original exception, which is i_throwable
itself or (may be indirectly) caused it.
- 1.1 of 2000-10-26 Reporting methods separated: Low level in
class Msg, onto sreen in class Awt.
- 1.0 of 2000-10-21 Big revolution.
- New convenience class MethodFailure. No longer 0..10
unnamed parameters in Failure-constructor.
- Each exception object has a default message text pattern, which is used,
if there is no corresponding message text found in file MsgText.properties or one of its
localized variants.
- New classes Assertion and Assertion.Failure
- Requires only JDK 1.1, no longer 1.2
- 0.2 of 2000-10-08 Failure extends java.lang.RuntimeException by default.
- 0.1 of 2000-09-29 Failure extends java.lang.Exception instead of
multex.Exc. Thus it is easily switchable to extends java.lang.RuntimeException.
Named parameters are the only parameters, that can be inserted into a
message text. Nevertheless for easiest providing of diagnostic information
in a Failure exception, the constructor of Failure accepts 0..10 unnamed
parameters of type Object.
- 0.0 of 1999..2000 Evolution of this framework. The name MulTEx was not yet used.
@author Christoph Knabe, TFH Berlin, 1999-2000 Copyrighted, but usable by GNU LGPL.