OpenJDK 27 · java.util.logging.Handler · APIdia, the JavaDoc alternative

A Handler object takes log messages from a Logger and exports them. It might for example, write them to a console or write them to a file, or send them to a network logging service, or forward them to an OS log, or whatever.

A Handler can be disabled by doing a setLevel(Level.OFF) and can be re-enabled by doing a setLevel with an appropriate level.

Handler classes typically use LogManager properties to set default values for the Handler's Filter, Formatter, and Level. See the specific documentation for each concrete Handler class.

Thread Safety and Deadlock Risk in Handlers

Implementations of Handler should be thread-safe. Handlers are expected to be invoked concurrently from arbitrary threads. However, over-use of synchronization may result in unwanted thread contention, performance issues or even deadlocking.

In particular, subclasses should avoid acquiring locks around code which calls back to arbitrary user-supplied objects, especially during log record formatting. Holding a lock around any such callbacks creates a deadlock risk between logging code and user code.

As such, general purpose Handler subclasses should not synchronize their publish(LogRecord) methods, or call super.publish() while holding locks, since these are typically expected to need to process and format user-supplied arguments.

Modifier and Type	Field and Description
private volatile String	encoding
private volatile ErrorManager	errorManager
private volatile Filter	filter
private volatile Formatter	formatter
private volatile Level	logLevel
private final LogManager	manager
private static final int	offValue

Constructor Summary

Access Constructor and Description

protected

Access	Constructor and Description
protected	Handler() Default constructor.
pack-priv	Handler(Level a default `Level` to configure if one is not found in LogManager configuration properties defaultLevel, Formatter a default `Formatter` to configure if one is not specified by `specifiedFormatter` parameter nor found in LogManager configuration properties defaultFormatter, Formatter if not null, this is the formatter to configure specifiedFormatter) Package-private constructor for chaining from subclass constructors that wish to configure the handler with specific default and/or specified values.

Handler()

Default constructor.

pack-priv

Handler(Level

a default Level to configure if one is not found in LogManager configuration properties

defaultLevel, Formatter

a default Formatter to configure if one is not specified by specifiedFormatter parameter nor found in LogManager configuration properties

defaultFormatter, Formatter

if not null, this is the formatter to configure

specifiedFormatter)

Package-private constructor for chaining from subclass constructors that wish to configure the handler with specific default and/or specified values.

Method Summary

Modifier and Type	Method and Description
public abstract void	close() Close the `Handler` and free all associated resources.
public abstract void	flush() Flush any buffered output.
public String	Returns: The encoding name. May be null, which indicates the default encoding should be used. getEncoding() Return the character encoding for this `Handler`.
public ErrorManager	Returns: the ErrorManager for this Handler getErrorManager() Retrieves the ErrorManager for this Handler.
public Filter	Returns: a `Filter` object (may be null) getFilter() Get the current `Filter` for this `Handler`.
public Formatter	Returns: the `Formatter` (may be null). getFormatter() Return the `Formatter` for this `Handler`.
public Level	Returns: the level of messages being logged. getLevel() Get the log level specifying which messages will be logged by this `Handler`.
public boolean	Returns: true if the `LogRecord` would be logged. isLoggable(LogRecord a `LogRecord` (may be null). record) Check if this `Handler` would actually log a given `LogRecord`.
public abstract void	publish(LogRecord description of the log event. A null record is silently ignored and is not published record) Publish a `LogRecord`.
protected void	reportError(String a descriptive string (may be null) msg, Exception an exception (may be null) ex, int an error code defined in ErrorManager code) Protected convenience method to report an error to this Handler's ErrorManager.
public synchronized void	setEncoding(String The name of a supported character encoding. May be null, to indicate the default platform encoding. encoding) Set the character encoding used by this `Handler`.
public synchronized void	setErrorManager(ErrorManager the new ErrorManager em) Define an ErrorManager for this Handler.
public synchronized void	setFilter(Filter a `Filter` object (may be null) newFilter) Set a `Filter` to control output on this `Handler`.
public synchronized void	setFormatter(Formatter the `Formatter` to use (may not be null) newFormatter) Set a `Formatter`.
public synchronized void	setLevel(Level the new value for the log level newLevel) Set the log level specifying which message levels will be logged by this `Handler`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

encoding	back to summary
private volatile String encoding

errorManager	back to summary
private volatile ErrorManager errorManager

filter	back to summary
private volatile Filter filter

formatter	back to summary
private volatile Formatter formatter

logLevel	back to summary
private volatile Level logLevel

