Класс FileHandler

java.util.logging.FileHandler

public class FileHandler extends StreamHandler

Простая запись логов в файл Handler.

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

При достижении предельного размера файла, он закрывается, и создаётся новый файл. Последовательно более старые файлы именовываются путем добавления "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 в качестве первого файла в своих циклических последовательностях.

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

Since:: 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`.

Методы, унаследованные от класса java.util.logging.StreamHandler

flush, isLoggable, setEncoding, setOutputStream

Методы, унаследованные от класса java.util.logging.Handler

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

Методы, унаследованные от класса java.lang.Object

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

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

FileHandler

public FileHandler() throws IOException, SecurityException

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

Исключение:: IOException - если возникли проблемы с вводом/выводом при открытии файлов.; SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control")).; NullPointerException - если свойство pattern пустая строка.

FileHandler

public FileHandler(String pattern) throws IOException, SecurityException

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

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

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

Параметры:: pattern - имя выходного файла
Исключение:: IOException - если возникли проблемы с вводом/выводом при открытии файлов.; SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control").; IllegalArgumentException - если pattern является пустой строкой

FileHandler

public FileHandler(String pattern, boolean append) throws IOException, SecurityException

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

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

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

Параметры:: pattern - имя выходного файла; append - указывает режим добавления
Исключение:: IOException - если возникли проблемы с вводом/выводом при открытии файлов.; SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control").; IllegalArgumentException - если pattern является пустой строкой

FileHandler

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

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

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

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

Параметры:: pattern - шаблон для именования выходного файла; limit - максимальное количество байтов для записи в любой один файл; count - количество используемых файлов
Исключение:: IOException - если возникли проблемы с вводом/выводом при открытии файлов.; SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control").; IllegalArgumentException - если limit < 0, или count < 1.; IllegalArgumentException - если pattern является пустой строкой

FileHandler

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

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

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

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

Параметры:: pattern - шаблон для именования выходного файла; limit - максимальное количество байтов для записи в любой один файл; count - количество используемых файлов; append - указывает режим добавления
Исключение:: IOException - если возникли проблемы с вводом/выводом при открытии файлов.; SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control").; 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.

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

Параметры:: pattern - шаблон для именования выходного файла; limit - максимальное количество байтов для записи в любой один файл; count - количество используемых файлов; append - указывает режим добавления
Исключение:: IOException - если возникли проблемы с вводом/выводом при открытии файлов.; SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control").; IllegalArgumentException - если limit < 0, или count < 1.; IllegalArgumentException - если pattern является пустой строкой
С тех пор:: 9

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

publish

public void publish(LogRecord record)

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

Переопределяет:: publish в классе StreamHandler
Параметры:: record - описание события логирования. Нулевой объект игнорируется и не публикуется

close

public void close() throws SecurityException

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

Переопределяет:: close в классе StreamHandler
Исключение:: SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет LoggingPermission("control").

© 1993, 2023, 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/21/docs/api/java.logging/java/util/logging/FileHandler.html