Package multex

MulTEx - the Multi-Tier Exception Handling Framework.

See:
Description

Interface Summary

AwtExceptionHandler	Used for handling otherwise uncaught RuntimeException / Error in AWT/Swing.
CauseGetter	Describes, how to get the causing exception of a caused Throwable, which is not a subclass of Failure
MultexException	Marks an exception as to be handled especially by MsgText.

Class Summary

Assertion	Tool for checking unexpected programming errors
Awt	Services for reporting onto AWT Dialogs the messages for any exception with dynamic or static or no internationalization.
Msg	Services for low-level reporting of any exception.
MsgText	Services for getting the message text for exceptions.
ReflectionCauseGetter	Describes, how to get the causing exception of any non-MulTEx-exception in any JDK supporting reflection.
Swing	Services for reporting onto Swing dialogs the messages for any exception with dynamic or static or no internationalization.
Util	Utilities for MulTEx.

Exception Summary

AssertionFailure	Indicates that an assertion failed.
Exc	Problem-related exception with parameters and internationalizable message text.
Failure	Indirectly caused exception with parameters, causal chain and internationalizable message text.

Package multex Description

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 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)

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/
2. 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.
3. 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.
4. 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().
5. 2005-01-13 Include private attributes of type Throwable into the 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

• 6b of 2005-04-26 Added User's Guide documenting, how to introduce MulTEx. Main chapter: How to assure centralized exception handling.
• 6a of 2005-04-14 Added method Awt.setAwtExceptionHandlerClass(multex.AwtExceptionHandler) 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 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 ReflectionCauseGetter instead of leaving this to Throwable.printStackTrace().
  Restriction: Now needs JRE >= 1.4, which exits already >= 3 years.
  Incompatible: Much utility functionality moved from class Failure to the new class 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 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 Msg for printing the stack trace of a Throwable chain, report a null Throwable instead of throwing NullPointerException.
  Improvement: The methods in class 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 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 Msg.printReport(StringBuffer, Throwable, ResourceBundle) now passes its ResourceBundle to multex.Msg.printMessages(...).
  Bug avoiding: Now Awt and 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 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 Swing for reporting into a Swing dialog with dynamic or static internationalization. Interface of class Awt simplified (incompatible change) and made uniform with Swing.
  Added method 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 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 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 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.