Класс 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 обычно приведет к записи лог-файлов в /var/tmp/java0.log и /var/tmp/java1.log на Solaris, а в 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

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

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

FileHandler

public FileHandler(String pattern)
            throws IOException,
                   SecurityException

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

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

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

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

FileHandler

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

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

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

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

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

FileHandler

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

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

FileHandler настраивается на основе свойств LogManager (или их значений по умолчанию), за исключением того, что переданный аргумент pattern используется в качестве шаблона имени файла, предел файла устанавливается в значение аргумента limit, а количество файлов устанавливается в значение аргумента 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 для записи в набор файлов с опцией добавления. Когда (приблизительно) заданный предел достигнут в одном файле, открывается другой файл. Вывод циклически переключается между набором файлов, количество которых указано.

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

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

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

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

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

Методы

publish

public void publish(LogRecord record)

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

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

close

public void close()
           throws SecurityException

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

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

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

Spec-Zone .ru
спецификации, руководства, описания, API