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.
*
* @author Sascha Brawer (brawer@acm.org)
*/
public abstract class Handler
{
Formatter formatter;
Filter filter;
Level level;
ErrorManager errorManager;
String encoding;
/**
* 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. */ protected Handler() { level = Level.ALL; } /** * 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 {@link 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.
*
* @param record the log event to be published.
*/
public abstract void publish(LogRecord record);
/**
* 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.
*/
public abstract void flush();
/**
* 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.
*/
public abstract void close()
throws SecurityException;
/**
* 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.
*
* @return the Formatter being used, or
* null if this Handler
* does not use formatters and no formatter has
* ever been set by calling setFormatter.
*/
public Formatter getFormatter()
{
return formatter;
}
/**
* 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.
*
* @param 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.
*
* @throws NullPointerException if formatter is
* null.
*/
public void setFormatter(Formatter formatter)
throws SecurityException
{
LogManager.getLogManager().checkAccess();
/* Throws a NullPointerException if formatter is null. */
formatter.getClass();
this.formatter = formatter;
}
/**
* Returns the character encoding which this handler uses for publishing
* log records.
*
* @return the name of a character encoding, or null
* for the default platform encoding.
*/
public String getEncoding()
{
return encoding;
}
/**
* 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.
*
* @param encoding the name of a character encoding, or null
* for the default encoding.
*
* @exception SecurityException if a security manager exists and
* the caller is not granted the permission to control
* the logging infrastructure.
*
*/
public void setEncoding(String encoding)
throws SecurityException, UnsupportedEncodingException
{
/* Should any developer ever change this implementation, they are
* advised to have a look at StreamHandler.setEncoding(String),
* which overrides this method without calling super.setEncoding.
*/
LogManager.getLogManager().checkAccess();
/* Simple check for supported encodings. This is more expensive
* than it could be, but this method is overwritten by StreamHandler
* anyway.
*/
if (encoding != null)
new String(new byte[0], encoding);
this.encoding = encoding;
}
/**
* Returns the Filter that currently controls which
* log records are being published by this Handler.
*
* @return 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.
*/
public Filter getFilter()
{
return filter;
}
/**
* Sets the Filter for controlling which
* log records will be published by this Handler.
*
* @param filter the Filter to use, or
* null to filter log records purely based
* on their severity level.
*/
public void setFilter(Filter filter)
throws SecurityException
{
LogManager.getLogManager().checkAccess();
this.filter = filter;
}
/**
* Returns the ErrorManager that currently deals
* with errors originating from this Handler.
*
* @exception SecurityException if a security manager exists and
* the caller is not granted the permission to control
* the logging infrastructure.
*/
public ErrorManager getErrorManager()
{
LogManager.getLogManager().checkAccess();
/* Developers wanting to change the subsequent code should
* have a look at Handler.reportError -- it also can create
* an ErrorManager, but does so without checking permissions
* to control the logging infrastructure.
*/
if (errorManager == null)
errorManager = new ErrorManager();
return errorManager;
}
public void setErrorManager(ErrorManager manager)
{
LogManager.getLogManager().checkAccess();
/* Make sure manager is not null. */
manager.getClass();
this.errorManager = manager;
}
protected void reportError(String message, Exception ex, int code)
{
if (errorManager == null)
errorManager = new ErrorManager();
errorManager.error(message, ex, code);
}
/**
* 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.
*
* @return the severity level below which all log messages
* will be discarded.
*/
public Level getLevel()
{
return 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.
*
* @param level the severity level below which all log messages
* will be discarded.
*
* @exception SecurityException if a security manager exists and
* the caller is not granted the permission to control
* the logging infrastructure.
*
* @exception NullPointerException if level is
* null.
*/
public void setLevel(Level level)
{
LogManager.getLogManager().checkAccess();
/* Throw NullPointerException if level is null. */
level.getClass();
this.level = level;
}
/**
* 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 {@link Filter} has
* been installed, its {@link Filter#isLoggable(LogRecord) isLoggable}
* method is invoked. Subclasses of Handler can override
* this method to impose their own constraints.
*
* @param record the LogRecord to be checked.
*
* @return true if record would
* be published by {@link #publish(LogRecord) publish},
* false if it would be discarded.
*
* @see #setLevel(Level)
* @see #setFilter(Filter)
* @see Filter#isLoggable(LogRecord)
*
* @throws NullPointerException if record
* is null.
*/
public boolean isLoggable(LogRecord record)
{
if (record.getLevel().intValue() < level.intValue())
return false;
if (filter != null)
return filter.isLoggable(record);
else
return true;
}
}