Класс LogManager

java.lang.Object

java.util.logging.LogManager

public class LogManager extends Object

Существует единственный глобальный объект LogManager, используемый для поддержания набора общих данных о логгерах и службах регистрации.

Этот объект LogManager:

Управляет иерархическим пространством имён объектов Logger. Все именованные логгеры хранятся в этом пространстве имён.
Управляет набором свойств управления регистрацией. Это простые пары ключ-значение, которые могут использоваться обработчиками (Handlers) и другими объектами регистрации для настройки себя.

Глобальный объект LogManager можно получить с помощью LogManager.getLogManager(). Объект LogManager создается во время инициализации класса и не может быть изменён впоследствии.

При запуске класс LogManager ищется с помощью системной переменной java.util.logging.manager.

Настройка LogManager

LogManager инициализирует конфигурацию регистрации через метод readConfiguration() во время инициализации LogManager. По умолчанию используется конфигурация по умолчанию LogManager. Конфигурация регистрации, считанная LogManager, должна быть в формате файла свойств properties file.

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

java.util.logging.config.class
java.util.logging.config.file

Эти две системные свойства могут быть заданы в командной строке для команды "java" или как определения системных свойств, переданные в JNI_CreateJavaVM.

Свойства (properties) для логгеров и обработчиков (Handlers) будут иметь имена, начинающиеся с имени обработчика или логгера, разделённого точками.
Глобальные свойства регистрации могут включать:

Свойство "handlers". Оно определяет список имён классов обработчиков (handlers), разделённых пробелами или запятыми, для загрузки и регистрации в качестве обработчиков корневого логгера (логгера с именем ""). Каждое имя класса должно соответствовать классу Handler, имеющему конструктор по умолчанию. Обратите внимание, что эти обработчики могут создаваться лениво, когда они впервые используются.
Свойство "<logger>.handlers". Оно определяет список имён классов обработчиков (handlers), разделённых пробелами или запятыми, для загрузки и регистрации в качестве обработчиков указанному логгеру. Каждое имя класса должно соответствовать классу Handler, имеющему конструктор по умолчанию. Обратите внимание, что эти обработчики могут создаваться лениво, когда они впервые используются.
Свойство "<logger>.handlers.ensureCloseOnReset". Это определяет булево значение. Если "<logger>.handlers" не определено или пусто, это свойство игнорируется. В противном случае оно по умолчанию равно true. Когда значение равно true, обработчики, связанные с логгером, гарантированно будут закрыты при вызове reset() и завершении работы. Это можно отключить, явно задав "<logger>.handlers.ensureCloseOnReset=false" в конфигурации. Обратите внимание, что отключение этого свойства влечёт риск утечки ресурсов, поскольку логгер может быть собран сборщиком мусора до вызова reset(), тем самым не позволяя его обработчикам закрыться в процессе reset(). В этом случае ответственность за закрытие обработчиков ложится на приложение до того, как логгер будет удалён сборщиком мусора.
Свойство "<logger>.useParentHandlers". Это определяет булево значение. По умолчанию каждый логгер обращается к своему родителю помимо обработки собственного сообщения регистрации. Это часто приводит к тому, что сообщения обрабатываются и корневым логгером. При установке этого свойства в значение false, обработчик (Handler) должен быть настроен для этого логгера, иначе сообщения регистрации не будут доставлены.
Свойство "config". Это свойство предназначено для выполнения произвольного кода конфигурации. Свойство определяет список имён классов, разделённых пробелами или запятыми. Для каждого имени класса будет создан новый экземпляр. Конструктор по умолчанию каждого класса может выполнить произвольный код для обновления конфигурации регистрации, такой как установка уровней логгеров, добавление обработчиков, добавление фильтров и т. д.

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

Логгеры организованы в иерархию имён на основе их имён, разделённых точками. Таким образом, "a.b.c" является потомком "a.b", но "a.b1" и "a.b2" являются сверстниками.

Все свойства, имена которых заканчиваются на ".level", предполагаются для определения уровней логгеров для логгеров. Таким образом, "foo.level" определяет уровень логгера с именем "foo" и (рекурсивно) для любого из его потомков в иерархии имён. Уровни логов применяются в порядке их определения в файле свойств. Таким образом, настройки уровня для дочерних узлов в дереве должны следовать за настройками их родителей. Свойство с именем ".level" может быть использовано для установки уровня для корня дерева.

Все методы объекта LogManager являются многопоточно безопасными.

