public abstract class ErrorManager extends Object
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...
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.
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);
}
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.
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;
}
public void doSomething(String arg) {
if (arg.length() == 0) {
Logger.getLogger(YourClass.class.getName()).log(Leverl.WARNING,
"Warning: doSomething called on empty string");
return;
}
// ...
}
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);
}
}
| Modifier and Type | Class and Description |
|---|---|
static interface |
ErrorManager.Annotation
Annotation that can be attached to an error.
|
| Modifier and Type | Field and Description |
|---|---|
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 and Description |
|---|
ErrorManager() |
| Modifier and Type | Method and Description |
|---|---|
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
ErrorManager.annotate(Throwable,Throwable)
except marks the annotation ErrorManager.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 ErrorManager.findAnnotations(java.lang.Throwable) and ErrorManager.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.
|
public static final int UNKNOWN
ErrorManager.notify(int, Throwable)
and ErrorManager.annotate(Throwable, int, String, String, Throwable, Date).public static final int INFORMATIONAL
public static final int WARNING
public static final int USER
public static final int EXCEPTION
public static final int ERROR
public static ErrorManager getDefault()
public abstract Throwable attachAnnotations(Throwable t, ErrorManager.Annotation[] arr)
t - the exceptionarr - array of annotations (or null)t (as a convenience)public abstract ErrorManager.Annotation[] findAnnotations(Throwable t)
t - the exceptionnullpublic abstract Throwable annotate(Throwable t, int severity, String message, String localizedMessage, Throwable stackTrace, Date date)
t - the exceptionseverity - integer describing severity, e.g. ErrorManager.EXCEPTIONmessage - message to attach to the exception or nulllocalizedMessage - localized message for the user or nullstackTrace - exception representing the stack trace or nulldate - date or nullt (as a convenience)public abstract void notify(int severity,
Throwable t)
ErrorManager.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.severity - the severity to be applied to the exception (overrides default), e.g. ErrorManager.EXCEPTIONt - the exception to notifypublic final void notify(Throwable t)
t - the exception to notifyErrorManager.UNKNOWN,
ErrorManager.notify(int, Throwable)public abstract void log(int severity,
String s)
severity - the severity to be applied (overrides default)s - the log messagepublic final void log(String s)
s - the log messagepublic boolean isLoggable(int severity)
The default implementation just returns true. Subclasses should override to be more precise - treat this method as abstract.
severity - the severity to check, e.g. ErrorManager.EXCEPTIONfalse if the next call to ErrorManager.log(int,String) with this severity will
discard the messagepublic boolean isNotifiable(int severity)
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 ErrorManager.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 ErrorManager.isLoggable(int). Subclasses
should override to be more precise - treat this method as abstract.
severity - a notification severitypublic abstract ErrorManager getInstance(String 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.
name - the desired identifying namepublic final Throwable annotate(Throwable t, String localizedMessage)
t - the exceptionlocalizedMessage - localized message for the user or nullt (as a convenience)public final Throwable annotate(Throwable target, Throwable t)
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().
target - the exception to be annotatedt - the exception that will be addedtarget (as a convenience)@Deprecated public final Throwable copyAnnotation(Throwable t, Throwable copyFrom)
ErrorManager.annotate(Throwable,Throwable)
except marks the annotation ErrorManager.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 ErrorManager.findAnnotations(java.lang.Throwable) and ErrorManager.attachAnnotations(java.lang.Throwable, org.openide.ErrorManager.Annotation[]).t - the exception to annotatecopyFrom - exception to take annotations fromt (as a convenience)