站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > NetBeans API Javadoc 5.5.0

ErrorManager (NetBeans Utilities API) - NetBeans API Javadoc 5.5.0

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
  extended by 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 May 28 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.