com.sdm.quasar.client.core.common
Class ErrorHandler

java.lang.Object
  com.sdm.quasar.client.core.common.ErrorHandler

public class ErrorHandler

extends java.lang.Object

Offers static access to the global error handler.

While developing a dialog, errors should be processed locally as much as possible. That means, wherever possible an error should be analyzed and dealt with immediately in an appropriate way by the dialog's implementation, e.g. by resetting the dialog and notifying the user, or by correcting the error. From the outside, it is nearly impossible to determine, what 'appropriate' means.

Therefore, this ErrorHandler can only perform some damage control as a last resort. That is, if you are unable to handle the error in the implementation, you can call ErrorHandler#handleException(Object,Throwable) with a context object, that describes the context to abort.

You should call the method ErrorHandler#handleException(Object, Throwable) with the abort context when you are absolutely sure that any negative effects of the error are restricted to the specified context. If there is a ErrorContextHandler registered for that context, it can close the context; the remaining application can continue. A context can be e.g. a dialog; in this case the dialog and it's childs may be disposed and a portal can continue running.

Important: This is a last resort. You should try to handle as many errors in the dialog's implementation as possible to improve the user experience. In complex clients that may be simplified using a dialog based error handling scheme.

This class redirects calls to the registered ErrorContextHandlers, if they can handle the excepetion in the specified context. The ErrorContextHandler are asked ordered from the last added to the first added. So the last added ErrorContextHandler should be the most specific. It is guaranteed, that at least one ErrorContextHandler is registered - it can handle all contexts and alle exceptions by simply wrapping them in a RuntimeException, which will be thrown (which means, that this ErrorContextHandler actually does nothing). If an application likes to do some desaster handling, it should register at least an ErrorContextHandler, which takes any context and that does this desaster handling stuff. This must be done as early as possible as explaned above!

Version:

1.0

Author:

Thomas Wolf, Bernd Olleck

Method Summary

static void	abort() Aborts without any context.
static void	abort(java.lang.Object context) Aborts the context given.
static void	addErrorContextHandler(ErrorContextHandler errorContextHandler) Adds an ErrorContextHandler to this ErrorHandler.
static void	addUnhandledError(java.lang.Throwable e) Adds a given unhandled Throwable to the stack of currently unhandled errors.
static void	handleError(java.lang.Object context, java.lang.Throwable e) Handles the Throwable given.
static void	handleError(java.lang.Throwable e) Handles the Throwable given without any context.
static void	handleUnhandledErrors() Handles currently unhandled errors.
static boolean	hasUnhandledErrors() Returns true, iff there are stored unhandled errors at this ErrorHandler.
static void	removeErrorContextHandler(ErrorContextHandler errorContextHandler) Removes a previously registered ErrorContextHandler.
static void	removeUnhandledError(java.lang.Throwable e) Removes the given Throwable from the stack of currently unhandled errors.
static void	throwRuntimeException(java.lang.Throwable e) Converts the given Throwable to a RuntimeException and throws this RuntimeException.

Methods inherited from class java.lang.Object

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

Method Detail

abort

public static void abort()
                  throws java.lang.RuntimeException

Aborts without any context. This will lead to handling an AbortException.

Throws:

java.lang.RuntimeException - if an unhandled exception occures

abort

public static void abort(java.lang.Object context)
                  throws java.lang.RuntimeException

Aborts the context given. This will lead to handling an AbortException with the given context.

Parameters:

context - the context object (may be null)

Throws:

java.lang.RuntimeException - if an unhandled exception occures

handleError

public static void handleError(java.lang.Throwable e)
                        throws java.lang.RuntimeException

Handles the Throwable given without any context.

Parameters:

e - the Throwable to handle (null means, a new AbortException will be used)

Throws:

java.lang.RuntimeException - if an unhandled exception occures

handleError

public static void handleError(java.lang.Object context,
                               java.lang.Throwable e)
                        throws java.lang.RuntimeException

Handles the Throwable given. This will be done by the registered ErrorContextHandler. To allow them to shutdown as few as possible of the application, the caller should specify a context object, that specifies the part of the application that at least must be shut down. The caller must be shure, that the exception given cannot corrupt any other part of the application! A context of null is threaded as no context - so this is a last resort desaster handling!

Parameters:

context - the context object (may be null)

e - the Throwable to handle (null means, a new AbortException will be used)

Throws:

java.lang.RuntimeException - if an unhandled exception occures

throwRuntimeException

public static void throwRuntimeException(java.lang.Throwable e)
                                  throws java.lang.RuntimeException

Converts the given Throwable to a RuntimeException and throws this RuntimeException. This is done the following way:

1. If the given Throwable is a RuntimeException, that RuntimeException will be thrown directly,
2. if the given Throwable is an Error, that Error will be thrown directly,
3. Otherwise a wrapping RuntimeException is created, which has the orgin. Throwable as nested exception.

Parameters:

e - the Throwable to convert to RuntimeException

Throws:

java.lang.RuntimeException - the converted RuntimeException

addErrorContextHandler

public static void addErrorContextHandler(ErrorContextHandler errorContextHandler)

Adds an ErrorContextHandler to this ErrorHandler.

Note: Order is important here: The least adedd ErrorContextHandler should be the most specific one! If an ErrorContextHandler has references to other objects (which is normal) it is important to remove this ErrorContextHandler, when the context it controls is disposed. Otherwise we have a huge memory leak, because ErrorHandler is a static class!

Parameters:

errorContextHandler - a new ErrorContextHandler, that can handle errors in a special context

removeErrorContextHandler

public static void removeErrorContextHandler(ErrorContextHandler errorContextHandler)

Removes a previously registered ErrorContextHandler.

Parameters:

errorContextHandler - the ErrorContextHandler to remove

hasUnhandledErrors

public static boolean hasUnhandledErrors()

Returns true, iff there are stored unhandled errors at this ErrorHandler.

addUnhandledError

public static void addUnhandledError(java.lang.Throwable e)

Adds a given unhandled Throwable to the stack of currently unhandled errors.

Parameters:

e - the unhandled error as Throwable to add

removeUnhandledError

public static void removeUnhandledError(java.lang.Throwable e)

Removes the given Throwable from the stack of currently unhandled errors.

Parameters:

e - the error as Throwable to remove

handleUnhandledErrors

public static void handleUnhandledErrors()
                                  throws java.lang.RuntimeException

Handles currently unhandled errors. If the handling of the first of the unhandled errors leads to a RuntimeException, this exception will be thrown here (but the according unhandled error is removed from the list of unhandled errors).

Throws:

java.lang.RuntimeException - if an unhandled exception occures