/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"
     *
     *      "&lt;html&gt;You are running on &lt;b&gt;reserver&lt;/b&gt; battery 
     *       power. Please plug into a power source immediately, or your work may
     *       be lost!&lt;/html&gt;"
     * </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();
}