Класс Handler

java.lang.Object

java.util.logging.Handler

Прямые известные подклассы:: MemoryHandler, StreamHandler

public abstract class Handler extends Object

Объект Handler получает сообщения журнала от Logger и экспортирует их. Например, он может выводить их в консоль или записывать в файл, отправлять в сетевую службу ведения журнала, передавать в журнал ОС или выполнять любые другие действия.

Handler можно отключить с помощью setLevel(Level.OFF) и повторно включить с помощью setLevel с подходящим уровнем.

Классы Handler обычно используют свойства LogManager для задания значений по умолчанию для Handler: Filter, Formatter и Level. См. документацию по каждому конкретному классу Handler.

Потокобезопасность и риск взаимной блокировки в обработчиках

Реализации Handler должны быть потокобезопасными. Предполагается, что обработчики могут вызываться одновременно из произвольных потоков. Однако чрезмерное использование синхронизации может привести к нежелательной конкуренции потоков, проблемам с производительностью и даже к взаимной блокировке.

В частности, подклассам следует избегать захвата блокировок вокруг кода, который вызывает методы произвольных объектов, предоставленных пользователем, особенно при форматировании записей журнала. Удержание блокировки во время таких обратных вызовов создает риск взаимной блокировки между кодом ведения журнала и пользовательским кодом.

Поэтому подклассам Handler общего назначения не следует синхронизировать методы publish(LogRecord) или вызывать super.publish(), удерживая блокировки, поскольку обычно предполагается, что эти методы обрабатывают и форматируют аргументы, предоставленные пользователем.

Начиная с:: 1.4

Краткое описание конструкторов

Handler()

Модификатор	Конструктор	Описание
`protected`	Конструктор по умолчанию.

Краткое описание методов

Модификатор и тип	Метод	Описание
`abstract void`	`close()`	Закрывает `Handler` и освобождает все связанные с ним ресурсы.
`abstract void`	`flush()`	Сбрасывает все буферизованные выходные данные.
`String`	`getEncoding()`	Возвращает кодировку символов для этого `Handler`.
`ErrorManager`	`getErrorManager()`	Получает ErrorManager для этого Handler.
`Filter`	`getFilter()`	Получает текущий `Filter` для этого `Handler`.
`Formatter`	`getFormatter()`	Возвращает `Formatter` для этого `Handler`.
`Level`	`getLevel()`	Получает уровень журнала, определяющий, какие сообщения будут записываться этим `Handler`.
`boolean`	`isLoggable(LogRecord record)`	Проверяет, будет ли этот `Handler` фактически записывать указанный `LogRecord`.
`abstract void`	`publish(LogRecord record)`	Публикует `LogRecord`.
`protected void`	`reportError(String msg, Exception ex, int code)`	Защищенный вспомогательный метод для передачи ошибки в ErrorManager данного Handler.
`void`	`setEncoding(String encoding)`	Задает кодировку символов, используемую этим `Handler`.
`void`	`setErrorManager(ErrorManager em)`	Задает ErrorManager для этого Handler.
`void`	`setFilter(Filter newFilter)`	Задает `Filter` для управления выводом этого `Handler`.
`void`	`setFormatter(Formatter newFormatter)`	Задает `Formatter`.
`void`	`setLevel(Level newLevel)`	Задает уровень журнала, определяющий, сообщения каких уровней будут записываться этим `Handler`.

