oracle.ide.dialogs
Class ExceptionDialog

java.lang.Object
  oracle.ide.dialogs.ExceptionDialog

public final class ExceptionDialog
extends java.lang.Object

NOTE: most of the methods in this class are deprecated. You should use oracle.javatools.dialogs.ExceptionDialog instead.

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

Constructor Summary

ExceptionDialog()

Method Summary

static void	showExceptionDialog(java.awt.Component parent, java.lang.Throwable t, java.lang.String title, java.lang.String message, java.lang.String helpTopicID) Deprecated. use oracle.javatools.dialogs.ExceptionDialog
static void	showExceptionDialog(Context context, java.lang.Throwable t) Show an exception dialog based on an IDE context and a throwable.
static void	showExceptionDialog(Context context, java.lang.Throwable t, java.lang.String message) Show an exception dialog based on an IDE context and a throwable.
static void	showExceptionDialog(Context context, java.lang.Throwable t, java.lang.String title, java.lang.String message, java.lang.String helpTopicID) Show an exception dialog based on an IDE context and a throwable.
static int	showExceptionDialog(java.awt.Window parent, java.lang.Exception ex) Deprecated. use oracle.javatools.dialogs.ExceptionDialog
static int	showExceptionDialog(java.awt.Window parent, java.lang.Exception ex, java.lang.String message) Deprecated. use oracle.javatools.dialogs.ExceptionDialog
static int	showExceptionDialog(java.awt.Window parent, java.lang.Exception ex, java.lang.String title, java.lang.String message) Deprecated. use oracle.javatools.dialogs.ExceptionDialog

Methods inherited from class java.lang.Object

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

Constructor Detail

ExceptionDialog

public ExceptionDialog()

Method Detail

showExceptionDialog

public static void showExceptionDialog(Context context,
                                       java.lang.Throwable t)

Show an exception dialog based on an IDE context and a throwable. If the context has a view, and the view has a GUI, that is used as the parent of the dialog.

Parameters:

context - an IDE context

t - the exception to report

showExceptionDialog

public static void showExceptionDialog(Context context,
                                       java.lang.Throwable t,
                                       java.lang.String message)

Show an exception dialog based on an IDE context and a throwable. If the context has a view, and the view has a GUI, that is used as the parent of the dialog.

Parameters:

context - an IDE context

t - the exception to report

message - the message to display

showExceptionDialog

public static void showExceptionDialog(Context context,
                                       java.lang.Throwable t,
                                       java.lang.String title,
                                       java.lang.String message,
                                       java.lang.String helpTopicID)

Show an exception dialog based on an IDE context and a throwable. If the context has a view, and the view has a GUI, that is used as the parent of the dialog.

Parameters:

context - an IDE context

t - the exception to report

title - the title bar caption for the exception dialog

message - the message to display in the dialog

helpTopicID - the help topic ID for the dialog. May be null.

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)

Deprecated. use oracle.javatools.dialogs.ExceptionDialog

Preferred method for invoking the exception dialog.

Parameters:

component - component that this dialog will be parented upon

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)

Deprecated. use oracle.javatools.dialogs.ExceptionDialog

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)

Deprecated. use oracle.javatools.dialogs.ExceptionDialog

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)

Deprecated. use oracle.javatools.dialogs.ExceptionDialog

Displays an Exception dialog to the user.

Parameters:

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

ex - Exception to display in dialog