org.jdesktop.swingx.error
Class ErrorInfo

java.lang.Object
  org.jdesktop.swingx.error.ErrorInfo

public class ErrorInfo
extends Object

A simple class that encapsulates all the information needed to report a problem using the automated report/processing system.

All HTML referred to in this API refers to version 3.2 of the HTML markup specification.

Both basicErrorMessage and detailedErrorMessage may be specified with variable substitution. For example, this is a valid error message string: "${os.version} is not supported". Such variables are resovled using the substituteVariables method. This method will use properties in the "state" map to replace these variables.

For example:

    String message = "An error occured on ${os.name} version ${os.version}";
    //auto creates the state map, populated with all System properties.
    //Sandboxed apps can't read System properties.
    ErrorInfo info = new ErrorInfo("Error", exception);
    message = info.substituteVariables(message);

    //prints out: "An error occured on Mac OS X version 10.4.7" on some systems
    log.info(message);
 

Review status:

REVIEWED

Constructor Summary

ErrorInfo(String title, String basicErrorMessage, String detailedErrorMessage, String category, Throwable errorException, Level errorLevel, Map<String,String> state)
Creates a new ErrorInfo based on the provided data.

Method Summary

String	getBasicErrorMessage() Gets the basic error message.
String	getCategory() Gets the category name.
String	getDetailedErrorMessage() Gets the detailed error message.
Throwable	getErrorException() Gets the actual exception that generated the error.
Level	getErrorLevel() Gets the severity of the error.
Map<String,String>	getState() Gets a copy of the application state at the time that the incident occured.
String	getTitle() Gets the string to use for a dialog title or other quick reference.

Methods inherited from class java.lang.Object

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

Constructor Detail

ErrorInfo

public ErrorInfo(String title,
                 String basicErrorMessage,
                 String detailedErrorMessage,
                 String category,
                 Throwable errorException,
                 Level errorLevel,
                 Map<String,String> state)

Creates a new ErrorInfo based on the provided data.

Parameters:

title - used as a quick reference for the error (for example, it might be used as the title of an error dialog or as the subject of an email message). May be null.

basicErrorMessage - short description of the problem. May be null.

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.

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. May be null.

errorException - Throwable that can be used as a source for additional information such as call stack, thread name, etc. May be null.

errorLevel - any Level (Level.SEVERE, Level.WARNING, etc). If null, then the level will be set to SEVERE.

state - the state of the application at the time the incident occured. The standard System properties are automatically added to this state, and thus do not need to be included. This value may be null. If null, the resulting map will contain only the System properties. If there is a value in the map with a key that also occurs in the System properties (for example: sun.java2d.noddraw), then the developer supplied value will be used. In other words, defined parameters override standard ones. In addition, the keys "System.currentTimeMillis" and "isOnEDT" are both defined automatically.

Method Detail

getTitle

public String getTitle()

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.

Returns:

quick reference String. May be null.

getBasicErrorMessage

public String getBasicErrorMessage()

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.

For example, the following are perfectly acceptable basic error messages:

      "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>"
 

Returns:

basic error message or null

getDetailedErrorMessage

public String getDetailedErrorMessage()

Gets the detailed error message. Unlike 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.

This method may return null.

Returns:

detailed error message or null

getCategory

public String getCategory()

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.

Returns:

the category. May be null.

getErrorException

public Throwable getErrorException()

Gets the actual exception that generated the error. If this returns a non null value, then getBasicErrorMessage() may return a null value. If this returns a non null value and getDetailedErrorMessage() returns a null value, then this returned Throwable may be used as the basis for the detailed error message (generally by showing the stack trace).

Returns:

exception or null

getErrorLevel

public Level getErrorLevel()

Gets the severity of the error. The default level is Level.SEVERE, but any Level may be specified when constructing an ErrorInfo.

Returns:

the error level. This will never be null

getState

public Map<String,String> getState()

Gets a copy of the application state at the time that the incident occured. This map will never be null. If running with appropriate permissions the map will contain all the System properties. In addition, it contains two keys, "System.currentTimeMillis" and "isOnEDT".

Warning: The System.properties may not contain the exact set of System properties at the time the exception occured. This is due to the nature of System.getProperties() and the Properties collection. While they are property synchronized, it is possible that while iterating the set of properties in the ErrorInfo constructor that some other code can change the properties on another thread. This is unlikely to occur, but in some applications may occur.

Returns:

a copy of the application state. This will never be null.