Методы, объявленные в классе Object

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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`boolean`	`equals(Object obj)`	Указывает, равен ли другой объект этому объекту.
`protected void`	`finalize()`	Устарело, будет удалено: этот элемент API подлежит удалению в будущей версии. Финализация объявлена устаревшей и подлежит удалению в одном из будущих выпусков.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`int`	`hashCode()`	Возвращает хеш-код этого объекта.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`String`	`toString()`	Возвращает строковое представление объекта.
`final void`	`wait()`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством вызова метода notify или interrupt.
`final void`	`wait(long timeoutMillis)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством вызова метода notify или interrupt, либо до истечения заданного времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Переводит текущий поток в состояние ожидания до его пробуждения, обычно посредством вызова метода notify или interrupt, либо до истечения заданного времени.

Подробное описание конструкторов

Handler

protected Handler()

Конструктор по умолчанию. Создаваемый Handler имеет уровень журнала Level.ALL, не имеет Formatter и Filter. Экземпляр ErrorManager по умолчанию устанавливается как ErrorManager.

Подробное описание методов

publish

public abstract void publish(LogRecord record)

Публикует LogRecord.

Запрос на ведение журнала изначально был направлен объекту Logger, который инициализировал LogRecord и передал его сюда.

Handler отвечает за форматирование сообщения, когда это необходимо. Форматирование должно учитывать локализацию.

Примечание API:: Чтобы избежать риска взаимной блокировки, реализациям этого метода следует избегать удержания блокировок при вызове кода приложения, например при форматировании LogRecord.
Параметры:: record — описание события журнала. Запись со значением null молча игнорируется и не публикуется

flush

public abstract void flush()

Сбрасывает все буферизованные выходные данные.

close

public abstract void close()

Закрывает Handler и освобождает все связанные с ним ресурсы.

Метод close выполняет flush, а затем закрывает Handler. После вызова close этот Handler больше не следует использовать. Вызовы методов могут молча игнорироваться или приводить к исключениям времени выполнения.

setFormatter

public void setFormatter(Formatter newFormatter)

Задает Formatter. Этот Formatter будет использоваться для форматирования LogRecords для этого Handler.

Некоторые Handlers могут не использовать Formatters; в таком случае Formatter будет сохранен, но не будет использоваться.

Параметры:: newFormatter — используемый Formatter (не может иметь значение null)

getFormatter

public Formatter getFormatter()

Возвращает Formatter для этого Handler.

Возвращает:: Formatter (может иметь значение null).

setEncoding

public void setEncoding(String encoding) throws UnsupportedEncodingException

Задает кодировку символов, используемую этим Handler.

Кодировку следует задать до записи каких-либо LogRecords в Handler.

Параметры:: encoding — имя поддерживаемой кодировки символов. Может иметь значение null, указывающее на использование кодировки платформы по умолчанию.
Исключения:: UnsupportedEncodingException — если указанная кодировка не поддерживается.

getEncoding

public String getEncoding()

Возвращает кодировку символов для этого Handler.

Возвращает:: Имя кодировки. Может иметь значение null, указывающее на необходимость использовать кодировку по умолчанию.

setFilter

public void setFilter(Filter newFilter)

Задает Filter для управления выводом этого Handler.

При каждом вызове publish Handler вызывает этот Filter (если он не равен null), чтобы проверить, следует ли публиковать или отбрасывать LogRecord.

Параметры:: newFilter — объект Filter (может иметь значение null)

getFilter

public Filter getFilter()

Получает текущий Filter для этого Handler.

Возвращает:: объект Filter (может иметь значение null)

setErrorManager

public void setErrorManager(ErrorManager em)

Задает ErrorManager для этого Handler.

Метод "error" объекта ErrorManager будет вызван при возникновении ошибок во время использования этого Handler.

Параметры:: em — новый ErrorManager

getErrorManager

public ErrorManager getErrorManager()

Получает ErrorManager для этого Handler.

Возвращает:: ErrorManager для этого Handler

reportError

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

Защищенный вспомогательный метод для передачи ошибки в ErrorManager данного Handler.

Параметры:: msg — описательная строка (может иметь значение null); ex — исключение (может иметь значение null); code — код ошибки, определенный в ErrorManager

setLevel

public void setLevel(Level newLevel)

Задает уровень журнала, определяющий, сообщения каких уровней будут записываться этим Handler. Сообщения с уровнем ниже этого значения будут отброшены.

Это позволяет разработчикам включать подробное ведение журнала, ограничивая при этом сообщения, отправляемые определенным Handlers.

Параметры:: newLevel — новое значение уровня журнала

getLevel

public Level getLevel()

Получает уровень журнала, определяющий, какие сообщения будут записываться этим Handler. Сообщения с уровнем ниже этого значения будут отброшены.

Возвращает:: уровень записываемых сообщений.

isLoggable

public boolean isLoggable(LogRecord record)

Проверяет, будет ли этот Handler фактически записывать указанный LogRecord.

Этот метод проверяет, имеет ли LogRecord подходящий Level и удовлетворяет ли он всем Filter. Кроме того, он может выполнять другие проверки, специфичные для Handler, которые могут помешать обработчику записать LogRecord. Метод вернет false, если LogRecord имеет значение null.

Параметры:: record — LogRecord (может иметь значение null).
Возвращает:: true, если LogRecord будет записан.

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.