Since:: 1.4

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final String`	`LOGGING_MXBEAN_NAME`	Строковое представление `ObjectName` для интерфейса управления системой регистрации.

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

LogManager()

Модификатор	Конструктор	Описание
`protected`	Защищённый конструктор.

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

Модификатор и тип	Метод	Описание
`LogManager`	`addConfigurationListener(Runnable listener)`	Добавляет слушателя конфигурации, который вызывается каждый раз при чтении конфигурации регистрации.
`boolean`	`addLogger(Logger logger)`	Добавляет именованный логгер.
`void`	`checkAccess()`	Устаревший, для удаления: Этот элемент API может быть удалён в будущей версии. Этот метод полезен только в сочетании с менеджером безопасности, который устарел и подлежит удалению в будущей версии.
`Logger`	`getLogger(String name)`	Метод поиска именованного логгера.
`Enumeration<String>`	`getLoggerNames()`	Получает перечисление известных имён логгеров.
`static LoggingMXBean`	`getLoggingMXBean()`	Устаревший. `java.util.logging.LoggingMXBean` устарел и заменён на `java.lang.management.PlatformLoggingMXBean`.
`static LogManager`	`getLogManager()`	Возвращает глобальный объект LogManager.
`String`	`getProperty(String name)`	Получает значение свойства регистрации.
`void`	`readConfiguration()`	Читает и инициализирует конфигурацию регистрации.
`void`	`readConfiguration(InputStream ins)`	Читает и инициализирует конфигурацию регистрации из заданного потока ввода.
`void`	`removeConfigurationListener(Runnable listener)`	Удаляет ранее зарегистрированного слушателя конфигурации.
`void`	`reset()`	Сбрасывает конфигурацию регистрации.
`void`	`updateConfiguration(InputStream ins, Function<String,BiFunction<String,String,String>> mapper)`	Обновляет конфигурацию регистрации.
`void`	`updateConfiguration(Function<String,BiFunction<String,String,String>> mapper)`	Обновляет конфигурацию регистрации.

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

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

Подробное описание полей

LOGGING_MXBEAN_NAME

public static final String LOGGING_MXBEAN_NAME

Строковое представление ObjectName для интерфейса управления системой ведения журналов.

С момента:

1.5

См. также:

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

LogManager

protected LogManager()

Защищённый конструктор. Он защищён, чтобы приложения-контейнеры (например, контейнеры J2EE) могли наследоваться от объекта. Он не является общедоступным, так как предполагается, что существует только один объект LogManager, значение которого извлекается вызовом LogManager.getLogManager.

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

getLogManager

public static LogManager getLogManager()

Возвращает глобальный объект LogManager.

Возвращает:: глобальный объект LogManager

addLogger

public boolean addLogger(Logger logger)

Добавляет зарегистрированный логгер. Это ничего не делает и возвращает false, если логгер с таким же именем уже зарегистрирован.

Методы фабрики Logger вызывают этот метод для регистрации каждого вновь созданного Logger.

Приложение должно хранить свою ссылку на объект Logger, чтобы избежать его сборки мусора. LogManager может хранить только слабую ссылку.

Параметры:: logger - новый логгер.
Возвращает:: true, если аргумент логгер был успешно зарегистрирован, false, если логгер с таким именем уже существует.
Исключения:: NullPointerException - если имя логгера null.

getLogger

public Logger getLogger(String name)

Метод поиска имени логгера.

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

Параметры:: name - имя логгера
Возвращает:: соответствующий логгер или null, если не найден

getLoggerNames

public Enumeration<String> getLoggerNames()

Получение перечисления известных имён логгеров.

Примечание: логгеры могут добавляться динамически по мере загрузки новых классов. Этот метод сообщает только о логгерах, которые в настоящее время зарегистрированы. Также важно отметить, что этот метод возвращает только имя логгера, а не сильную ссылку на сам логгер. Возвращаемая строка ничего не делает для предотвращения сборки мусора логгера. В частности, если возвращённое имя передаётся в LogManager.getLogger(), то вызывающий метод должен проверить возвращаемое значение из LogManager.getLogger() на null, чтобы должным образом обработать случай, когда логгер был собран мусором в то время, когда его имя было возвращено этим методом.

Возвращает:: перечисление строк имён логгеров

readConfiguration

public void readConfiguration() throws IOException, SecurityException

Читает и инициализирует конфигурацию ведения журналов.

Если системная переменная "java.util.logging.config.class" установлена, то значение переменной обрабатывается как имя класса. Данный класс будет загружен, объект будет создан, и конструктор этого объекта отвечает за чтение начальной конфигурации. (Этот объект может использовать другие системные переменные для управления своей конфигурацией.) Альтернативный класс конфигурации может использовать readConfiguration(InputStream) для определения свойств в LogManager.

Если системная переменная "java.util.logging.config.class" не установлена, то этот метод будет читать начальную конфигурацию из файла свойств и вызывает метод readConfiguration(InputStream) для инициализации конфигурации. Системная переменная "java.util.logging.config.file" может использоваться для указания файла свойств, который будет прочитан в качестве начальной конфигурации; если она не установлена, то используется конфигурация по умолчанию LogManager. Конфигурация по умолчанию обычно загружается из файла свойств "conf/logging.properties" в каталоге установки Java.

Любой зарегистрированный слушатель конфигурации будет вызван после чтения свойств.

Примечание API:: Этот readConfiguration метод должен использоваться только для инициализации конфигурации во время инициализации LogManager или при использовании переменной "java.util.logging.config.class". Когда этот метод вызывается после создания логгеров, и системная переменная "java.util.logging.config.class" не установлена, все существующие логгеры будут сброшены. Затем любые существующие логгеры, имеющие свойство уровня, указанное в новом потоке конфигурации, будут установлены на указанный уровень ведения журнала.
Для правильного обновления конфигурации ведения журнала используйте методы updateConfiguration(java.util.function.Function) или updateConfiguration(java.io.InputStream, java.util.function.Function).
Исключения:: SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет разрешения LoggingPermission("control").; IOException - если возникли проблемы с чтением конфигурации.

reset

public void reset() throws SecurityException

Сброс конфигурации ведения журнала.

Для всех именованных логгеров операция сброса удаляет и закрывает все обработчики и (кроме корневого логгера) устанавливает уровень на null. Уровень корневого логгера устанавливается на Level.INFO.

Примечание API:: Вызов этого метода также очищает свойства LogManager properties. Для правильного обновления конфигурации можно использовать метод updateConfiguration(Function) или updateConfiguration(InputStream, Function).
Исключения:: SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет разрешения LoggingPermission("control").

readConfiguration

public void readConfiguration(InputStream ins) throws IOException, SecurityException

Читает и инициализирует конфигурацию ведения журнала из данного потока ввода.

Любой зарегистрированный слушатель конфигурации будет вызван после чтения свойств.

Примечание API:: Этот readConfiguration метод должен использоваться только для инициализации конфигурации во время инициализации LogManager или при использовании переменной "java.util.logging.config.class". Когда этот метод вызывается после создания логгеров, все существующие логгеры будут сброшены. Затем любые существующие логгеры, имеющие свойство уровня, указанное в данном потоке ввода, будут установлены на указанный уровень ведения журнала.
Для правильного обновления конфигурации ведения журнала используйте методы updateConfiguration(java.util.function.Function) или updateConfiguration(java.io.InputStream, java.util.function.Function).
Параметры:: ins - поток для чтения свойств
Исключения:: SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет разрешения LoggingPermission("control").; IOException - если возникли проблемы с чтением из потока или данный поток не находится в формате файла properties.

updateConfiguration

public void updateConfiguration(Function<String,BiFunction<String,String,String>> mapper) throws IOException

Обновляет конфигурацию логирования.

Если системная переменная "java.util.logging.config.file" установлена, то значение переменной указывает на файл свойств, который будет прочитан как новая конфигурация. В противном случае используется конфигурация по умолчанию LogManager.
Конфигурация по умолчанию обычно загружается из файла свойств "conf/logging.properties" в каталоге установки Java.

Этот метод считывает новую конфигурацию и вызывает метод updateConfiguration(ins, mapper) для обновления конфигурации.

API Note:

Этот метод обновляет конфигурацию логирования, считывая файл свойств, и игнорирует системную переменную "java.util.logging.config.class". Переменная "java.util.logging.config.class" используется только методом readConfiguration() для загрузки пользовательского класса конфигурации в качестве начальной конфигурации.

Parameters:

mapper - функциональный интерфейс, который принимает ключ конфигурации k и возвращает функцию f(o,n), значение которой будет применено к результирующей конфигурации. Функция f может вернуть null для указания того, что свойство k не будет добавлено в результирующую конфигурацию.
Если mapper равно null, то предполагается (k) -> ((o, n) -> n).
Для каждого k, отображаемая функция f будет вызвана со значением, связанным с k в старой конфигурации (т.е. o), и значением, связанным с k в новой конфигурации (т.е. n).
Значение null для o или n указывает на то, что для k не было значения в соответствующей конфигурации.

Throws:

SecurityException - если существует менеджер безопасности, и вызывающий его не имеет LoggingPermission("control"), или не имеет необходимых разрешений для настройки конфигурации (например, для открытия файла, указанного для FileHandlers).

NullPointerException - если mapper возвращает функцию null при вызове.

IOException - если возникли проблемы при чтении файла конфигурации логирования.

Since:

See Also:

updateConfiguration(java.io.InputStream, java.util.function.Function)

updateConfiguration

public void updateConfiguration(InputStream ins, Function<String,BiFunction<String,String,String>> mapper) throws IOException

Обновляет конфигурацию логирования.

Для каждого ключа конфигурации в существующей конфигурации и конфигурации, заданной входным потоком, заданная функция mapper вызывается для отображения ключа конфигурации в функцию f(o,n), которая принимает старое и новое значения и возвращает результирующее значение, которое будет применено в результирующей конфигурации, как указано в таблице ниже.

Пусть k — ключ конфигурации в старой или новой конфигурации, o — старое значение (т.е. значение, связанное с k в старой конфигурации), n — новое значение (т.е. значение, связанное с k в новой конфигурации), и f — функция, возвращаемая mapper.apply(k): тогда v = f(o,n) — результирующее значение. Если v не null, то свойство k со значением v будет добавлено в результирующую конфигурацию. В противном случае оно будет опущено.
Значение null может быть передано функции f для указания того, что соответствующая конфигурация не имеет ключа конфигурации k. Функция f может вернуть null для указания того, что свойству k не будет соответствовать значение в результирующей конфигурации.

Если mapper равно null, то v будет установлено в n.

Свойства LogManager обновляются с результирующим значением в результирующей конфигурации.

Зарегистрированные слушатели конфигурации будут вызваны после успешного обновления конфигурации.

Обновление свойств конфигурации
Свойство	Поведение результата
`<logger>.level`	Если результирующая конфигурация определяет уровень для логгера и если результирующий уровень отличается от уровня, указанного в старой конфигурации, или не указан в старой конфигурации, то если логгер существует или если существуют дочерние элементы для этого логгера, уровень для этого логгера будет обновлен, и изменение будет распространено на все существующие дочерние элементы логгера. Это может привести к созданию логгера, если это необходимо. Если старая конфигурация определила уровень для логгера, а результирующая конфигурация нет, то это изменение не будет распространено на существующие логгеры, если таковые имеются. Для полного замещения конфигурации вызывающий должен, следовательно, вызвать `reset` для очистки текущей конфигурации перед вызовом `updateConfiguration`.
`<logger>.useParentHandlers`	Если либо результирующее, либо старое значение для свойства useParentHandlers не равно null, то если логгер существует или если существуют дочерние элементы для этого логгера, этот логгер будет обновлен до результирующего значения. Значение свойства useParentHandlers является значением, указанным в конфигурации; если оно не указано, значение по умолчанию равно true.
`<logger>.handlers`	Если результирующая конфигурация определяет список обработчиков для логгера, и если результирующий список отличается от списка, указанного в старой конфигурации для этого логгера (который может быть пустым), то если логгер существует или существуют его дочерние элементы, обработчики, связанные с этим логгером, будут закрыты и удалены, и новые обработчики будут созданы в соответствии с результирующей конфигурацией и добавлены к этому логгеру, создавая этот логгер при необходимости. Если старая конфигурация определила некоторые обработчики для логгера, а результирующая конфигурация нет, если этот логгер существует, его обработчики будут удалены и закрыты. Изменение списка обработчиков в существующем логгере приведет к удалению и закрытию всех его предыдущих обработчиков, независимо от того, были ли они созданы из конфигурации или программно. Старые обработчики будут заменены новыми, если таковые имеются.
`<handler-name>.*`	Свойства, настроенные/измененные в классах обработчиков, будут влиять только на вновь созданные обработчики. Если узел настроен с тем же списком обработчиков в старой и результирующей конфигурации, эти обработчики останутся неизменными.
`config` и любые другие свойства	Результирующее значение для этих свойств будет храниться в свойствах LogManager, но `updateConfiguration` не будет анализировать или обрабатывать их значения.

Примеры функций-отображений:

Замена всех свойств логирования новой конфигурацией:

(k) -> ((o, n) -> n):

это эквивалентно передаче null-параметра mapper.
Объединение новой конфигурации и старой конфигурации и использование нового значения, если k существует в новой конфигурации:

(k) -> ((o, n) -> n == null ? o : n):

как будто объединяются две коллекции следующим образом: result.putAll(oldc); result.putAll(newc).
Объединение новой конфигурации и старой конфигурации и использование старого значения, если k существует в старой конфигурации:

(k) -> ((o, n) -> o == null ? n : o):

как будто объединяются две коллекции следующим образом: result.putAll(newc); result.putAll(oldc).
Замена всех свойств новой конфигурацией, кроме свойства обработчика для настройки обработчика логгера, который не является корневым логгером:
```
(k) -> k.endsWith(".handlers")
          ? ((o, n) -> (o == null ? n : o))
          : ((o, n) -> n)
