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 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 onto streams and screens
- 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.
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.
- 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. Do some analogous for class Action in JSP/Struts.
- 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.
- 2002-07-02 Include private attributes of type Throwable into the
{@link multex.ReflectionCauseGetter} in order to get the cause for
exceptions like java.rmi.ConnectException, which do not have a cause
getter before JDK 1.4.
Version history
- 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.Failure#getContainedException(java.lang.Throwable,java.lang.Class)}
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 {@link 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