oracle.javatools.dialogs
Class ExceptionDialog

java.lang.Object
  oracle.javatools.dialogs.ExceptionDialog

public class ExceptionDialog

extends java.lang.Object

Dialog to display an exception and optional message to the user. The dialog includes a Details button which can display a stack trace, or a list of stack traces (for "chained" exceptions such as SQLException).

In general, when runtime exceptions occur in the IDE or in extensions, this dialog should be used in preference to printing the stack trace to the console or using Assert.printStackTrace(). It's important for diagnostic purposes that users have information they can provide to support to help pinpoint problems. In addition, the use of this dialog helps extension developers to identify problems while developing extension code.

Whenever event handling code is written that may cause a RuntimeException to be thrown on the AWT event thread, it should be surrounded by a try/catch block like the following:

   public void actionPerformed(ActionEvent ae)
   {
     try
     {
       doSomething();
     }
     catch (RuntimeException re)
     {
       // Use the "messageless" version, which reports as an "internal
       // error"
       ExceptionDialog.showExceptionDialog( parent, re );
     }
   }
 

Important: do not invoke the exception dialog in code that is called from paint(), including Swing component renderers. Doing so may result in the user being unable to dismiss the dialog. In addition, certain components have listeners which are notified in a way that is not compatible with using this dialog. For instance, list, tree or table selection events may be fired several times.

By default, the exception dialog has message text and an associated help topic that indicate that the error was an internal or unexpected error. For consistency, this should be the default error message for runtime exceptions that are not otherwise handled.

In addition to reporting "internal errors", the exception dialog can be used as a general error reporting mechanism where the stack trace may be of interest to the user. It should be used sparingly for this purpose. Often the stack trace is irrelevant and should not be displayed. Using the exception dialog in such circumstances can lead to a "fear factor"; the user is used to this particular dialog being used for internal errors and may misinterpret the severity of your error message. In most cases, consider using the MessageDialog to display a plain alert.

The exception dialog has built in support for chained SQLExceptions. You can also provide an implementation of ThrowableChainTraverser and call the registerThrowableChainTraverser() to handle other types of chained exception.

Note: This dialog handles ThreadDeath specially. ThreadDeath exceptions are never reported; the showExceptionDialog() methods will immediately throw the exception back out if it is an instance of ThreadDeath.

See Also:

MessageDialog, Frame, Exception, SQLException

Nested Class Summary

static interface

ExceptionDialog.ThrowableChainTraverser An interface describing how to traverse a chain of exceptions

Method Summary

protected java.util.List	getThrowableChain(java.lang.Throwable t)
protected boolean	isChainedThrowable(java.lang.Throwable t) Return true if the specified throwable is chaied.
static void	registerThrowableChainTraverser(java.lang.Class exceptionClass, ExceptionDialog.ThrowableChainTraverser tct) Register a ThrowableChainTraverser with the ExceptionDialog utility.
static void	showExceptionDialog(java.awt.Component parent, java.lang.Throwable t) Show an exception dialog based on a component and a throwable.
static void	showExceptionDialog(java.awt.Component parent, java.lang.Throwable t, java.lang.String message) Show an exception dialog with a message
static void	showExceptionDialog(java.awt.Component parent, java.lang.Throwable t, java.lang.String title, java.lang.String message, java.lang.String helpTopicID) Preferred method for invoking the exception dialog.
static int	showExceptionDialog(java.awt.Window parent, java.lang.Exception ex) Displays an Exception dialog to the user.
static int	showExceptionDialog(java.awt.Window parent, java.lang.Exception ex, java.lang.String message) Displays an exception dialog to the user.
static int	showExceptionDialog(java.awt.Window parent, java.lang.Exception ex, java.lang.String title, java.lang.String message) Displays an Exception dialog to the user.
static void	unregisterThrowableChainTraverser(ExceptionDialog.ThrowableChainTraverser tct) Unregister ThrowableChainTraverser

Methods inherited from class java.lang.Object

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

Method Detail

showExceptionDialog

public static void showExceptionDialog(java.awt.Component parent,
                                       java.lang.Throwable t)

Show an exception dialog based on a component and a throwable.

Parameters:

parent - the parent component of the dialog

t - an exception to report

showExceptionDialog

public static void showExceptionDialog(java.awt.Component parent,
                                       java.lang.Throwable t,
                                       java.lang.String message)

Show an exception dialog with a message

Parameters:

parent - the parent component of the dialog

t - an exception to report

showExceptionDialog

public static void showExceptionDialog(java.awt.Component parent,
                                       java.lang.Throwable t,
                                       java.lang.String title,
                                       java.lang.String message,
                                       java.lang.String helpTopicID)

Preferred method for invoking the exception dialog.

Parameters:

t - Throwable to display in dialog

title - title bar caption for the dialog

message - Text message to display to the user in addition to the exception text.

helpTopicID - a help topic ID to attach to the help button of the exception dialog.

showExceptionDialog

public static int showExceptionDialog(java.awt.Window parent,
                                      java.lang.Exception ex,
                                      java.lang.String title,
                                      java.lang.String message)

Displays an Exception dialog to the user.

Parameters:

parent - Frame that this dialog will be parented upon

ex - Exception to display in dialog

title - title bar caption for the dialog

message - Text message to display to the user in addition to the exception text.

showExceptionDialog

public static int showExceptionDialog(java.awt.Window parent,
                                      java.lang.Exception ex,
                                      java.lang.String message)

Displays an exception dialog to the user. The title is defaulted to the application name.

Parameters:

parent - Frame that this dialog will be parented upon

ex - Exception to display in dialog

message - Text message to display to the user in addition to the exception text.

showExceptionDialog

public static int showExceptionDialog(java.awt.Window parent,
                                      java.lang.Exception ex)

Displays an Exception dialog to the user.

Parameters:

parent - Frame/Dialog that this dialog will be parented upon

ex - Exception to display in dialog

registerThrowableChainTraverser

public static void registerThrowableChainTraverser(java.lang.Class exceptionClass,
                                                   ExceptionDialog.ThrowableChainTraverser tct)

Register a ThrowableChainTraverser with the ExceptionDialog utility. You can use this to handle chained exceptions.

unregisterThrowableChainTraverser

public static void unregisterThrowableChainTraverser(ExceptionDialog.ThrowableChainTraverser tct)

Unregister ThrowableChainTraverser

isChainedThrowable

protected boolean isChainedThrowable(java.lang.Throwable t)

Return true if the specified throwable is chaied.

getThrowableChain

protected java.util.List getThrowableChain(java.lang.Throwable t)