manager	back to summary
private final LogManager manager

offValue	back to summary
private static final int offValue

Constructor Detail

Handler	back to summary
protected Handler() Default constructor. The resulting `Handler` has a log level of `Level.ALL`, no `Formatter`, and no `Filter`. A default `ErrorManager` instance is installed as the `ErrorManager`.

Handler back to summary

Handler	back to summary
pack-priv Handler(Level defaultLevel, Formatter defaultFormatter, Formatter specifiedFormatter) Package-private constructor for chaining from subclass constructors that wish to configure the handler with specific default and/or specified values. Parameters defaultLevel:Level a default `Level` to configure if one is not found in LogManager configuration properties defaultFormatter:Formatter a default `Formatter` to configure if one is not specified by `specifiedFormatter` parameter nor found in LogManager configuration properties specifiedFormatter:Formatter if not null, this is the formatter to configure

pack-priv Handler(Level defaultLevel, Formatter defaultFormatter, Formatter specifiedFormatter)

Package-private constructor for chaining from subclass constructors that wish to configure the handler with specific default and/or specified values.

Parameters

defaultLevel:Level: a default Level to configure if one is not found in LogManager configuration properties
defaultFormatter:Formatter: a default Formatter to configure if one is not specified by specifiedFormatter parameter nor found in LogManager configuration properties
specifiedFormatter:Formatter: if not null, this is the formatter to configure

Method Detail

close back to summary

close	back to summary
public abstract void close() Close the `Handler` and free all associated resources. The close method will perform a `flush` and then close the `Handler`. After close has been called this `Handler` should no longer be used. Method calls may either be silently ignored or may throw runtime exceptions.

public abstract void close()

Close the Handler and free all associated resources.

The close method will perform a flush and then close the Handler. After close has been called this Handler should no longer be used. Method calls may either be silently ignored or may throw runtime exceptions.

flush	back to summary
public abstract void flush() Flush any buffered output.

getEncoding back to summary

getEncoding	back to summary
public String getEncoding() Return the character encoding for this `Handler`. Returns:String The encoding name. May be null, which indicates the default encoding should be used.

public String getEncoding()

Return the character encoding for this Handler.

Returns:String: The encoding name. May be null, which indicates the default encoding should be used.

getErrorManager	back to summary
public ErrorManager getErrorManager() Retrieves the ErrorManager for this Handler. Returns:ErrorManager the ErrorManager for this Handler

getErrorManager

back to summary

public ErrorManager getErrorManager()

Retrieves the ErrorManager for this Handler.

Returns:ErrorManager: the ErrorManager for this Handler

getFilter back to summary

getFilter	back to summary
public Filter getFilter() Get the current `Filter` for this `Handler`. Returns:Filter a `Filter` object (may be null)

public Filter getFilter()

Get the current Filter for this Handler.

Returns:Filter: a Filter object (may be null)

getFormatter back to summary

getFormatter	back to summary
public Formatter getFormatter() Return the `Formatter` for this `Handler`. Returns:Formatter the `Formatter` (may be null).

public Formatter getFormatter()

Return the Formatter for this Handler.

Returns:Formatter: the Formatter (may be null).

getLevel back to summary

getLevel	back to summary
public Level getLevel() Get the log level specifying which messages will be logged by this `Handler`. Message levels lower than this level will be discarded. Returns:Level the level of messages being logged.

public Level getLevel()

Get the log level specifying which messages will be logged by this Handler. Message levels lower than this level will be discarded.

Returns:Level: the level of messages being logged.

isLoggable back to summary

isLoggable	back to summary
public boolean isLoggable(LogRecord record) Check if this `Handler` would actually log a given `LogRecord`. This method checks if the `LogRecord` has an appropriate `Level` and whether it satisfies any `Filter`. It also may make other `Handler` specific checks that might prevent a handler from logging the `LogRecord`. It will return false if the `LogRecord` is null. Parameters record:LogRecord a `LogRecord` (may be null). Returns:boolean true if the `LogRecord` would be logged.

public boolean isLoggable(LogRecord record)

Check if this Handler would actually log a given LogRecord.

This method checks if the LogRecord has an appropriate Level and whether it satisfies any Filter. It also may make other Handler specific checks that might prevent a handler from logging the LogRecord. It will return false if the LogRecord is null.

Parameters

record:LogRecord: a LogRecord (may be null).

Returns:boolean

true if the LogRecord would be logged.

publish back to summary

