Класс FileHandler

java.util.logging.FileHandler

public class FileHandler extends StreamHandler

Простое ведение журнала в файлы Handler.

FileHandler может записывать данные в указанный файл или в набор сменяющих друг друга файлов.

При использовании набора сменяющих друг друга файлов, когда размер каждого файла достигает заданного предела, он закрывается, заменяется следующим, и открывается новый файл. Имена последовательно более старых файлов формируются добавлением «0», «1», «2» и т. д. к базовому имени файла.

По умолчанию в библиотеках ввода-вывода включена буферизация, но каждая запись журнала сбрасывается после завершения.

По умолчанию для форматирования используется класс XMLFormatter.

Конфигурация: По умолчанию каждый FileHandler инициализируется с использованием следующих свойств конфигурации LogManager, где <handler-name> — полное имя класса обработчика. Если свойства не заданы (или имеют недопустимые значения), используются указанные значения по умолчанию.

<handler-name>.level задает уровень по умолчанию для Handler (по умолчанию — Level.ALL).
<handler-name>.filter задает имя класса Filter, который следует использовать (по умолчанию Filter не используется).
<handler-name>.formatter задает имя класса Formatter, который следует использовать (по умолчанию — java.util.logging.XMLFormatter)
<handler-name>.encoding задает имя используемой кодировки набора символов (по умолчанию используется кодировка платформы).
<handler-name>.limit задает приблизительный максимальный объем данных (в байтах), записываемых в один файл. Если значение равно нулю, ограничение отсутствует. (По умолчанию ограничение отсутствует).
<handler-name>.count задает количество циклически используемых выходных файлов (по умолчанию — 1).
<handler-name>.pattern задает шаблон для формирования имени выходного файла. Подробности см. ниже. (По умолчанию — "%h/java%u.log").
<handler-name>.append задает, должен ли FileHandler добавлять данные в существующие файлы (по умолчанию — false).
<handler-name>.maxLocks задает максимальное количество блокировок, одновременно удерживаемых FileHandler (по умолчанию — 100).

Например, свойства для FileHandler будут следующими:

java.util.logging.FileHandler.level=INFO
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

Для пользовательского обработчика, например com.foo.MyHandler, свойства будут следующими:

com.foo.MyHandler.level=INFO
com.foo.MyHandler.formatter=java.util.logging.SimpleFormatter

Шаблон представляет собой строку, содержащую следующие специальные компоненты, которые заменяются во время выполнения:

"/" — разделитель локальных путей
"%t" — временный каталог системы
"%h" — значение системного свойства "user.home"
"%g" — номер поколения, различающий сменяемые файлы журнала
"%u" — уникальный номер для разрешения конфликтов
"%%" — преобразуется в один знак процента "%"

Если поле "%g" не указано, а количество файлов больше единицы, номер поколения добавляется в конец сформированного имени файла после точки.

Так, например, шаблон "%t/java%g.log" при количестве файлов 2 обычно приводит к записи файлов журнала в Solaris в /var/tmp/java0.log и /var/tmp/java1.log, а в Windows 95 — в C:\TEMP\java0.log и C:\TEMP\java1.log

Номера поколений следуют в последовательности 0, 1, 2 и т. д.

Обычно уникальному полю "%u" присваивается значение 0. Однако, если FileHandler пытается открыть файл и обнаруживает, что он уже используется другим процессом, он увеличивает значение уникального поля и повторяет попытку. Это будет продолжаться до тех пор, пока FileHandler не найдет имя файла, которое в данный момент не используется. Если возникает конфликт и поле "%u" не указано, оно добавляется в конец имени файла после точки. (Это происходит после автоматически добавленного номера поколения.)

Так, если три процесса попытаются вести журнал в файлы fred%u.%g.txt, они могут использовать fred0.0.txt, fred1.0.txt и fred2.0.txt в качестве первых файлов своих циклических последовательностей.

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

Начиная с версии:: 1.4

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

Конструктор	Описание
`FileHandler()`	Создает обработчик `FileHandler` по умолчанию.
`FileHandler(String pattern)`	Инициализирует `FileHandler` для записи в указанный файл.
`FileHandler(String pattern, boolean append)`	Инициализирует `FileHandler` для записи в указанный файл с возможностью добавления данных в конец.
`FileHandler(String pattern, int limit, int count)`	Инициализирует `FileHandler` для записи в набор файлов.
`FileHandler(String pattern, int limit, int count, boolean append)`	Инициализирует `FileHandler` для записи в набор файлов с возможностью добавления данных в конец.
`FileHandler(String pattern, long limit, int count, boolean append)`	Инициализирует `FileHandler` для записи в набор файлов с возможностью добавления данных в конец.

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

Модификатор и тип	Метод	Описание
`void`	`close()`	Закрывает все файлы.
`void`	`publish(LogRecord record)`	Форматирует и публикует `LogRecord`.

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

flush, isLoggable, setEncoding, setOutputStream

Модификатор и тип	Метод	Описание
`void`	`flush()`	Сбрасывает все буферизованные сообщения.
`boolean`	`isLoggable(LogRecord record)`	Проверяет, будет ли этот `Handler` действительно записывать заданный `LogRecord`.
`void`	`setEncoding(String encoding)`	Задает (или изменяет) кодировку символов, используемую этим `Handler`.
`protected void`	`setOutputStream(OutputStream out)`	Изменяет выходной поток.

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

getEncoding, getErrorManager, getFilter, getFormatter, getLevel, reportError, setErrorManager, setFilter, setFormatter, setLevel

