Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.openide.util 6.8.22
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
| org.openide.util 6.8.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.