Package org.jboss.logmanager

## Class ExtHandler

- java.lang.Object
- - java.util.logging.Handler
  - - org.jboss.logmanager.ExtHandler

All Implemented Interfaces:
  `java.io.Closeable`, `java.io.Flushable`, `java.lang.AutoCloseable`, `FlushableCloseable`, `Protectable`

Direct Known Subclasses:
  `AsyncHandler`, `DelayedHandler`, `NullHandler`, `QueueHandler`, `SocketHandler`, `SyslogHandler`, `WriterHandler`

    public abstract class ExtHandler
    extends java.util.logging.Handler
    implements FlushableCloseable, Protectable

An extended logger handler. Use this class as a base class for log handlers which require `ExtLogRecord` instances.

### Field Summary

Fields
`protected java.util.logging.Handler[]` `handlers` The sub-handlers for this handler.
`protected static org.jboss.logmanager.AtomicArray<ExtHandler,java.util.logging.Handler>` `handlersUpdater` The atomic updater for the `handlers` field.

### Constructor Summary

Constructors
`protected` `ExtHandler()` Construct a new instance.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
`void` `addHandler​(java.util.logging.Handler handler)` Add a sub-handler to this handler.
`protected static void` `checkAccess()` Deprecated. use `checkAccess(ExtHandler)`
`protected static void` `checkAccess​(ExtHandler handler)` Check access.
`java.util.logging.Handler[]` `clearHandlers()` A convenience method to atomically get and clear all sub-handlers.
`void` `close()` Close all child handlers.
`void` `disableAccess()` Disable previous access to the object for modifications on the current thread.
`protected void` `doPublish​(ExtLogRecord record)` Do the actual work of publication; the record will have been filtered already.
`void` `enableAccess​(java.lang.Object protectKey)` Enable access to the object for modifications on the current thread.
`void` `flush()` Flush all child handlers.
`java.util.logging.Handler[]` `getHandlers()` Get a copy of the sub-handlers array.
`boolean` `isAutoFlush()` Determine if this handler will auto-flush.
`boolean` `isCallerCalculationRequired()` Indicates whether or not the formatter associated with this handler or a formatter from a child handler requires the caller to be calculated.
`boolean` `isCloseChildren()` Indicates whether or not children handlers should be closed when this handler is closed.
`boolean` `isEnabled()` Determine if the handler is enabled.
`void` `protect​(java.lang.Object protectionKey)` Protect this object from modifications.
`void` `publish​(java.util.logging.LogRecord record)`
`void` `publish​(ExtLogRecord record)` Publish an `ExtLogRecord`.
`void` `removeHandler​(java.util.logging.Handler handler)` Remove a sub-handler from this handler.
`void` `setAutoFlush​(boolean autoFlush)` Change the autoflush setting for this handler.
`void` `setCloseChildren​(boolean closeChildren)` Sets whether or not children handlers should be closed when this handler is closed.
`void` `setEnabled​(boolean enabled)` Enables or disables the handler based on the value passed in.
`void` `setEncoding​(java.lang.String encoding)`
`void` `setErrorManager​(java.util.logging.ErrorManager em)`
`void` `setFilter​(java.util.logging.Filter newFilter)`
`void` `setFormatter​(java.util.logging.Formatter newFormatter)`
`java.util.logging.Handler[]` `setHandlers​(java.util.logging.Handler[] newHandlers)` A convenience method to atomically get and replace the sub-handler array.
`void` `setLevel​(java.util.logging.Level newLevel)`
`void` `unprotect​(java.lang.Object protectionKey)` Allows the object to be modified if the `protectionKey` matches the key used to `protect` the object.

### Methods inherited from class java.util.logging.Handler

`getEncoding, getErrorManager, getFilter, getFormatter, getLevel, isLoggable, reportError`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### handlers

    protected volatile java.util.logging.Handler[] handlers

The sub-handlers for this handler. May only be updated using the `handlersUpdater` atomic updater. The array instance should not be modified (treat as immutable).