Модификатор и тип	Метод	Описание
`String`	`getEncoding()`	Возвращает кодировку символов для этого `Handler`.
`ErrorManager`	`getErrorManager()`	Получает ErrorManager этого обработчика.
`Filter`	`getFilter()`	Получает текущий `Filter` для этого `Handler`.
`Formatter`	`getFormatter()`	Возвращает `Formatter` для этого `Handler`.
`Level`	`getLevel()`	Получает уровень ведения журнала, определяющий, какие сообщения будут записываться этим `Handler`.
`protected void`	`reportError(String msg, Exception ex, int code)`	Защищенный вспомогательный метод для передачи ошибки в ErrorManager этого обработчика.
`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

Модификатор и тип	Метод	Описание
`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()`	Приостанавливает текущий поток до его пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Приостанавливает текущий поток до его пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Приостанавливает текущий поток до его пробуждения, обычно посредством уведомления или прерывания, либо до истечения заданного промежутка реального времени.

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

FileHandler

public FileHandler() throws IOException

Создает обработчик FileHandler по умолчанию. Его конфигурация полностью определяется свойствами LogManager (или их значениями по умолчанию).

Выбрасывает:: IOException — если при открытии файлов возникли проблемы ввода-вывода.; NullPointerException — если свойство pattern содержит пустую строку.

FileHandler

public FileHandler(String pattern) throws IOException

Инициализирует FileHandler для записи в указанный файл.

Конфигурация FileHandler определяется свойствами LogManager (или их значениями по умолчанию), за исключением того, что заданный аргумент pattern используется как шаблон имени файла, ограничение размера файла отключается, а количество файлов устанавливается равным единице.

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

Параметры:: pattern — имя выходного файла
Выбрасывает:: IOException — если при открытии файлов возникли проблемы ввода-вывода.; IllegalArgumentException — если pattern — пустая строка

FileHandler

public FileHandler(String pattern, boolean append) throws IOException

Инициализирует FileHandler для записи в указанный файл с возможностью добавления данных в конец.

Конфигурация FileHandler определяется свойствами LogManager (или их значениями по умолчанию), за исключением того, что заданный аргумент pattern используется как шаблон имени файла, ограничение размера файла отключается, количество файлов устанавливается равным единице, а режим добавления данных определяется заданным аргументом append.

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

Параметры:: pattern — имя выходного файла; append — задает режим добавления данных
Выбрасывает:: IOException — если при открытии файлов возникли проблемы ввода-вывода.; IllegalArgumentException — если pattern — пустая строка

FileHandler

public FileHandler(String pattern, int limit, int count) throws IOException

Инициализирует FileHandler для записи в набор файлов. Когда в один файл будет записан (примерно) заданный объем данных, откроется следующий файл. Вывод будет циклически переключаться между заданным количеством файлов.

Конфигурация FileHandler определяется свойствами LogManager (или их значениями по умолчанию), за исключением того, что заданный аргумент pattern используется как шаблон имени файла, ограничение размера файла задается аргументом limit, а количество файлов — заданным аргументом count.

Количество файлов должно быть не меньше 1.

Параметры:: pattern — шаблон для формирования имени выходного файла; limit — максимальное количество байтов, записываемых в один файл; count — количество используемых файлов
Выбрасывает:: IOException — если при открытии файлов возникли проблемы ввода-вывода.; IllegalArgumentException — если limit < 0 или count < 1.; IllegalArgumentException — если pattern — пустая строка

FileHandler

public FileHandler(String pattern, int limit, int count, boolean append) throws IOException

Инициализирует FileHandler для записи в набор файлов с возможностью добавления данных в конец. Когда в один файл будет записан (примерно) заданный объем данных, откроется следующий файл. Вывод будет циклически переключаться между заданным количеством файлов.

Конфигурация FileHandler определяется свойствами LogManager (или их значениями по умолчанию), за исключением того, что заданный аргумент pattern используется как шаблон имени файла, ограничение размера файла задается аргументом limit, количество файлов — заданным аргументом count, а режим добавления данных — заданным аргументом append.

Количество файлов должно быть не меньше 1.

Параметры:: pattern — шаблон для формирования имени выходного файла; limit — максимальное количество байтов, записываемых в один файл; count — количество используемых файлов; append — задает режим добавления данных
Выбрасывает:: IOException — если при открытии файлов возникли проблемы ввода-вывода.; IllegalArgumentException — если limit < 0 или count < 1.; IllegalArgumentException — если pattern — пустая строка

FileHandler

public FileHandler(String pattern, long limit, int count, boolean append) throws IOException

Конфигурация FileHandler определяется свойствами LogManager (или их значениями по умолчанию), за исключением того, что заданный аргумент pattern используется как шаблон имени файла, ограничение размера файла задается аргументом limit, количество файлов — заданным аргументом count, а режим добавления данных — заданным аргументом append.

Количество файлов должно быть не меньше 1.

Параметры:: pattern — шаблон для формирования имени выходного файла; limit — максимальное количество байтов, записываемых в один файл; count — количество используемых файлов; append — задает режим добавления данных
Выбрасывает:: IOException — если при открытии файлов возникли проблемы ввода-вывода.; IllegalArgumentException — если limit < 0 или count < 1.; IllegalArgumentException — если pattern — пустая строка
Начиная с версии:: 9

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

publish

public void publish(LogRecord record)

Форматирует и публикует LogRecord.

Переопределяет:: publish в классе StreamHandler
Параметры:: record — описание события журнала. Запись null молча игнорируется и не публикуется

close

public void close()

Закрывает все файлы.

Переопределяет:: close в классе StreamHandler

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