ErrorManager (NetBeans Utilities API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.

There may be zero or more instances of ErrorManager in Lookup.getDefault(). All will be delegated to, or a simple backup implementation is available if there are none.

How to...

Handle an exception

If it might be an important error (show the user):

 try {
     foo.doSomething();
 } catch (IOException ioe) {
     ErrorManager.getDefault().notify(ioe);
 }

If it is not very important but should be sent to the log file:

 try {
     foo.doSomething();
 } catch (IOException ioe) {
     ErrorManager.getDefault().notify(ErrorManager.INFORMATIONAL, ioe);
 }

If it is the normal outcome of a user action and there is no need to show stack traces to the user:

 try {
     foo.doSomething();
 } catch (IOException ioe) {
     // Also WARNING or ERROR:
     ErrorManager.getDefault().notify(ErrorManager.USER, ioe);
 }

You can also specify the severity when you are creating the exception (by annotating it), rather than relying on the notifier to do this. In that case, if the notifier just use the plain form of notify (i.e. UNKNOWN severity), the annotated severity is used.

Retain nested stacktraces / change exception type

 public void doSomething() throws IOException {
     try {
         doSomethingElse();
     } catch (IllegalArgumentException iae) {
         IOException ioe = new IOException("did not work: " + iae);
         ErrorManager.getDefault().annotate(ioe, iae);
         throw ioe;
     }
 }

You can also just use JDK 1.4 causes:

 public void doSomething() throws IOException {
     try {
         doSomethingElse();
     } catch (IllegalArgumentException iae) {
         IOException ioe = new IOException("did not work: " + iae);
         ioe.initCause(iae);
         throw ioe;
     }
 }
 // ...
 try {
     foo.doSomething();
 } catch (IOException ioe) {
     // The IllegalArgumentException is still available here:
     ErrorManager.getDefault().notify(ioe);
 }

Provide a user-visible (localized) message

 public void doSomething(File f) throws IOException {
     if (!f.isFile()) {
         IOException e = new IOException("Not a file: " + f); // NOI18N
         // For what the user actually sees:
         ErrorManager.getDefault().annotate(e,
             NbBundle.getMessage(This.class, "EXC_not_a_file", f));
         throw e;
     }
 }

You can also add the message when the exception is caught rather than when it is thrown. You could even have one piece of code throw an exception, another annotate it, and yet another notify it.

Collecting several exceptions and wrapping them in one

 IOException all = null;
 for (int i = 0; i < things.length; i++) {
     try {
          things[i].process();
     } catch (ThingProcessingException e) {
          if (all == null) {
              all = new IOException("Could not process one or more things"); // NOI18N
          }
          ErrorManager.getDefault().annotate(all, e);
     }
 }
 if (all != null) {
     throw all;
 }

Logging a warning message

 public void doSomething(String arg) {
     if (arg.length() == 0) {
         ErrorManager.getDefault().log(ErrorManager.WARNING,
             "Warning: doSomething called on empty string");
         return;
     }
     // ...
 }

Logging messages for some subcomponent

 package org.netbeans.modules.foo;
 class FooModule {
     public static final ErrorManager ERR =
         ErrorManager.getDefault().getInstance("org.netbeans.modules.foo");
 }
 // ...
 class Something {
     public void doSomething(String arg) {
         if (ERR.isLoggable(ErrorManager.INFORMATIONAL)) {
             ERR.log("Called doSomething with arg " + arg);
         }
     }
 }

Nested 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)
          Deprecated. Now does the same thing as annotate(Throwable,Throwable) except marks the annotation UNKNOWN severity. Otherwise you used to have inadvertent data loss when copyFrom had annotations of its own: the subannotations were kept but the main stack trace in copyFrom was discarded. In practice you usually want to keep all of copyFrom; if for some reason you just want to keep annotations, please do so explicitly using findAnnotations(java.lang.Throwable) and attachAnnotations(java.lang.Throwable, org.openide.ErrorManager.Annotation[]).

abstract ErrorManager.Annotation[] findAnnotations(Throwable t)
          Finds annotations associated with a given exception.

