Handler (Java SE 26 & JDK 26)
Description: declaration: module: java.logging, package: java.util.logging, class: Handler
Keywords: java.util.logging.Handler class

# Class Handler

java.lang.Object
java.util.logging.Handler

Direct Known Subclasses:
  `MemoryHandler, StreamHandler`

public abstract class Handler extends Object
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.

Since:
  1.4

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Handler()`
  Default constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `close()`
  Close the `Handler` and free all associated resources.
  `abstract void`
  `flush()`
  Flush any buffered output.
  `String`
  `getEncoding()`
  Return the character encoding for this `Handler`.
  `ErrorManager`
  `getErrorManager()`
  Retrieves the ErrorManager for this Handler.
  `Filter`
  `getFilter()`
  Get the current `Filter` for this `Handler`.
  `Formatter`
  `getFormatter()`
  Return the `Formatter` for this `Handler`.
  `Level`
  `getLevel()`
  Get the log level specifying which messages will be logged by this `Handler`.
  `boolean`
  `isLoggable(LogRecord record)`
  Check if this `Handler` would actually log a given `LogRecord`.
  `abstract void`
  `publish(LogRecord record)`
  Publish a `LogRecord`.
  `protected void`
  `reportError(String msg, Exception ex, int code)`
  Protected convenience method to report an error to this Handler's ErrorManager.
  `void`
  `setEncoding(String encoding)`
  Set the character encoding used by this `Handler`.
  `void`
  `setErrorManager(ErrorManager em)`
  Define an ErrorManager for this Handler.
  `void`
  `setFilter(Filter newFilter)`
  Set a `Filter` to control output on this `Handler`.
  `void`
  `setFormatter(Formatter newFormatter)`
  Set a `Formatter`.
  `void`
  `setLevel(Level newLevel)`
  Set the log level specifying which message levels will be logged by this `Handler`.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Constructor Details

  - ### Handler

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

- ## Method Details

  - ### publish

    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` - description of the log event. A null record is silently ignored and is not published

  - ### flush

    public abstract void flush()
    Flush any buffered output.

  - ### close

    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.

  - ### setFormatter

    public 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` - the `Formatter` to use (may not be null)

  - ### getFormatter

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

  - ### setEncoding

    public 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` - The name of a supported character encoding. May be null, to indicate the default platform encoding.
    Throws:
      `UnsupportedEncodingException` - if the named encoding is not supported.

  - ### getEncoding

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

  - ### setFilter

    public 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` - a `Filter` object (may be null)

  - ### getFilter

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

  - ### setErrorManager

    public 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` - the new ErrorManager

  - ### getErrorManager

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

  - ### reportError

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

  - ### setLevel

    public 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` - the new value for the log level

  - ### getLevel

    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:
      the level of messages being logged.

  - ### isLoggable

    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` - a `LogRecord` (may be null).
    Returns:
      true if the `LogRecord` would be logged.