```

Для полной повторной инициализации конфигурации приложение может сначала вызвать reset для полного удаления старой конфигурации, за которым следует updateConfiguration для инициализации новой конфигурации.

Parameters:: ins - поток для чтения свойств; mapper - функциональный интерфейс, который принимает ключ конфигурации k и возвращает функцию f(o,n), значение которой будет применено к результирующей конфигурации. Функция f может вернуть null для указания того, что свойство k не будет добавлено в результирующую конфигурацию.
Если mapper равно null, то предполагается (k) -> ((o, n) -> n).
Значение null для o или n указывает на то, что для k не было значения в соответствующей конфигурации.
Throws:: SecurityException - если существует менеджер безопасности, и вызывающий его не имеет LoggingPermission("control"), или не имеет необходимых разрешений для настройки конфигурации (например, для открытия файлов, указанных для FileHandlers).; NullPointerException - если ins равно null или если mapper возвращает null-функцию при вызове.; IOException - если возникли проблемы при чтении из потока, или заданный поток не имеет формата файла свойств.
Since:: 9

getProperty

public String getProperty(String name)

Получить значение свойства логирования. Метод возвращает null, если свойство не найдено.

Parameters:: name - имя свойства
Returns:: значение свойства

checkAccess

@Deprecated(since="17", forRemoval=true) public void checkAccess() throws SecurityException

Устаревшее, подлежит удалению: Этот элемент API может быть удален в будущей версии.

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

Проверяет, что текущий контекст надежно настроен для изменения конфигурации ведения журнала. Это требует LoggingPermission("control").

Если проверка не пройдена, выбрасывается SecurityException, иначе выполняется нормальный возврат.

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

getLoggingMXBean

@Deprecated(since="9") public static LoggingMXBean getLoggingMXBean()

Устаревшее.

java.util.logging.LoggingMXBean устарело и заменено на java.lang.management.PlatformLoggingMXBean. Используйте ManagementFactory.getPlatformMXBean(PlatformLoggingMXBean.class) вместо него.

Возвращает LoggingMXBean для управления логгерами.

Возвращает:

объект LoggingMXBean.

С тех пор:

1.5

См. также:

PlatformLoggingMXBean

addConfigurationListener

public LogManager addConfigurationListener(Runnable listener)

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

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

Рекомендуется, чтобы слушатели не выбрасывали ошибки или исключения. Если слушатель завершается с необработанной ошибкой или исключением, первое исключение будет передано вызывающему объекту readConfiguration() (или readConfiguration(java.io.InputStream)) после вызова всех слушателей.

Примечание реализации:: Если более одного слушателя завершается с необработанной ошибкой или исключением, реализация может записывать дополнительные ошибки или исключения как вспомогательные исключения.
Параметры:: listener - слушатель конфигурации, который будет вызван после изменения конфигурации.
Возвращает:: Этот LogManager.
Возбуждает:: SecurityException - если менеджер безопасности существует и у вызывающего объекта нет разрешения LoggingPermission("control").; NullPointerException - если слушатель равен null.
С тех пор:: 9

removeConfigurationListener

public void removeConfigurationListener(Runnable listener)

Удаляет ранее зарегистрированного слушателя конфигурации. Возвращает без действия, если слушатель не найден.

Параметры:: listener - слушатель конфигурации для удаления.
Возбуждает:: NullPointerException - если слушатель равен null.; SecurityException - если менеджер безопасности существует и у вызывающего объекта нет разрешения LoggingPermission("control").
С тех пор:: 9

© 1993, 2021, 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/17/docs/api/java.logging/java/util/logging/LogManager.html