java.util.logging
public abstract class Handler extends Object
Handler
publishes LogRecords
to
a sink, for example a file, the console or a network socket.
There are different subclasses of Handler
to deal with different kinds of sinks.
FIXME: Are handlers thread-safe, or is the assumption that only loggers are, and a handler can belong only to one single logger? If the latter, should we enforce it? (Spec not clear). In any case, it needs documentation.
Modifier | Constructor and Description |
---|---|
protected |
Handler()
Constructs a Handler with a logging severity level of
Level.ALL , no formatter, no filter, and
an instance of ErrorManager managing errors. |
Modifier and Type | Method and Description |
---|---|
abstract void |
close()
Closes this
Handler after having flushed
the buffers. |
abstract void |
flush()
Forces any data that may have been buffered to the underlying
output device.
|
String |
getEncoding()
Returns the character encoding which this handler uses for publishing
log records.
|
ErrorManager |
getErrorManager()
Returns the
ErrorManager that currently deals
with errors originating from this Handler. |
Filter |
getFilter()
Returns the
Filter that currently controls which
log records are being published by this Handler . |
Formatter |
getFormatter()
Returns the
Formatter which will be used to
localize the text of log messages and to substitute
message parameters. |
Level |
getLevel()
Returns the severity level threshold for this
Handler
All log records with a lower severity level will be discarded;
a log record of the same or a higher level will be published
unless an installed Filter decides to discard it. |
boolean |
isLoggable(LogRecord record)
Checks whether a
LogRecord would be logged
if it was passed to this Handler for publication. |
abstract void |
publish(LogRecord record)
Publishes a
LogRecord to an appropriate sink,
provided the record passes all tests for being loggable. |
protected void |
reportError(String message,
Exception ex,
int code) |
void |
setEncoding(String encoding)
Sets the character encoding which this handler uses for publishing
log records.
|
void |
setErrorManager(ErrorManager manager) |
void |
setFilter(Filter filter)
Sets the
Filter for controlling which
log records will be published by this Handler . |
void |
setFormatter(Formatter formatter)
Sets the
Formatter which will be used to
localize the text of log messages and to substitute
message parameters. |
void |
setLevel(Level level)
Sets the severity level threshold for this
Handler . |
protected Handler()
Level.ALL
, no formatter, no filter, and
an instance of ErrorManager
managing errors.
Specification Note: The specification of the JavaTM Logging API does not mention which character encoding is to be used by freshly constructed Handlers. The GNU implementation uses the default platform encoding, but other Java implementations might behave differently.
Specification Note: While a freshly constructed
Handler is required to have no filter according to the
specification, null
is not a valid parameter for
Handler.setFormatter
. Therefore, the following
code will throw a java.lang.NullPointerException
:
Handler h = new MyConcreteSubclassOfHandler(); h.setFormatter(h.getFormatter());It seems strange that a freshly constructed Handler is not supposed to provide a Formatter, but this is what the specification says.
public abstract void publish(LogRecord record)
LogRecord
to an appropriate sink,
provided the record passes all tests for being loggable. The
Handler
will localize the message of the log
record and substitute any message parameters.
Most applications do not need to call this method directly.
Instead, they will use use a Logger
, which will
create LogRecords and distribute them to registered handlers.
In case of an I/O failure, the ErrorManager
of this Handler
will be informed, but the caller
of this method will not receive an exception.
record
- the log event to be published.public abstract void flush()
In case of an I/O failure, the ErrorManager
of this Handler
will be informed, but the caller
of this method will not receive an exception.
public abstract void close() throws SecurityException
Handler
after having flushed
the buffers. As soon as close
has been called,
a Handler
should not be used anymore. Attempts
to publish log records, to flush buffers, or to modify the
Handler
in any other way may throw runtime
exceptions after calling close
.
In case of an I/O failure, the ErrorManager
of this Handler
will be informed, but the caller
of this method will not receive an exception.
SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.public Formatter getFormatter()
Formatter
which will be used to
localize the text of log messages and to substitute
message parameters. A Handler
is encouraged,
but not required to actually use an assigned
Formatter
.Formatter
being used, or
null
if this Handler
does not use formatters and no formatter has
ever been set by calling setFormatter
.public void setFormatter(Formatter formatter) throws SecurityException
Formatter
which will be used to
localize the text of log messages and to substitute
message parameters. A Handler
is encouraged,
but not required to actually use an assigned
Formatter
.formatter
- the new Formatter
to use.SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.NullPointerException
- if formatter
is
null
.public String getEncoding()
null
for the default platform encoding.public void setEncoding(String encoding) throws SecurityException, UnsupportedEncodingException
Handler
must be
set before any log records have been published.encoding
- the name of a character encoding, or null
for the default encoding.SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.UnsupportedEncodingException
public Filter getFilter()
Filter
that currently controls which
log records are being published by this Handler
.Filter
, or
null
if no filter has been associated.
In the latter case, log records are filtered purely
based on their severity level.public void setFilter(Filter filter) throws SecurityException
Filter
for controlling which
log records will be published by this Handler
.filter
- the Filter
to use, or
null
to filter log records purely based
on their severity level.SecurityException
public ErrorManager getErrorManager()
ErrorManager
that currently deals
with errors originating from this Handler.SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.public void setErrorManager(ErrorManager manager)
protected void reportError(String message, Exception ex, int code)
public Level getLevel()
Handler
All log records with a lower severity level will be discarded;
a log record of the same or a higher level will be published
unless an installed Filter
decides to discard it.public void setLevel(Level level)
Handler
.
All log records with a lower severity level will be discarded;
a log record of the same or a higher level will be published
unless an installed Filter
decides to discard it.level
- the severity level below which all log messages
will be discarded.SecurityException
- if a security manager exists and
the caller is not granted the permission to control
the logging infrastructure.NullPointerException
- if level
is
null
.public boolean isLoggable(LogRecord record)
LogRecord
would be logged
if it was passed to this Handler
for publication.
The Handler
implementation considers a record as
loggable if its level is greater than or equal to the severity
level threshold. In a second step, if a Filter
has
been installed, its isLoggable
method is invoked. Subclasses of Handler
can override
this method to impose their own constraints.
record
- the LogRecord
to be checked.true
if record
would
be published by publish
,
false
if it would be discarded.NullPointerException
- if record
is null
.setLevel(Level)
,
setFilter(Filter)
,
Filter.isLoggable(LogRecord)