static ErrorManager getDefault()
          Getter for the default version of error manager.

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.

boolean isNotifiable(int severity)
          Test whether a throwable, if notified at the given level, will actually be displayed in any way (even to a log file etc.).

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. May be used only in notify(int, Throwable) and annotate(Throwable, int, String, String, Throwable, Date).

See Also:: Constant Field Values

INFORMATIONAL

public static final int INFORMATIONAL

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

See Also:: Constant Field Values

WARNING

public static final int WARNING

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

See Also:: Constant Field Values

USER

public static final int USER

Something the user should be aware of.

See Also:: Constant Field Values

EXCEPTION

public static final int EXCEPTION

Something went wrong, though it can be recovered.

See Also:: Constant Field Values

ERROR

public static final int ERROR

Serious problem, application may be crippled.

See Also:: Constant Field Values

Constructor Detail

ErrorManager

public ErrorManager()

Method Detail

getDefault

public static ErrorManager getDefault()

Getter for the default version of error manager.

Returns:: the error manager installed in the system
Since:: 2.1

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; 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; date - date 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. Use of UNKNOWN severity means that the error manager should automatically select an appropriate severity level, for example based on the contents of annotations in the throwable.

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
See Also:: UNKNOWN, notify(int, Throwable)

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.

The default implementation just returns true. Subclasses should override to be more precise - treat this method as abstract.

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

isNotifiable

public boolean isNotifiable(int severity)

Test whether a throwable, if notified at the given level, will actually be displayed in any way (even to a log file etc.). If not, there is no point in constructing it.

This method is distinct from isLoggable(int) because an error manager implementation may choose to notify stack traces at a level where it would not log messages. See issue #24056 for justification.

The default implementation just calls isLoggable(int). Subclasses should override to be more precise - treat this method as abstract.

Parameters:: severity - a notification severity
Returns:: true if a throwable notified at this severity will be used; false if it will be ignored
Since:: 3.18

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).

Consider using Throwable.initCause(java.lang.Throwable) instead; this will be correctly reported by the NetBeans error manager, and also works properly with Throwable.printStackTrace().

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)

Deprecated. Now does the same thing as annotate(Throwable,Throwable) except marks the annotation UNKNOWN severity. Otherwise you used to have inadvertent data loss when copyFrom had annotations of its own: the subannotations were kept but the main stack trace in copyFrom was discarded. In practice you usually want to keep all of copyFrom; if for some reason you just want to keep annotations, please do so explicitly using findAnnotations(java.lang.Throwable) and attachAnnotations(java.lang.Throwable, org.openide.ErrorManager.Annotation[]).

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)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Nested 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.

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)` Deprecated. Now does the same thing as `annotate(Throwable,Throwable)` except marks the annotation `UNKNOWN` severity. Otherwise you used to have inadvertent data loss when `copyFrom` had annotations of its own: the subannotations were kept but the main stack trace in `copyFrom` was discarded. In practice you usually want to keep all of `copyFrom`; if for some reason you just want to keep annotations, please do so explicitly using `findAnnotations(java.lang.Throwable)` and `attachAnnotations(java.lang.Throwable, org.openide.ErrorManager.Annotation[])`.
`abstract ErrorManager.Annotation[]`	`findAnnotations(Throwable t)` Finds annotations associated with a given exception.
`static ErrorManager`	`getDefault()` Getter for the default version of error manager.
`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.
`boolean`	`isNotifiable(int severity)` Test whether a throwable, if `notified` at the given level, will actually be displayed in any way (even to a log file etc.).
`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.

ErrorManager (NetBeans Utilities API) - NetBeans API Javadoc 5.0.0

org.openide Class ErrorManager

UNKNOWN

INFORMATIONAL

WARNING

USER

EXCEPTION

ERROR

ErrorManager

getDefault

attachAnnotations

findAnnotations

annotate

notify

notify

log

log

isLoggable

isNotifiable

getInstance

annotate

annotate

copyAnnotation

org.openide
Class ErrorManager