#### handlersUpdater

    protected static final org.jboss.logmanager.AtomicArray<ExtHandler,java.util.logging.Handler> handlersUpdater

The atomic updater for the `handlers` field.

### Constructor Detail

#### ExtHandler

    protected ExtHandler()

Construct a new instance.

### Method Detail

#### publish

    public void publish​(java.util.logging.LogRecord record)

Specified by:
  `publish` in class `java.util.logging.Handler`

#### publish

    public void publish​(ExtLogRecord record)

Publish an `ExtLogRecord`.

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

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

Parameters:
  `record` - the log record to publish

#### doPublish

    protected void doPublish​(ExtLogRecord record)

Do the actual work of publication; the record will have been filtered already. The default implementation does nothing except to flush if the `autoFlush` property is set to `true`; if this behavior is to be preserved in a subclass then this method should be called after the record is physically written.

Parameters:
  `record` - the log record to publish

#### addHandler

    public void addHandler​(java.util.logging.Handler handler)
                    throws java.lang.SecurityException

Add a sub-handler to this handler. Some handler types do not utilize sub-handlers.

Parameters:
  `handler` - the handler to add
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### removeHandler

    public void removeHandler​(java.util.logging.Handler handler)
                       throws java.lang.SecurityException

Remove a sub-handler from this handler. Some handler types do not utilize sub-handlers.

Parameters:
  `handler` - the handler to remove
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### getHandlers

    public java.util.logging.Handler[] getHandlers()

Get a copy of the sub-handlers array. Since the returned value is a copy, it may be freely modified.

Returns:
  a copy of the sub-handlers array

#### clearHandlers

    public java.util.logging.Handler[] clearHandlers()
                                              throws java.lang.SecurityException

A convenience method to atomically get and clear all sub-handlers.

Returns:
  the old sub-handler array
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### setHandlers

    public java.util.logging.Handler[] setHandlers​(java.util.logging.Handler[] newHandlers)
                                            throws java.lang.SecurityException

A convenience method to atomically get and replace the sub-handler array.

Parameters:
  `newHandlers` - the new sub-handlers
Returns:
  the old sub-handler array
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### isAutoFlush

    public boolean isAutoFlush()

Determine if this handler will auto-flush.

Returns:
  `true` if auto-flush is enabled

#### setAutoFlush

    public void setAutoFlush​(boolean autoFlush)
                      throws java.lang.SecurityException

Change the autoflush setting for this handler.

Parameters:
  `autoFlush` - `true` to automatically flush after each write; false otherwise
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### setEnabled

    public final void setEnabled​(boolean enabled)
                          throws java.lang.SecurityException

Enables or disables the handler based on the value passed in.

Parameters:
  `enabled` - `true` to enable the handler or `false` to disable the handler.
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### isEnabled

    public final boolean isEnabled()

Determine if the handler is enabled.

Returns:
  `true` if the handler is enabled, otherwise `false`.

#### isCloseChildren

    public boolean isCloseChildren()

Indicates whether or not children handlers should be closed when this handler is closed.

Returns:
  `true` if the children handlers should be closed when this handler is closed, `false` if children handlers should not be closed when this handler is closed

#### setCloseChildren

    public void setCloseChildren​(boolean closeChildren)

Sets whether or not children handlers should be closed when this handler is closed.

Parameters:
  `closeChildren` - `true` if all children handlers should be closed when this handler is closed, `false` if children handlers will not be closed when this handler is closed

#### protect

    public final void protect​(java.lang.Object protectionKey)
                       throws java.lang.SecurityException

Description copied from interface: `Protectable`
Protect this object from modifications.

Specified by:
  `protect` in interface `Protectable`
Parameters:
  `protectionKey` - the key used to protect the object.
Throws:
  `java.lang.SecurityException` - if the object is already protected.

#### unprotect

    public final void unprotect​(java.lang.Object protectionKey)
                         throws java.lang.SecurityException

