Класс Logger

public class Logger
extends Object

Объект Logger используется для регистрации сообщений для определённой системы или компонента приложения. Логгеры обычно имеют имя, используя иерархическое имённое пространство, разделённое точками. Имена логгеров могут быть произвольными строками, но они обычно должны основываться на имени пакета или классе логгируемого компонента, например, java.net или javax.swing. Кроме того, можно создавать «анонимные» логгеры, которые не хранятся в пространстве имён логгера.

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

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

Каждый Logger отслеживает «родительский» Logger, который является ближайшим существующим предком в пространстве имён Logger.

Каждый Logger связан с «уровнем» (Level). Это отражает минимальный уровень, который учитывается этим логгером. Если уровень Logger установлен на null, то его эффективный уровень наследуется от родительского логгера, который в свою очередь может получить его рекурсивно от своего родителя и так далее по дереву.

Уровень регистрации можно настроить на основе свойств из файла конфигурации регистрации, как описано в описании класса LogManager. Однако его также можно динамически изменить с помощью вызова метода Logger.setLevel. Если уровень логгера изменится, это изменение может также повлиять на дочерние логгеры, поскольку любой дочерний логгер, у которого null в качестве уровня, унаследует свой эффективный уровень от родителя.

При каждом вызове регистрации Logger сначала выполняет быструю проверку уровня запроса (например, SEVERE или FINE) относительно эффективного уровня регистрации логгера. Если уровень запроса ниже уровня регистрации, вызов регистрации возвращается немедленно.

После прохождения этого начального (быстрого) теста Logger выделит LogRecord для описания сообщения регистрации. Затем он вызовет фильтр (если он присутствует), чтобы выполнить более подробную проверку того, должно ли быть опубликовано сообщение. Если эта проверка пройдена, он опубликует LogRecord в своих выходных обработчиках Handler. По умолчанию логгеры также публикуют свои сообщения обработчикам своих родителей, рекурсивно вверх по дереву.

Каждый Logger может иметь ResourceBundle связанный с ним. ResourceBundle можно указать по имени, используя метод-фабрик getLogger(java.lang.String, java.lang.String), или по значению — с помощью метода setResourceBundle. Этот пакет будет использоваться для локализации сообщений регистрации. Если у Logger нет своего ResourceBundle или имени ресурсного пакета, то он унаследует ResourceBundle или имя ресурсного пакета от родителя, рекурсивно вверх по дереву.

Большинство методов логгирования принимают аргумент «msg». Этот аргумент msg может быть либо сырым значением, либо ключом локализации. Во время форматирования, если у логгера есть (или унаследован) пакет локализации ResourceBundle, и если ResourceBundle имеет отображение для строки msg, тогда строка msg заменяется локализованным значением. В противном случае используется исходная строка msg. Обычно форматировщики используют форматирование в стиле java.text.MessageFormat для форматирования параметров, поэтому, например, строка формата "{0} {1}" отформатирует два параметра как строки.

Набор методов альтернативно принимает «msgSupplier» вместо аргумента «msg». Эти методы принимают функцию Supplier<String>, которая вызывается для построения желаемого сообщения регистрации только тогда, когда сообщение фактически должно быть зарегистрировано на основе эффективного уровня регистрации, тем самым исключая ненужное создание сообщений. Например, если разработчик хочет зарегистрировать состояние здоровья системы для диагностики с помощью версии, принимающей String, код будет выглядеть так:

class DiagnosisMessages {
    static String systemHealthStatus() {
      // collect system health information
      ...
    }
  }
  ...
  logger.log(Level.FINER, DiagnosisMessages.systemHealthStatus());

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

logger.log(Level.FINER, DiagnosisMessages::systemHealthStatus);

При поиске ResourceBundle, логгер сначала проверяет, был ли пакет указан с помощью setResourceBundle, а затем только наличие имени ресурсного пакета, указанного через метод-фабрик getLogger. Если ResourceBundle или имя ресурсного пакета не найдены, то он будет использовать ближайшее ResourceBundle или имя ресурсного пакета, унаследованные от родительского дерева.
Если ResourceBundle был унаследован или указан через метод setResourceBundle, то этот ResourceBundle будет использован. В противном случае, если у логгера есть только имя ресурсного пакета или он его унаследовал, то это имя ресурсного пакета будет сопоставлено с объектом ResourceBundle, используя локаль по умолчанию на момент регистрации.
При сопоставлении имён ресурсных пакетов с объектами ResourceBundle, логгер сначала попытается использовать контекстный класс загрузчик потока context class loader для сопоставления заданного имени ресурсного пакета с ResourceBundle. Если контекстный класс загрузчик потока null, он попытается использовать системный класс загрузчик вместо него. Если ResourceBundle по-прежнему не найден, он будет использовать класс-загрузчик первого вызывающего метода-фабрики getLogger.

Форматирование (включая локализацию) является обязанностью выходного обработчика Handler, который обычно вызовет Formatter.

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

Методы регистрации сгруппированы в пяти основных категориях:

• Существует набор методов «log», которые принимают уровень регистрации, строку сообщения и необязательно некоторые параметры для строки сообщения.

• Существует набор методов «logp» (для «точного логгирования»), которые похожи на методы «log», но также принимают явное имя класса источника и имя метода.

• Существует набор методов «logrb» (для «логгирования с использованием ресурсного пакета»), которые похожи на метод «logp», но также принимают явный объект ресурсного пакета для использования в локализации сообщения регистрации.

• Существуют служебные методы для отслеживания входов в методы («входящие» методы), возвратов из методов («выходящие» методы) и выбрасывания исключений («бросающие» методы).

• Наконец, есть набор служебных методов для использования в простейших случаях, когда разработчик просто хочет зарегистрировать простую строку на заданном уровне регистрации. Эти методы названы по именам стандартных уровней («severe», «warning», «info» и т. д.) и принимают один аргумент — строку сообщения.

Для методов, не принимающих явное имя источника и имя метода, среда выполнения логгирования сделает все возможное, чтобы определить, какой класс и метод вызвали метод логгирования. Однако важно понимать, что эта автоматически определённая информация может быть приблизительной (или даже совершенно неправильной!). Виртуальные машины могут выполнять расширенные оптимизации при JIT-компиляции и могут полностью удалить кадры стека, что делает невозможным надёжное определение вызывающего класса и метода.

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

Информация по наследованию: Обратите внимание, что класс LogManager может предоставлять собственную реализацию именованных логгеров для любой точки в пространстве имен. Поэтому любые подклассы Logger (если они не реализованы в сочетании с новым классом LogManager) должны позаботиться о получении экземпляра Logger из класса LogManager и делегировать операции, такие как «isLoggable» и «log(LogRecord)», этому экземпляру. Обратите внимание, что для перехвата всех сообщений регистрации подклассам достаточно переопределить метод log(LogRecord). Все остальные методы логгирования реализованы как вызовы этому методу log(LogRecord).