Package org.jboss.logmanager

# Class ExtHandler

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

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`, `FlushableCloseable`, `Protectable`

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

public abstract class ExtHandler extends 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
Modifier and Type
Field
Description
`protected Handler[]`
`handlers`
The sub-handlers for this handler.
`protected static final org.jboss.logmanager.AtomicArray<ExtHandler,Handler>`
`handlersUpdater`
The atomic updater for the `handlers` field.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`ExtHandler()`
Construct a new instance.

## Method Summary

Modifier and Type
Method
Description
`void`
`addHandler(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.
`Handler[]`
`clearHandlers()`
A convenience method to atomically get and clear all sub-handlers.
`void`
`close()`
Close all child handlers.
`final 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.
`final void`
`enableAccess(Object protectKey)`
Enable access to the object for modifications on the current thread.
`void`
`flush()`
Flush all child handlers.
`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.
`final boolean`
`isEnabled()`
Determine if the handler is enabled.
`final void`
`protect(Object protectionKey)`
Protect this object from modifications.
`void`
`publish(LogRecord record)`
`void`
`publish(ExtLogRecord record)`
Publish an `ExtLogRecord`.
`void`
`removeHandler(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.
`final void`
`setEnabled(boolean enabled)`
Enables or disables the handler based on the value passed in.
`void`
`setEncoding(String encoding)`
`void`
`setErrorManager(ErrorManager em)`
`void`
`setFilter(Filter newFilter)`
`void`
`setFormatter(Formatter newFormatter)`
`Handler[]`
`setHandlers(Handler[] newHandlers)`
A convenience method to atomically get and replace the sub-handler array.
`void`
`setLevel(Level newLevel)`
`final void`
`unprotect(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 Details

### handlers

protected volatile 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,Handler> handlersUpdater
The atomic updater for the `handlers` field.

## Constructor Details

### ExtHandler

protected ExtHandler()
Construct a new instance.

## Method Details

### publish

public void publish(LogRecord record)

Specified by:
  `publish` in class `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(Handler handler) throws SecurityException
Add a sub-handler to this handler. Some handler types do not utilize sub-handlers.

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

### removeHandler

public void removeHandler(Handler handler) throws SecurityException
Remove a sub-handler from this handler. Some handler types do not utilize sub-handlers.

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

### getHandlers

public 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 Handler[] clearHandlers() throws SecurityException
A convenience method to atomically get and clear all sub-handlers.

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

### setHandlers

public Handler[] setHandlers(Handler[] newHandlers) throws 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:
  `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 SecurityException
Change the autoflush setting for this handler.

Parameters:
  `autoFlush` - `true` to automatically flush after each write; false otherwise
Throws:
  `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 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:
  `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(Object protectionKey) throws 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:
  `SecurityException` - if the object is already protected.

### unprotect

public final void unprotect(Object protectionKey) throws 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:
  `SecurityException` - if the object is protected and the key doesn't match.

### enableAccess

public final void enableAccess(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 SecurityException
Deprecated.
use `checkAccess(ExtHandler)`
Check access.

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

### checkAccess

protected static void checkAccess(ExtHandler handler) throws SecurityException
Check access.

Parameters:
  `handler` - the handler to check access on.
Throws:
  `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 `Flushable`
Specified by:
  `flush` in class `Handler`

### close

public void close() throws SecurityException
Close all child handlers.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Specified by:
  `close` in class `Handler`
Throws:
  `SecurityException`

### setFormatter

public void setFormatter(Formatter newFormatter) throws SecurityException

Overrides:
  `setFormatter` in class `Handler`
Throws:
  `SecurityException`

### setFilter

public void setFilter(Filter newFilter) throws SecurityException

Overrides:
  `setFilter` in class `Handler`
Throws:
  `SecurityException`

### setEncoding

public void setEncoding(String encoding) throws SecurityException, UnsupportedEncodingException

Overrides:
  `setEncoding` in class `Handler`
Throws:
  `SecurityException`
  `UnsupportedEncodingException`

### setErrorManager

public void setErrorManager(ErrorManager em)

Overrides:
  `setErrorManager` in class `Handler`

### setLevel

public void setLevel(Level newLevel) throws SecurityException

Overrides:
  `setLevel` in class `Handler`
Throws:
  `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()`