Exc (MulTEx 7.1: API documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

multex
Class Exc

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          multex.Exc

All Implemented Interfaces:: MultexException, java.io.Serializable

Direct Known Subclasses:: Util.MyDemoExc

public class Exc
extends java.lang.Exception
implements MultexException

Business rule exception (precondition violation) with parameters and internationalizable message text, and may be a cause. This class serves for the framework user as a base class for defining business rule exceptions. Objects directly of this class can be thrown, too, but such exceptions cannot be catched individually nor get internationalized.

Naming convention:

All user-defined exception classes derived from Exc should have a name ending in Exc. The pattern is:

    class ErrorconditionExc extends Exc { ... }

Parameters

All elements of the Object[] are considered positional parameters of this exception. The corresponding placeholders in the message text patterns have the syntax: {i} with i being the number of the parameter in the range 0..9.

The exception parameters can be substituted into the corresponding message text pattern in a desired locale format by class MsgText, which itself makes use of class java.text.MessageFormat.
See the usage examples Copy, AwtCopy, SwingCopy in directory demo.
Since MulTEx version 7 of 2006-05-06 you can pass many instances of Throwable as parameters. They will form an exception tree and are correctly reported by class Msg.

Relation to Standards

Class java.text.MesageFormat does much more in direction of internationalization than just to insert parameters into a message text pattern. You can e.g. specify different styles of formatting a parameter. E.g. formatting a parameter of type java.util.Date at position 0 could be done by the following parameter formatting directive: {0,date}.

Cause of a business rule exception

The class Exc does since MulTEx version 7 of 2006-05-06 provide a parameter cause in its constructor. In the rare case, you have got a cause of a business rule exception, you can provide it just like to a Failure.

Example

 //NIS-Authentication of userName:
 final String userData;
 try {
     userData = initialContext.lookup("system/passwd/"+userName).toString();
 } catch (final NameNotFoundException ex) {
     throw new multex.Exc("User name {0} unknown", ex, userName);
 }

Warning

Usually you get a causal exception only when performing the modification part of an operation. Such causal exceptions should be captured using a Failure.

Author:: Christoph Knabe, TFH Berlin, 1999-2005
See Also:: Serialized Form

Field Summary
`static java.lang.String`	`className` The unqualified name of this class

Constructor Summary
`Exc(java.lang.String i_defaultMessageTextPattern)` Convenience constructor null
`Exc(java.lang.String i_defaultMessageTextPattern, java.util.Collection i_parameters)` Convenience constructor with parameters as Collection.
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Object i_object0)` Convenience constructor 0
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Object[] i_parameters)` Constructs an Exc with a default message text pattern and exception parameters as an polymorphic Object[].
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Object i_object0, java.lang.Object i_object1)` Convenience constructor 1
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2)` Convenience constructor 2
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Object i_object0, java.lang.Object i_object1, java.lang.Object i_object2, java.lang.Object i_object3)` Convenience constructor 3
`Exc(java.lang.String i_defaultMessageTextPattern, 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
`Exc(java.lang.String i_defaultMessageTextPattern, 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
`Exc(java.lang.String i_defaultMessageTextPattern, 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
`Exc(java.lang.String i_defaultMessageTextPattern, 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
`Exc(java.lang.String i_defaultMessageTextPattern, 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
`Exc(java.lang.String i_defaultMessageTextPattern, 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
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause)` Convenience constructor null
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0)` Convenience constructor 0
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object[] i_parameters)` Constructs an Exc with a default message text pattern, a cause, and exception parameters as an polymorphic Object[].
`Exc(java.lang.String i_defaultMessageTextPattern, java.lang.Throwable i_cause, java.lang.Object i_object0, java.lang.Object i_object1)` Convenience constructor 1
`Exc(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
`Exc(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
`Exc(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
`Exc(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
`Exc(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
`Exc(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
`Exc(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
`Exc(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

Method Summary
`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.
`java.lang.Object[]`	`getParameters()` Returns a copy of the positional exception parameter array, or null if the exception does not have parameters.
`boolean`	`hasParameters()` Returns true, if the exception parameter array exists and has at least one element.
`void`	`printStackTrace()` Prints the chained, compact stack traces of this `Exc` object to the standard error stream System.err.
`void`	`printStackTrace(java.io.PrintStream io_printer)` Prints the chained, compact stack traces of this `Failure` object to io_printer.
`void`	`printStackTrace(java.io.PrintWriter io_printer)` Prints the chained, compact stack traces of this `Failure` object to io_printer.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface multex.MultexException

getCause

Field Detail

className

public static final java.lang.String className

The unqualified name of this class

See Also:: Constant Field Values

Constructor Detail

Exc

public Exc(java.lang.String i_defaultMessageTextPattern)

Convenience constructor null
See Also:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Object i_object0)

Convenience constructor 0
See Also:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Object i_object0,
           java.lang.Object i_object1)

Convenience constructor 1
See Also:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Object i_object0,
           java.lang.Object i_object1,
           java.lang.Object i_object2)

Convenience constructor 2
See Also:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           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:: Exc(String, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Object[] i_parameters)

Constructs an Exc with a default message text pattern and exception parameters as an polymorphic Object[].

Examples of defining an exception with parameters:

  public static class AuthorizationExc extends Exc {
    public AuthorizationExc(final String i_username, final String i_functionName){
      //use of convenience constructor:
      super("User {0} is not allowed to use function {1}.", i_username, i_functionName);
    }
  }
  public static class StartedExc extends Exc {
    public StartedExc(final String i_driver, final java.util.Date i_date){
      //use of parameter array constructor:
      super("Copy-driver {0}, version of {1,date} was started",
        new Object[]{i_driver,i_date}
      );
    }
  }

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_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.

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Throwable i_cause,
           java.lang.Object[] i_parameters)

Constructs an Exc with a default message text pattern, a cause, and exception parameters as an polymorphic Object[]. When to give a cause to an Exc is discussed in the class description.

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

   public static class UserUnknownExc extends Exc {
     public UserUnknownExc(
       final Throwable i_cause,
       final String    i_userName
     ){
       super("User ''{0}'' does not exist in this system.",
         i_cause, new Object[]{i_userName}
       );
     }
   }//UserUnknownExc

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 pattern shall only be taken from a ResourceBundle using the class name as key.

i_cause - The causing Throwable object for providing the diagnostics causer chain. null is allowed here, if no cause is available or necessary.

i_parameters - Exception parameters as a 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.

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Throwable i_cause)

Convenience constructor null
See Also:: Exc(String, Throwable, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.lang.Throwable i_cause,
           java.lang.Object i_object0)

Convenience constructor 0
See Also:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(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:: Exc(String, Throwable, Object[])

Exc

public Exc(java.lang.String i_defaultMessageTextPattern,
           java.util.Collection i_parameters)

Convenience constructor with parameters as Collection. You can use this as a List Exc, passing collected Throwables to i_parameters.
See Also:: Exc(String, Throwable, Object[])

Method Detail

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.:

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

hasParameters

public boolean hasParameters()

Description copied from interface: MultexException

Returns true, if the exception parameter array exists and has at least one element.

Specified by:: hasParameters in interface MultexException

getParameters

public java.lang.Object[] getParameters()

Description copied from interface: MultexException

Returns a copy of the positional exception parameter array, or null if the exception does not have parameters.

Specified by:: getParameters in interface MultexException

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

printStackTrace

public void printStackTrace()

Prints the chained, compact stack traces of this Exc object to the standard error stream System.err.

See Also:: printStackTrace(java.io.PrintWriter)

printStackTrace

public void printStackTrace(java.io.PrintStream io_printer)

Prints the chained, compact stack traces of this Failure object to io_printer.

See Also:: printStackTrace(java.io.PrintWriter)

printStackTrace

public void printStackTrace(java.io.PrintWriter io_printer)

Prints the chained, compact stack traces of this Failure object to io_printer.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

multex Class Exc

Naming convention:

Parameters

Relation to Standards

Cause of a business rule exception

Warning

className

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

Exc

getMessage

hasParameters

getParameters

getDefaultMessageTextPattern

printStackTrace

printStackTrace

printStackTrace

multex
Class Exc