org.openide
Class ErrorManager

java.lang.Object
  extended by org.openide.ErrorManager

public abstract class ErrorManager
extends java.lang.Object

A more or less deprecated system of managing, annotating, and classifying errors and log messages. Instead of ErrorManager use Logger as described in NetBeans logging guide.

Rather then using the ErrorManager consider using JDK's Logger for reporting log events, unwanted exceptions, etc. The methods in this class which are deprecated are annotated with a description how to use use the Logger methods to achieve the same goal.

The levels in descending order are:

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) {
     Logger.getLogger(YourClass.class.getName()).log(Level.CONFIG, "msg", ioe);
     // used to be:
     // 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) {
 
     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);
         ioe.initCause(iae);
         // used to be: 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);
     // or use logging
     Logger.getLogger(YourClass.class.getName()).log(Level.SEVERE, null, 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 just simply uses the JDK's logging API
 public void doSomething(String arg) {
     if (arg.length() == 0) {
         Logger.getLogger(YourClass.class.getName()).log(Leverl.WARNING,
             "Warning: doSomething called on empty string");
         return;
     }
     // ...
 }
 
Logging messages for some subcomponent can be done easily with JDK's logging API
 package org.netbeans.modules.foo;
 class FooModule {
     public static final Logger ERR =
         Logger.getLogger("org.netbeans.modules.foo");
 }
 // ...
 class Something {
     public void doSomething(String arg) {
         LogRecord rec = new LogRecord(Level.FINE, "MSG_Key");
         // where in the Bundle.properties one has:
         // MSG_Key=Called doSomething with arg {0}
         rec.setResourceBundle(NbBundle.getBundle(Something.class));
         rec.setParameters(new Object[] { arg });
         ERR.log(rec);
     }
 }
 

Author:
Jaroslav Tulach, Jesse Glick

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  java.lang.Throwable annotate(java.lang.Throwable t, int severity, java.lang.String message, java.lang.String localizedMessage, java.lang.Throwable stackTrace, java.util.Date date)
          Annotates given exception with given values.
 java.lang.Throwable annotate(java.lang.Throwable t, java.lang.String localizedMessage)
          Annotates given exception with given values.
 java.lang.Throwable annotate(java.lang.Throwable target, java.lang.Throwable t)
          Annotates target exception with given exception.
abstract  java.lang.Throwable attachAnnotations(java.lang.Throwable t, ErrorManager.Annotation[] arr)
          Associates annotations with an exception.
 java.lang.Throwable copyAnnotation(java.lang.Throwable t, java.lang.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(java.lang.Throwable t)
          Finds annotations associated with a given exception.
static ErrorManager getDefault()
          Getter for the default version of error manager.
abstract  ErrorManager getInstance(java.lang.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, java.lang.String s)
          Logs the message to a file and (possibly) tells the user.
 void log(java.lang.String s)
          Logs the message to log file and (possibly) tells the user.
abstract  void notify(int severity, java.lang.Throwable t)
          Prints the exception to the log file and (possibly) notifies the user.
 void notify(java.lang.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 java.lang.Throwable attachAnnotations(java.lang.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(java.lang.Throwable t)
Finds annotations associated with a given exception.

Parameters:
t - the exception
Returns:
array of annotations or null

annotate

public abstract java.lang.Throwable annotate(java.lang.Throwable t,
                                             int severity,
                                             java.lang.String message,
                                             java.lang.String localizedMessage,
                                             java.lang.Throwable stackTrace,
                                             java.util.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,
                            java.lang.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(java.lang.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,
                         java.lang.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(java.lang.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(java.lang.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 java.lang.Throwable annotate(java.lang.Throwable t,
                                          java.lang.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 java.lang.Throwable annotate(java.lang.Throwable target,
                                          java.lang.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

@Deprecated
public final java.lang.Throwable copyAnnotation(java.lang.Throwable t,
                                                           java.lang.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)