/Users/richardallenbair/Documents/Source/Projects/nonsense/swingx/src/beaninfo/JXErrorDialog_API.java |
package org.jdesktop.swingx; /** * <p>JXErrorDialog is a common error dialog suitable for displaying information * about errors, warnings, and exceptional behavior in an application to users. * The common usage scenario for <code>JXErrorDialog</code> is to show collected * data about some incident (such as an <code>Exception</code> to the user. You * may also want to configure the <code>JXErrorDialog</code> to allow the user * to take one of several actions, including sending an error report via email * or some other means.</p> * * <p>Data about each incident is encapsulated in the {@link IncidentInfo} class. * JXErrorDialog displays each property of the <code>IncidentInfo</code> in a * specific way: * <ul> * <li><code><b>header: </b></code> becomes the title of the * <code>JXErrorDialog</code></li> * <li><code><b>basicErrorMessage: </b></code> the main message in the error * dialog</li> * <li><code><b>detailedErrorMessage: </b></code> if non null, then a button * will be displayed allowing the user to view details. Details are shown * in a component capable of rendering simply HTML.</li> * <li><code><b>errorException: </b></code> if non null and * <code>detailedErrorMessage</code> is null, then this will form the * <code>detailedErrorMessage</code>. The "details" button will be shown * the same as noted above.</li> * <li><code><b>errorLevel: </b></code> if <code>Level.SEVERE</code> then the * error icon will be shown, otherwise a warning icon will be shown.</li> * </ul></p> * * <p>Because <code>JXErrorDialog</code> is a Java Bean, it may be instantiated * and properties can be modified on the dialog prior to showing the dialog. For * example, if you wanted to modify the icon that was shown with a particular * instance of a <code>JXErrorDialog</code> prior to showing an error, you might * do the following: * <pre><code> * //myWindow is the JFrame/JDialog that is going to be the * //"parent" for the JXErrorDialog * JXErrorDialog dlg = new JXErrorDialog(myWindow); * dlg.setErrorIcon(myErrorIcon); * dlg.setIncidentInfo(new IncidentInfo("Fatal Error", exception)); * dlg.pack(); * dlg.setVisible(true); * </code></pre></p> * * <p>Several static methods are included as part of the JXErrorDialog API to * simplify showing errors. These methods are convenient to use from within * catch blocks. For example: * <pre><code> * try { * //do stuff.... something throws an exception in here * } catch (Exception e) { * JXErrorDialog.showDialog(myWindow, "Fatal Error", e); * } * </code></pre></p> * * <p>While this is the simpliest usage, it is not the recommended approach for * most errors since it yields the most obtuse messages for users. Users * should not be presented with details that include a stack trace! Instead, you * should provide a more useful message to users. For example, if I were creating * a URL (which may cause a MalformedURLException): * <pre><code> * URL url = null; * try { * url = new URL(userSuppliedUrl); * } catch (MalformedURLException e) { * String msg = "The web resource you entered is not formatted" * + " correctly."; * String details = "&th;html>Web resources should begin with \"http://\"" * + " and cannot contain any spaces. Below are a few" * + " more guidelines.<ul>" * + getURLGuidelines() * + "</ul>&th;/html>"; * JXErrorDialog.showDialog(myWindow, "Unknown Resource", msg, details, e); * return false; * } * </code></pre></p> * * <p><code>JXErrorDialog may also be configured with a "Report" button which allows * the user to send a bug report, typically through email. This is done through * the pluggable {@link ErrorReporter} class. Simply instantiate {@link LogErrorReporter}, * {@link JdicEmailErrorReporter}, {@link JavaEmailErrorReporter}, or some custom * subclass of <code>ErrorReporter</code> and pass the <code>ErrorReporter</code> * instance into the {@link #setErrorReporter} method.</p> * * @author Richard Bair * @author Alexander Zuev * @author Shai Almog */ public class JXErrorDialog extends JDialog { //--------------------------------------------------------- constructors /** * Create a new <code>JXErrorDialog</code>. */ public JXErrorDialog(); /** * Create a new <code>JXErrorDialog</code> with the given <code>Frame</code> * as the owner. * * @param owner Owner of this error dialog. */ public JXErrorDialog(Frame owner); /** * Create a new <code>JXErrorDialog</code> with the given <code>Dialog</code> * as the owner. * * @param owner Owner of this error dialog. */ public JXErrorDialog(Dialog owner); //-------------------------------------------- public methods/properties /** * Sets the IncidentInfo for this dialog * * @param info IncidentInfo that incorporates all the details about the error */ public void setIncidentInfo(IncidentInfo info); /** * Gets the <code>JXErrorDialog</code>'s <code>IncidentInfo</code> * * @return <code>IncidentInfo</code> assigned to this dialog */ public IncidentInfo getIncidentInfo(); /** * Sets the <code>ErrorReporter</code> to use with this instance of * <code>JXErrorDialog</code>. * If not specified, the default error reporter is used (as specified * by the setDefaultErrorReporter() static method) which by default is * null. * * @param rep the error reporter to use. May be null. */ public void setErrorReporter(ErrorReporter rep); /** * Returns the error reporter in use with this instance of <code>JXErrorDialog.</code> * * @return the ErrorReporter in use. May be null */ public ErrorReporter getErrorReporter(); /** * Specifies the icon to use if the IncidentInfo is Level.SEVERE * * @param icon the Icon to use. May be null. */ public void setErrorIcon(Icon icon); /** * Returns the Icon in use if the IncidentInfo is Level.SEVERE * * @return the Icon */ public Icon getErrorIcon(); /** * Specifies the icon to use if the IncidentInfo is not Level.SEVERE * * @param icon the Icon to use. May be null. */ public void setWarningIcon(Icon icon); /** * Returns the Icon in use if the IncidentInfo is not Level.SEVERE * * @return the Icon */ public Icon getWarningIcon(); /** * Sets the Action that will be executed to report an error/warning. * * @param action The Action to execute if the user attempts to report a problem */ public void setReportAction(Action action); /** * @return the Action that is executed if the user attempts to report a problem */ public Action getReportAction(); //------------------------------------------------------- static methods /** * Constructs and shows the error dialog for the given exception. The exceptions message will be the * errorMessage, and the stacktrace will be the details. * @param owner Owner of this error dialog. Determines the Window in which the dialog * is displayed; if the <code>owner</code> has * no <code>Window</code>, a default <code>Frame</code> is used * @param title Title of the error dialog * @param e Exception that contains information about the error cause and stack trace */ public static void showDialog(Component owner, String title, Throwable e); /** * Constructs and shows the error dialog for the given exception. The exceptions message is specified, * and the stacktrace will be the details. * @param owner Owner of this error dialog. Determines the Window in which the dialog * is displayed; if the <code>owner</code> has * no <code>Window</code>, a default <code>Frame</code> is used * @param title Title of the error dialog * @param errorMessage Message for the error dialog * @param e Exception that contains information about the error cause and stack trace */ public static void showDialog(Component owner, String title, String errorMessage, Throwable e); /** * Show the error dialog. * @param owner Owner of this error dialog. Determines the Window in which the dialog * is displayed; if the <code>owner</code> has * no <code>Window</code>, a default <code>Frame</code> is used * @param title Title of the error dialog * @param errorMessage Message for the error dialog * @param details Details to be shown in the detail section of the dialog. This can be null * if you do not want to display the details section of the dialog. */ public static void showDialog(Component owner, String title, String errorMessage, String details); /** * Show the error dialog. * @param owner Owner of this error dialog. Determines the Window in which the dialog * is displayed; if the <code>owner</code> has * no <code>Window</code>, a default <code>Frame</code> is used * @param title Title of the error dialog * @param errorMessage Message for the error dialog * @param details Details to be shown in the detail section of the dialog. This can be null * if you do not want to display the details section of the dialog. * @param e Exception that contains information about the error cause and stack trace */ public static void showDialog(Component owner, String title, String errorMessage, String details, Throwable e); /** * Show the error dialog. * @param owner Owner of this error dialog. Determines the Window in which the dialog * is displayed; if the <code>owner</code> has * no <code>Window</code>, a default <code>Frame</code> is used * @param title Title of the error dialog * @param errorMessage Message for the error dialog */ public static void showDialog(Component owner, String title, String errorMessage); /** * Show the error dialog. * @param owner Owner of this error dialog. Determines the Window in which the dialog * is displayed; if the <code>owner</code> has * no <code>Window</code>, a default <code>Frame</code> is used * @param info <code>IncidentInfo</code> that incorporates all the information about the error */ public static void showDialog(Component owner, IncidentInfo info); /** * Returns the current reporting engine that will be used to report a problem if * user clicks on 'Report' button or <code>null</code> if no reporting engine set. * * @return reporting engine */ public static ErrorReporter getDefaultErrorReporter(); /** * Set reporting engine which will handle error reporting if user clicks 'report' button. * * @param rep <code>ErrorReporter</code> to be used or <code>null</code> to turn reporting facility off. */ public static void setDefaultErrorReporter(ErrorReporter rep); }