/Users/richardallenbair/Documents/Source/Projects/nonsense/swingx/src/beaninfo/IncidentInfo_API.java |
package org.jdesktop.swingx.error; /** * A simple class that encapsulates all the information needed * to report a problem to the automated report/processing system. * * @author Alexander Zuev * @author rbair * @version 1.4 */ public class IncidentInfo { /** * Creates a new IncidentInfo based on the provided data. * * @param header used as a quick reference for the * incident (for example, it might be used as the * title of an error dialog or as the subject of * an email message). Must not be null. * * @param basicErrorMessage short description of the problem. May be null * only if <code>errorException</code> is not null. * * @param detailedErrorMessage full description of the problem. It is recommended, * though not required, that this String contain HTML * to improve the look and layout of the detailed * error message. May be null. * * @param category A category name, indicating where in the application * this incident occurred. It is recommended that * this be the same value as you would use when logging. * This may be null. * * @param errorException <code>Throwable</code> that can be used as a * source for additional information such as call * stack, thread name, etc. May be null. If null, * then <code>basicErrorMessage</code> must not * be null. * * @param errorLevel any Level (Level.SEVERE, Level.WARNING, etc). * If null, then the level will be set to SEVERE. * * @throws NullPointerException if both <code>basicErrorMessage</code> * and errorException are null, or * <code>header</code> is null. */ public IncidentInfo(String header, String basicErrorMessage, String detailedErrorMessage, String category, Throwable errorException, Level errorLevel); /** * Creates a new <code>IncidentInfo</code> based on the provided data. * <code>basicErrorMessage</code> must not be null. * * @param header used as a quick reference for the * incident (for example, it might be used as the * title of an error dialog or as the subject of * an email message). Must not be null. * * @param basicErrorMessage short description of the problem. Must not be null. * * @param detailedErrorMessage full description of the problem. It is recommended, * though not required, that this String contain HTML * to improve the look and layout of the detailed * error message. May be null. * * @throws NullPointerException if <code>basicErrorMessage</code> or * <code>header</code> is null */ public IncidentInfo(String header, String basicErrorMessage, String detailedErrorMessage); /** * Creates a new <code>IncidentInfo</code> based on the specified * <code>Throwable</code>. This constructor should not normally be used for * anticipated exceptions, since the resulting <code>basicErrorMessage</code> * and <code>detailedErrorMessage</code> will be very technical, and may * not provide much help to the user. Use this constructor for unexpected errors * that nonetheless need to be handled by the user. * * @param header used as a quick reference for the * incident (for example, it might be used as the * title of an error dialog or as the subject of * an email message). Must not be null. * * @param errorException <code>Throwable</code> that can be used as a * source for additional information such as call * stack, thread name, etc. Must not be null. * * @throws NullPointerException if both <code>header</cod> and * <code>errorException</code> is null. */ public IncidentInfo(String header, Throwable errorException); /** * Gets the string to use for a dialog title or other quick reference. Used * as a quick reference for the incident. For example, it might be used as the * title of an error dialog or as the subject of an email message. This value * will never be null. * * @return quick reference String */ public String getHeader(); /** * <p>Gets the basic error message. This message should be clear and user oriented. * This String may have HTML formatting, but any such formatting should be used * sparingly. Generally, such formatting makes sense for making certain words bold, * but should not be used for page layout or other such things.</p> * * <p>For example, the following are perfectly acceptable basic error messages: * <pre> * "Your camera cannot be located. Please make sure that it is powered on * and that it is connected to this computer. Consult the instructions * provided with your camera to make sure you are using the appropriate * cable for attaching the camera to this computer" * * "<html>You are running on <b>reserver</b> battery * power. Please plug into a power source immediately, or your work may * be lost!</html>" * </pre></p> * * <p>If {@link #getErrorException} returns a non-null value, then this * method <b>may</b> return a null value.</p> * * @return basic error message or null if {@link #getErrorException} returns * a non null value */ public String getBasicErrorMessage(); /** * <p>Gets the detailed error message. Unlike {@link #getBasicErrorMessage}, * this method may return a more technical message to the user. However, it * should still be user oriented. This String should be formatted using basic * HTML to improve readability as necessary.</p> * * <p>This method may return null.</p> * * @return detailed error message or null if a detailed error message was not * provided */ public String getDetailedErrorMessage(); /** * Gets the category name. This value indicates where in the application * this incident occurred. It is recommended that this be the same value as * you would use when logging. This may be null. * * @return the category. May be null. */ public String getCategory(); /** * Gets the actual exception that generated the error. If this returns a * non null value, then {@link #getBasicErrorMessage} may return a null value. * If this returns a non null value and {@link #getDetailedErrorMessage} returns * a null value, then this returned <code>Throwable</code> may be used as the * basis for the detailed error message (generally by showing the stack trace). * * @return exception or null if no exception provided */ public Throwable getErrorException(); /** * Gets the severity of the error. The default level is <code>Level.SEVERE</code>, * but any {@link Level} may be specified when constructing an * <code>IncidentInfo</code>. * * @return the error level. This will never be null */ public Level getErrorLevel(); }