BasicException (openMDX/Core API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.openmdx.kernel.exception
Class BasicException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          org.openmdx.kernel.exception.BasicException

All Implemented Interfaces:: Serializable, MultiLineStringRepresentation

Direct Known Subclasses:: StackedException

public class BasicException
extends Exception
implements MultiLineStringRepresentation
extends Exception
implements MultiLineStringRepresentation

The StackedException implements stackable exceptions. Stackable exceptions are useful to avoid hidden exceptions and to allow for remapping exceptions while keeping the complete exception stack.

Instead of defining a central resource defining error codes the StackedException follows the approach of a decentralized error code management using error domains. An organization may define as many error domains as required. Each error domain defines it's own error codes as positive values starting with the value of '1'. An error code itself is not unique, uniqness is only achieved together with an error domain.

To simplify things a number of common error codes are defined that are are shared within all error domains. These error codes have negative values. The StackedException provides error code mappers to map error codes from foreign domains to strings. This mappers are used when requesting a stringified form of the exception.

To enable interoperation with application domain specific exceptions exception mappers are used to convert foreign exceptions to stacked exceptions. These mappers are implicitely called when creating a new StackedException passing an embedded exception that is not of type StackedException.

A sample demonstrating the application of exception mappers in Corba applications:

    Corba Server                         Corba Client
    -----------------------------------  -----------------------------------
    :    :
    1) throw StackedException
    2) convert to Corba User Exception
    3) throw Corba User Exception

                                          4) catch Corba User Exception
                                          5) create StackedException passing
                                             the Corba Exception -> invokes
                                             the Corba Exception mapper
                                          6) throw StackException
                                          :    :

Each StackedException provides several information elements:

an error domain
an error code
exception parameters
a description
an embedded exception (optionally)

Do not make subclasses: BasicException will be final as soon as the deprecated package org.openmdx.compatibility.base.exception has been removed!

See Also:: Serialized Form

Nested Class Summary
`static class`	`BasicException.Code`
`static interface`	`BasicException.Mapper` An `Mapper` implementation maps foreign exceptions to `BasicException`s.
`static class`	`BasicException.Parameter` The Parameter class represents a name-value pair.
`static interface`	`BasicException.Wrapper` The interface `Wrapper` defines an exception as a wrapping exception that wraps a cause (a `BasicException`)

Field Summary
`static boolean`	`isMicrosoftVM` The `isMicrosoftVM` property is set to true if the currently active Java VM is a Microsoft Java VM.

Constructor Summary
`BasicException(String exceptionDomain, int exceptionCode, BasicException.Parameter[] parameters, String description)` Creates a new `BasicException`.
`BasicException(String className, String methodName, int lineNr, String exceptionDomain, int exceptionCode, BasicException.Parameter[] parameters, String description, String[] callStack, Date timestamp)` Creates a new `BasicException`.
`BasicException(Throwable throwable, String exceptionDomain, int exceptionCode, BasicException.Parameter[] parameters, String description)` Creates a new `BasicException`.
`BasicException(Throwable throwable, String exceptionDomain, int exceptionCode, BasicException.Parameter[] parameters, String description, Throwable that)` Creates a new `BasicException`.
`BasicException(Throwable throwable, String className, String methodName, int lineNr, String exceptionDomain, int exceptionCode, BasicException.Parameter[] parameters, String description, String[] callStack, Date timestamp)` Creates a new `BasicException`.

Method Summary
`Throwable`	`appendCause(Throwable throwable)` Appends the specified throwable to the end of the exception stack of this `BasicException`
`static List`	`breakupDescription(String description)` Breaks up an exception description into simple text lines
`static String[]`	`breakupStackTrace(Throwable throwable)` Breaks a stack trace of a throwable up into single entries, removes the leading 'at' and trims whitespaces.
`String[]`	`getCallStack()` Retrieves the stack trace for this `BasicException` toplevel object.
`Throwable`	`getCause()` Returns the cause.
`BasicException`	`getCause(String exceptionDomain)` Returns the cause belonging to a specific exception domain.
`String`	`getClassName()` Retrieves the class for this `BasicException` object.
`String`	`getDescription()` Retrieves the context for this `BasicException` toplevel object.
`int`	`getExceptionCode()` Retrieves the exception code for this `BasicException` toplevel object.
`String`	`getExceptionCodeString()` Retrieves the exception code for this `BasicException` toplevel object.
`String`	`getExceptionDomain()` Retrieves the domain for this `BasicException` toplevel object.
`List`	`getExceptionStack()` Returns the exception stack as a list of exceptions beginning with the first thrown exception.
`int`	`getLineNr()` Retrieves the line number for this `BasicException` object.
`String`	`getMethodName()` Retrieves the method for this `BasicException` object.
`String`	`getParameter(String name)` Searches for the parameter with the specified name in the parameter list.
`BasicException.Parameter[]`	`getParameters()` Retrieves the parameters for this `BasicException` toplevel object.
`Date`	`getTimestamp()` Retrieves the timestamp for this `BasicException` toplevel object.
`Throwable`	`initCause(Throwable throwable)` Initializes the cause of this throwable to the specified value.
`static HashMap`	`parseStackTraceEntry(String[] stackTrace, int index)` Parse a single stack trace line into its elements.
`void`	`printStack(Throwable holder, PrintStream stream, boolean addBacktrace)` Prints the exception including all stacked exceptions to the specified print stream.
`void`	`printStack(Throwable holder, PrintWriter writer, boolean addBacktrace)` Prints the exception including all stacked exceptions to the specified print writer.
`static void`	`register(Class exClass, BasicException.Mapper mapper)` Registers an exception mapper for a given exception class
`static void`	`register(String exceptionDomain, IntegerEnumeration.Mapper mapper)` Registers an error code mapper for a given exception domain
`static void`	`setSource(Object source)` Set an exception source object.
`static BasicException`	`toStackedException(Throwable throwable)` Maps a throwable to a `BasicException` using the registered exception mappers
`static BasicException`	`toStackedException(Throwable cause, Throwable wrapper)` Create a `BasicException` representing a `cause` wrapped into a `wrapper`.
`static BasicException`	`toStackedException(Throwable cause, Throwable wrapper, BasicException.Parameter[] parameters)` Create a `BasicException` representing a `cause` wrapped into a `wrapper`.
`String`	`toString()` Returns a formatted multiline String representation for the exception including all stacked exceptions.
`String`	`toString(boolean addBacktrace)` Returns a formatted multiline String representation for the exception including all stacked exceptions.
`String`	`toStringTopLevel()` Returns a String representation for the exception's top level object.
`String`	`toStringTopLevel(boolean addBacktrace)` Returns a String representation for the exception's top level object.

Methods inherited from class java.lang.Throwable
`fillInStackTrace, getLocalizedMessage, getMessage, getStackTrace, printStackTrace, printStackTrace, printStackTrace, setStackTrace`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

isMicrosoftVM

public static final boolean isMicrosoftVM

The isMicrosoftVM property is set to true if the currently active Java VM is a Microsoft Java VM.

Constructor Detail