Package multex

MulTEx - the Multi-Tier Exception Handling Framework.

See:
Description

Interface Summary

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

AllTests
Assertion	Tool for checking unexpected programming errors
Awt	Services for reporting onto AWT windows the messages for any exception.
ExceptionChainTest
Jdk1_1CauseGetter	Describes, how to get the causing exception of any exception in JDK 1.1 with an accessible causing exception.
Jdk1_4CauseGetter	Deprecated. Compiles only on JDK 1.4 and is then the most efficient solution for getting the cause of an exception.
Jdk1_4ExceptionChainTest
Msg	Services for low-level reporting of any exception.
MsgTest
MsgText	Services for getting the message text for exceptions.
MsgTextTest
MultexLocale	Packages all locale specific adjustments for dynamic internationalization.
ReflectionCauseGetter	Describes, how to get the causing exception of any non-MulTEx-exception in any JDK supporting reflection.

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 in the case of indirectly caused exceptions
• Internationalized message texts and parameters for exceptions
• Services for reporting exceptions onto streams and screens
• A standard way for writing method bodies with regard to exceptions

For introductory information you should first read the technical paper.

This package will still work correctly, if it is renamed, but you should not put classes of this package into different packages.

Naming conventions

The following naming conventions are used throughout the package multex.

• i_name for in-parameters of methods
• o_name for out-parameters of methods
• io_name for in/out-parameters of methods
• _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.
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. Do some analogous for class Action in JSP/Struts.
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. 2000-10-25 A class Swing for reporting into a Swing dialog rather than an Awt dialog should be created.
5. 2002-07-02 Include private attributes of type Throwable into the 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

• 4 of 2003-05-22: With dynamic internationalization as for web servers. The new class 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,MultexLocale,String).
• 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.