java.util.logging
Class Handler

java.lang.Object
  extended by java.util.logging.Handler
Direct Known Subclasses:
MemoryHandler, StreamHandler

public abstract class Handler
extends Object

A 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.


Constructor Summary
protected Handler()
          Constructs a Handler with a logging severity level of Level.ALL, no formatter, no filter, and an instance of ErrorManager managing errors.
 
Method Summary
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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Handler

protected Handler()
Constructs a Handler with a logging severity level of 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.

Method Detail

publish

public abstract void publish(LogRecord record)
Publishes a 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.

Parameters:
record - the log event to be published.

flush

public abstract void flush()
Forces any data that may have been buffered to the underlying output device.

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.


close

public abstract void close()
                    throws SecurityException
Closes this 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.

Throws:
SecurityException - if a security manager exists and the caller is not granted the permission to control the logging infrastructure.

getFormatter

public Formatter getFormatter()
Returns the 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.

Returns:
the Formatter being used, or null if this Handler does not use formatters and no formatter has ever been set by calling setFormatter.

setFormatter

public void setFormatter(Formatter formatter)
                  throws SecurityException
Sets the 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.

Parameters:
formatter - the new Formatter to use.
Throws:
SecurityException - if a security manager exists and the caller is not granted the permission to control the logging infrastructure.
NullPointerException - if formatter is null.

getEncoding

public String getEncoding()
Returns the character encoding which this handler uses for publishing log records.

Returns:
the name of a character encoding, or null for the default platform encoding.

setEncoding

public void setEncoding(String encoding)
                 throws SecurityException,
                        UnsupportedEncodingException
Sets the character encoding which this handler uses for publishing log records. The encoding of a Handler must be set before any log records have been published.

Parameters:
encoding - the name of a character encoding, or null for the default encoding.
Throws:
SecurityException - if a security manager exists and the caller is not granted the permission to control the logging infrastructure.
UnsupportedEncodingException

getFilter

public Filter getFilter()
Returns the Filter that currently controls which log records are being published by this Handler.

Returns:
the currently active Filter, or null if no filter has been associated. In the latter case, log records are filtered purely based on their severity level.

setFilter

public void setFilter(Filter filter)
               throws SecurityException
Sets the Filter for controlling which log records will be published by this Handler.

Parameters:
filter - the Filter to use, or null to filter log records purely based on their severity level.
Throws:
SecurityException

getErrorManager

public ErrorManager getErrorManager()
Returns the ErrorManager that currently deals with errors originating from this Handler.

Throws:
SecurityException - if a security manager exists and the caller is not granted the permission to control the logging infrastructure.

setErrorManager

public void setErrorManager(ErrorManager manager)

reportError

protected void reportError(String message,
                           Exception ex,
                           int code)

getLevel

public 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.

Returns:
the severity level below which all log messages will be discarded.

setLevel

public void setLevel(Level level)
Sets 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.

Parameters:
level - the severity level below which all log messages will be discarded.
Throws:
SecurityException - if a security manager exists and the caller is not granted the permission to control the logging infrastructure.
NullPointerException - if level is null.

isLoggable

public boolean isLoggable(LogRecord record)
Checks whether a 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.

Parameters:
record - the LogRecord to be checked.
Returns:
true if record would be published by publish, false if it would be discarded.
Throws:
NullPointerException - if record is null.
See Also:
setLevel(Level), setFilter(Filter), Filter.isLoggable(LogRecord)