org.openide
Class ErrorManager

java.lang.Object
  |
  +--org.openide.ErrorManager

public abstract class ErrorManager

extends Object

A system of managing, annotating, and classifying errors and log messages. Rather than printing raw exceptions to the console, or popping up dialog boxes with exceptions, or implementing custom debug or logging facililities, code may use the error manager to access logging and error-reporting in a higher-level fashion. Standard error manager implementations can then provide generic ways of customizing logging levels for different components, and so on.

Especially important is the attaching of annotations such as stack traces to exceptions, permitting you to throw an exception of a type permitted by your API signature while safely encapsulating the root cause of the problem (in terms of other nested exceptions). Code should use notify(Throwable) rather than directly printing caught exceptions, to make sure nested annotations are not lost.

Also localized messages may be annotated to exceptions so that code which can deal with a caught exception with a user-visible UI can display a polite and helpful message. Messages with no localized annotation can be handled in a default way while the details are reserved for the log file.

A simple example of usage to keep nested stacktraces:

 public void doSomething () throws IOException {
     try {
         doSomethingElse ();
     } catch (IllegalArgumentException iae) {
         IOException ioe = new IOException ("did not work");
         TopManager.getDefault ().getErrorManager ().annotate (ioe, iae);
         throw ioe;
     }
 }
 // ...
 try {
     foo.doSomething ();
 } catch (IOException ioe) {
     TopManager.getDefault ().getErrorManager ().notify (ioe);
 }
 

See Also:

Philosophy and usage scenarios

Inner Class Summary

static interface

ErrorManager.Annotation Annotation that can be attached to an error.

Field Summary

static int	ERROR Serious problem, application may be crippled.
static int	EXCEPTION Something went wrong, though it can be recovered.
static int	INFORMATIONAL Message that would be useful for tracing events but which need not be a problem.
static int	UNKNOWN Undefined severity.
static int	USER Something the user should be aware of.
static int	WARNING Something went wrong in the software, but it is continuing and the user need not be bothered.

Constructor Summary

ErrorManager()

Method Summary

abstract Throwable	annotate(Throwable t, int severity, String message, String localizedMessage, Throwable stackTrace, Date date) Annotates given exception with given values.
Throwable	annotate(Throwable t, String localizedMessage) Annotates given exception with given values.
Throwable	annotate(Throwable target, Throwable t) Annotates target exception with given exception.
abstract Throwable	attachAnnotations(Throwable t, ErrorManager.Annotation[] arr) Associates annotations with an exception.
Throwable	copyAnnotation(Throwable t, Throwable copyFrom) Takes annotations from one exception and associates them with another one.
abstract ErrorManager.Annotation[]	findAnnotations(Throwable t) Finds annotations associated with a given exception.
abstract ErrorManager	getInstance(String name) Returns an instance with given name.
boolean	isLoggable(int severity) Test whether a messages with given severity will be logged in advance.
abstract void	log(int severity, String s) Logs the message to a file and (possibly) tells the user.
void	log(String s) Logs the message to log file and (possibly) tells the user.
abstract void	notify(int severity, Throwable t) Prints the exception to the log file and (possibly) notifies the user.
void	notify(Throwable t) Prints the exception to the log file and (possibly) notifies the user.

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN

public static final int UNKNOWN

Undefined severity.

INFORMATIONAL

public static final int INFORMATIONAL

Message that would be useful for tracing events but which need not be a problem.

WARNING

public static final int WARNING

Something went wrong in the software, but it is continuing and the user need not be bothered.

USER

public static final int USER

Something the user should be aware of.

EXCEPTION

public static final int EXCEPTION

Something went wrong, though it can be recovered.

ERROR

public static final int ERROR

Serious problem, application may be crippled.

Constructor Detail

ErrorManager

public ErrorManager()

Method Detail

attachAnnotations

public abstract Throwable attachAnnotations(Throwable t,
                                            ErrorManager.Annotation[] arr)

Associates annotations with an exception.

Parameters:

t - the exception

arr - array of annotations (or null)

Returns:

the same exception t (as a convenience)

findAnnotations

public abstract ErrorManager.Annotation[] findAnnotations(Throwable t)

Finds annotations associated with a given exception.

Parameters:

t - the exception

Returns:

array of annotations or null

annotate

public abstract Throwable annotate(Throwable t,
                                   int severity,
                                   String message,
                                   String localizedMessage,
                                   Throwable stackTrace,
                                   Date date)

Annotates given exception with given values. All the previous annotations are kept and this new one is added at the top of the annotation stack (index 0 of the annotation array).

Parameters:

t - the exception

severity - integer describing severity, e.g. EXCEPTION

date - date or null

message - message to attach to the exception or null

localizedMessage - localized message for the user or null

stackTrace - exception representing the stack trace or null

Returns:

the same exception t (as a convenience)

notify

public abstract void notify(int severity,
                            Throwable t)

Prints the exception to the log file and (possibly) notifies the user.

Parameters:

severity - the severity to be applied to the exception (overrides default), e.g. EXCEPTION

t - the exception to notify

notify

public final void notify(Throwable t)

Prints the exception to the log file and (possibly) notifies the user. Guesses at the severity.

Parameters:

t - the exception to notify

log

public abstract void log(int severity,
                         String s)

Logs the message to a file and (possibly) tells the user.

Parameters:

severity - the severity to be applied (overrides default)

s - the log message

log

public final void log(String s)

Logs the message to log file and (possibly) tells the user. Uses a default severity.

Parameters:

s - the log message

isLoggable

public boolean isLoggable(int severity)

Test whether a messages with given severity will be logged in advance. Can be used to avoid the construction of complicated and expensive logging messages.

Parameters:

severity - the severity to check, e.g. EXCEPTION

Returns:

false if the next call to log(int,String) with this severity will discard the message

getInstance

public abstract ErrorManager getInstance(String name)

Returns an instance with given name.

By convention, you can name error managers the same as packages (or classes) they are designed to report information from. For example, org.netbeans.modules.mymodule.ComplicatedParser.

The error manager implementation should provide some way of configuring e.g. the logging level for error managers of different names. For example, in the basic NetBeans core implementation, you can define a system property with the same name as the future error manager (or a package prefix of it) whose value is the numeric logging level (e.g. -J-Dorg.netbeans.modules.mymodule.ComplicatedParser=0 to log everything). Other implementations may have quite different ways of configuring the error managers.

Parameters:

name - the desired identifying name

Returns:

a new error manager keyed off of that name

annotate

public final Throwable annotate(Throwable t,
                                String localizedMessage)

Annotates given exception with given values. All the previous annotations are kept and this new is added at the top of the annotation stack (index 0 of the annotation array).

Parameters:

t - the exception

localizedMessage - localized message for the user or null

Returns:

the same exception t (as a convenience)

annotate

public final Throwable annotate(Throwable target,
                                Throwable t)

Annotates target exception with given exception. All the previous annotations are kept and this new is added at the top of the annotation stack (index 0 of the annotation array).

Parameters:

target - the exception to be annotated

t - the exception that will be added

Returns:

the same exception target (as a convenience)

copyAnnotation

public final Throwable copyAnnotation(Throwable t,
                                      Throwable copyFrom)

Takes annotations from one exception and associates them with another one.

Parameters:

t - the exception to annotate

copyFrom - exception to take annotations from

Returns:

the same exception t (as a convenience)