publish	back to summary
public abstract void publish(LogRecord record) Publish a `LogRecord`. The logging request was made initially to a `Logger` object, which initialized the `LogRecord` and forwarded it here. The `Handler` is responsible for formatting the message, when and if necessary. The formatting should include localization. API Note To avoid the risk of deadlock, implementations of this method should avoid holding any locks while calling out to application code, such as the formatting of `LogRecord`. Parameters record:LogRecord description of the log event. A null record is silently ignored and is not published

public abstract void publish(LogRecord record)

Publish a LogRecord.

The logging request was made initially to a Logger object, which initialized the LogRecord and forwarded it here.

The Handler is responsible for formatting the message, when and if necessary. The formatting should include localization.

API Note

To avoid the risk of deadlock, implementations of this method should avoid holding any locks while calling out to application code, such as the formatting of LogRecord.

Parameters

record:LogRecord: description of the log event. A null record is silently ignored and is not published

reportError	back to summary
protected void reportError(String msg, Exception ex, int code) Protected convenience method to report an error to this Handler's ErrorManager. Parameters msg:String a descriptive string (may be null) ex:Exception an exception (may be null) code:int an error code defined in ErrorManager

reportError

back to summary

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

Protected convenience method to report an error to this Handler's ErrorManager.

Parameters

msg:String: a descriptive string (may be null)
ex:Exception: an exception (may be null)
code:int: an error code defined in ErrorManager

setEncoding back to summary

setEncoding	back to summary
public synchronized void setEncoding(String encoding) throws UnsupportedEncodingException Set the character encoding used by this `Handler`. The encoding should be set before any `LogRecords` are written to the `Handler`. Parameters encoding:String The name of a supported character encoding. May be null, to indicate the default platform encoding. Exceptions UnsupportedEncodingException: if the named encoding is not supported.

public synchronized void setEncoding(String encoding) throws UnsupportedEncodingException

Set the character encoding used by this Handler.

The encoding should be set before any LogRecords are written to the Handler.

Parameters

encoding:String: The name of a supported character encoding. May be null, to indicate the default platform encoding.

Exceptions

UnsupportedEncodingException:: if the named encoding is not supported.

setErrorManager	back to summary
public synchronized void setErrorManager(ErrorManager em) Define an ErrorManager for this Handler. The ErrorManager's "error" method will be invoked if any errors occur while using this Handler. Parameters em:ErrorManager the new ErrorManager

setErrorManager

back to summary

public synchronized void setErrorManager(ErrorManager em)

Define an ErrorManager for this Handler.

The ErrorManager's "error" method will be invoked if any errors occur while using this Handler.

Parameters

em:ErrorManager: the new ErrorManager

setFilter back to summary

setFilter	back to summary
public synchronized void setFilter(Filter newFilter) Set a `Filter` to control output on this `Handler`. For each call of `publish` the `Handler` will call this `Filter` (if it is non-null) to check if the `LogRecord` should be published or discarded. Parameters newFilter:Filter a `Filter` object (may be null)

public synchronized void setFilter(Filter newFilter)

Set a Filter to control output on this Handler.

For each call of publish the Handler will call this Filter (if it is non-null) to check if the LogRecord should be published or discarded.

Parameters

newFilter:Filter: a Filter object (may be null)

setFormatter back to summary

setFormatter	back to summary
public synchronized void setFormatter(Formatter newFormatter) Set a `Formatter`. This `Formatter` will be used to format `LogRecords` for this `Handler`. Some `Handlers` may not use `Formatters`, in which case the `Formatter` will be remembered, but not used. Parameters newFormatter:Formatter the `Formatter` to use (may not be null)

public synchronized void setFormatter(Formatter newFormatter)

Set a Formatter. This Formatter will be used to format LogRecords for this Handler.

Some Handlers may not use Formatters, in which case the Formatter will be remembered, but not used.

Parameters

newFormatter:Formatter: the Formatter to use (may not be null)

setLevel back to summary

setLevel	back to summary
public synchronized void setLevel(Level newLevel) Set the log level specifying which message levels will be logged by this `Handler`. Message levels lower than this value will be discarded. The intention is to allow developers to turn on voluminous logging, but to limit the messages that are sent to certain `Handlers`. Parameters newLevel:Level the new value for the log level

public synchronized void setLevel(Level newLevel)

Set the log level specifying which message levels will be logged by this Handler. Message levels lower than this value will be discarded.

The intention is to allow developers to turn on voluminous logging, but to limit the messages that are sent to certain Handlers.

Parameters

newLevel:Level: the new value for the log level

public abstract Class Handler

Thread Safety and Deadlock Risk in Handlers

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail