Класс 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.

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

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

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

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

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

Все методы объекта LogManager многопоточно безопасны.

С момента:
1.4

Поля

Модификатор и тип Поле Описание
static String LOGGING_MXBEAN_NAME

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

Конструкторы

Модификатор Конструктор Описание
protected LogManager()

Защищённый конструктор.

Методы

Модификатор и тип Метод Описание
LogManager addConfigurationListener​(Runnable listener)

Добавляет слушателя конфигурации, который вызывается каждый раз при считывании конфигурации регистрации.
boolean addLogger​(Logger logger)

Добавляет именованный логгер.
void checkAccess()

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

Конструкторы

LogManager

protected LogManager()

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

Методы

getLogManager

public static LogManager getLogManager()

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

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

addLogger

public boolean addLogger(Logger logger)

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

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

Приложению следует сохранить собственную ссылку на объект 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 . Для правильного обновления конфигурации можно использовать метод 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:
Этот метод обновляет конфигурацию ведения журнала, считывая файл свойств, и игнорирует системную переменную «java.util.logging.config.class». Системная переменная «java.util.logging.config.class» используется только методом readConfiguration() для загрузки пользовательского класса конфигурации как начальной конфигурации.
Параметры:
mapper - функциональный интерфейс, который принимает ключ конфигурации k и возвращает функцию f(o,n), значение которой будет применено к результирующей конфигурации. Функция f может вернуть null для указания того, что свойство k не будет добавлено в результирующую конфигурацию.
Если mapper это null, то (k) -> ((o, n) -> n) предполагается.
Для каждого k вызывается сопоставленная функция f со значением, связанным с k в старой конфигурации (т.е. o) и значением, связанным с k в новой конфигурации (т.е. n).
Значение null для o или n указывает, что значение для k в соответствующей конфигурации отсутствовало.
Выбрасывает:
SecurityException - если существует менеджер безопасности, а у вызывающего метода нет разрешения LoggingPermission("control"), или нет разрешений, необходимых для настройки конфигурации (например, открытие файла, указанного для FileHandlers и т. д.).
NullPointerException - если mapper возвращает null функцию при вызове.
IOException - если возникли проблемы с чтением файла конфигурации ведения журнала.
С момента:
9
См. также:
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 для инициализации новой конфигурации.

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

getProperty

public String getProperty(String name)

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

Параметры:
name - имя свойства
Возвращает:
значение свойства

checkAccess

public void checkAccess()
                 throws SecurityException

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

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