Класс LogManager

java.lang.Object

java.util.logging.LogManager

public class LogManager extends Object

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

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

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

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

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

Настройка LogManager

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

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

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

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

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

Свойство "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 может быть удалён в будущей версии. Этот метод полезен только в сочетании с Security Manager, который устарел и может быть удалён в будущей версии.
`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)

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

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

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

getLoggerNames

public Enumeration<String> getLoggerNames()

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

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

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

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 - если возникли проблемы при чтении из потока или заданный поток не находится в формате файла свойства.

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

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):

это эквивалентно передаче параметра mapper как null.
Объединить новую конфигурацию и старую конфигурацию и использовать новое значение, если 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 может быть удален в будущей версии.

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

Проверяет, что текущий контекст доверен для изменения конфигурации ведения журнала. Это требует 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

См. также:

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, 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/LogManager.html