Description copied from interface: `Protectable`
Allows the object to be modified if the `protectionKey` matches the key used to `protect` the object.

Specified by:
  `unprotect` in interface `Protectable`
Parameters:
  `protectionKey` - the key used to protect the object.
Throws:
  `java.lang.SecurityException` - if the object is protected and the key doesn't match.

#### enableAccess

    public final void enableAccess​(java.lang.Object protectKey)

Description copied from interface: `Protectable`
Enable access to the object for modifications on the current thread.

Specified by:
  `enableAccess` in interface `Protectable`
Parameters:
  `protectKey` - the key used to `protect` modifications.

#### disableAccess

    public final void disableAccess()

Description copied from interface: `Protectable`
Disable previous access to the object for modifications on the current thread.

Specified by:
  `disableAccess` in interface `Protectable`

#### checkAccess

    @Deprecated
    protected static void checkAccess()
                               throws java.lang.SecurityException

Deprecated.
use `checkAccess(ExtHandler)`
Check access.

Throws:
  `java.lang.SecurityException` - if a security manager is installed and the caller does not have the `"control" LoggingPermission`

#### checkAccess

    protected static void checkAccess​(ExtHandler handler)
                               throws java.lang.SecurityException

Check access.

Parameters:
  `handler` - the handler to check access on.
Throws:
  `java.lang.SecurityException` - if a security manager exists and if the caller does not have `LoggingPermission(control)` or the handler is `protected`.

#### flush

    public void flush()

Flush all child handlers.

Specified by:
  `flush` in interface `java.io.Flushable`
Specified by:
  `flush` in class `java.util.logging.Handler`

#### close

    public void close()
               throws java.lang.SecurityException

Close all child handlers.

Specified by:
  `close` in interface `java.lang.AutoCloseable`
Specified by:
  `close` in interface `java.io.Closeable`
Specified by:
  `close` in class `java.util.logging.Handler`
Throws:
  `java.lang.SecurityException`

#### setFormatter

    public void setFormatter​(java.util.logging.Formatter newFormatter)
                      throws java.lang.SecurityException

Overrides:
  `setFormatter` in class `java.util.logging.Handler`
Throws:
  `java.lang.SecurityException`

#### setFilter

    public void setFilter​(java.util.logging.Filter newFilter)
                   throws java.lang.SecurityException

Overrides:
  `setFilter` in class `java.util.logging.Handler`
Throws:
  `java.lang.SecurityException`

#### setEncoding

    public void setEncoding​(java.lang.String encoding)
                     throws java.lang.SecurityException,
                            java.io.UnsupportedEncodingException

Overrides:
  `setEncoding` in class `java.util.logging.Handler`
Throws:
  `java.lang.SecurityException`
  `java.io.UnsupportedEncodingException`

#### setErrorManager

    public void setErrorManager​(java.util.logging.ErrorManager em)

Overrides:
  `setErrorManager` in class `java.util.logging.Handler`

#### setLevel

    public void setLevel​(java.util.logging.Level newLevel)
                  throws java.lang.SecurityException

Overrides:
  `setLevel` in class `java.util.logging.Handler`
Throws:
  `java.lang.SecurityException`

#### isCallerCalculationRequired

    public boolean isCallerCalculationRequired()

Indicates whether or not the formatter associated with this handler or a formatter from a child handler requires the caller to be calculated.

Calculating the caller on a log record can be an expensive operation. Some handlers may be required to copy some data from the log record, but may not need the caller information. If the formatter is a `ExtFormatter` the `ExtFormatter.isCallerCalculationRequired()` is used to determine if calculation of the caller is required.

Returns:
  `true` if the caller should be calculated, otherwise `false` if it can be skipped
See Also:
  `LogRecord.getSourceClassName()`, `ExtLogRecord.getSourceFileName()`, `ExtLogRecord.getSourceLineNumber()`, `LogRecord.getSourceMethodName()`