Класс 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 для этого обработчика.
`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 этого обработчика.
`void`	`setEncoding(String encoding)`	Задает кодировку символов, используемую этим `Handler`.
`void`	`setErrorManager(ErrorManager em)`	Задает ErrorManager для этого обработчика.
`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

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

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 для этого обработчика.

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

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

getErrorManager

public ErrorManager getErrorManager()

Получает ErrorManager для этого обработчика.

Возвращает:: ErrorManager для этого обработчика

reportError

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

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

Параметры:: 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.
https://docs.oracle.com/en/java/javase/25/docs/api/java.logging/java/util/logging/Handler.html