java.util.logging

接口
类

java.util.logging
类 Logger

java.lang.Object
  继承者 java.util.logging.Logger

public class Logger
     

      extends 
      Object

Logger 对象用来记录特定系统或应用程序组件的日志消息。一般使用圆点分隔的层次名称空间来命名 Logger。Logger 名称可以是任意的字符串，但是它们一般应该基于被记录组件的包名或类名，如 java.net 或 javax.swing。此外，可以创建“匿名”的 Logger，其名称未存储在 Logger 名称空间中。

可通过调用某个 getLogger 工厂方法来获得 Logger 对象。这些方法要么创建一个新 Logger，要么返回一个合适的现有 Logger。

日志消息被转发到已注册的 Handler 对象，该对象可以将消息转发到各种目的地，包括控制台、文件、OS 日志等等。

每个 Logger 都跟踪一个“父”Logger，也就是 Logger 名称空间中与其最近的现有祖先。

每个 Logger 都有一个与其相关的 "Level"。这反映了此 logger 所关心的最低 Level。如果将 Logger 的级别设置为 null，那么它的有效级别继承自父 Logger，这可以通过其父 Logger 一直沿树向上递归得到。

可以根据日志配置文件的属性来配置日志级别，在 LogManager 类的描述中对此有所说明。但是也可以通过调用 Logger.setLevel 方法动态地改变它。如果日志级别改变了，则此变化也会影响它的子 logger，因为任何级别为 null 的子 logger 的有效级别都继承自它的父 Logger。

对于每次日志记录调用，Logger 最初都依照 logger 的有效日志级别对请求级别（例如 SEVERE 或 FINE）进行简单的检查。如果请求级别低于日志级别，则日志记录调用将立即返回。

通过此初始（简单）测试后，Logger 将分配一个 LogRecord 来描述日志记录消息。接着调用 Filter（如果存在）进行更详细的检查，以确定是否应该发布该记录。如果检查通过，则将 LogRecord 发布到其输出 Handler。在默认情况下，logger 也将 LogRecord 沿树递推发布到其父 Handler。

每个 Logger 都有一个与其关联的 ResourceBundle 名称。该指定的包用于本地化日志消息。如果一个 Logger 没有自己的 ResourceBundle 名称，则它将通过其父 Logger 沿树递归继承到 ResourceBundle 名称。

大多数 logger 输出方法都带有 "msg" 参数。此 msg 参数可以是一个原始值，也可以是一个本地化的键。在格式化期间，如果 logger 具有（或继承）一个本地化 ResourceBundle，并且 ResourceBundle 包含 msg 字符串的映射关系，那么用本地化值替换 msg 字符串。否则使用原来的 msg 字符串。通常，格式器使用 java.text.MessageFormat 形式的格式来格式化参数，例如，格式字符串 "{0} {1}" 将两个参数格式化为字符串。

将 ResourceBundle 名称映射到 ResourceBundle 时，Logger 首先试图使用该线程的 ContextClassLoader。如果 ContextClassLoader 为 null，则 Logger 将尝试 SystemClassLoader。作为初始实现中的临时过渡功能，如果 Logger 无法从 ContextClassLoader 或 SystemClassLoaderis 中找到一个 ResourceBundle，则 Logger 将会向上搜索类堆栈并连续调用 ClassLoader 来试图找到 ResourceBundle（此调用堆栈搜索是为了允许容器过渡到使用 ContextClassLoader，该功能可能在以后版本中取消）。

格式化（包括本地化）是输出 Handler 的责任，它通常会调用格式器。

注意，格式化不必同步发生。它可以延迟，直到 LogRecord 被实际写入到外部接收器。

日志记录方法划分为 5 个主要类别：

  • 一系列的 "log" 方法，这种方法带有日志级别、消息字符串，以及可选的一些消息字符串参数。

  • 一系列的 "logp" 方法（即 "log precise"），其与 "log" 方法相似，但是带有显式的源类名称和方法名称。

  • 一系列的 "logrb" 方法（即 "log with resource bundle"），其与 "logp" 方法相似，但是带有显式的在本地化日志消息中使用的资源包名称。

  • 还有跟踪方法条目（"entering" 方法）、方法返回（"exiting" 方法）和抛出异常（"throwing" 方法）的便捷方法。

  • 最后，还有一系列在非常简单的情况下（如开发人员只想为给定的日志级别记录一条简单的字符串）使用的便捷方法。这些方法按标准级别名称命名（"severe"、"warning"、"info" 等等)，并带有单个参数，即一个消息字符串。

对于不带显式源名和方法名的方法，日志记录框架将尽可能确定日志记录方法中调用了哪个类和方法。但是应认识到，这样自动推断的信息可能只是近似的，甚至可能是完全错误的。这是因为允许虚拟机在 JIT 编译时可以进行广泛的优化，并且可以完全移除栈帧，导致它无法可靠地找到调用的类和方法。

Logger 上执行的所有方法都是多线程安全的。

子类化信息：注意，对于名称空间中的任意点，LogManager 类都可以提供自身的指定 Logger 实现。因此，Logger 的任何子类（它们与新的 LogManager 类一起实现的情况除外）要注意应该从 LogManager 类获得一个 Logger 实例，并应该将诸如 "isLoggable" 和 "log(LogRecord)" 这样的操作委托给该实例。注意，为了截取所有的日志记录输出，子类只需要重写 log(LogRecord) 方法。所有其他日志记录方法作为在此 log(LogRecord) 方法上的调用而实现。

从以下版本开始：
1.4

字段摘要
static Logger global
          已过时。 此字段的初始化会容易出现死锁。必须由 Logger 类初始化来初始化字段，这可能会导致 LogManager 类初始化的死锁。在这种情况下，两个类初始化都要等待对方完成。从 JDK version 1.6 开始，获取全局 logger 对象的首选方法是通过调用 Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)。
static String GLOBAL_LOGGER_NAME
          GLOBAL_LOGGER_NAME 是全局 logger 的一个名称。
 
构造方法摘要
protected Logger(String name, String resourceBundleName)
          受保护的方法，它用于为一个指定子系统的构造 logger。
 
方法摘要
 void addHandler(Handler handler)
          添加一个日志 Handler 以接收日志记录消息。
 void config(String msg)
          记录一条 CONFIG 消息。
 void entering(String sourceClass, String sourceMethod)
          记录一个方法条目。
 void entering(String sourceClass, String sourceMethod, Object param1)
          记录一个方法条目，带有一个参数。
 void entering(String sourceClass, String sourceMethod, Object[] params)
          记录一个方法条目，带有一组参数。
 void exiting(String sourceClass, String sourceMethod)
          记录一个方法返回。
 void exiting(String sourceClass, String sourceMethod, Object result)
          记录一个方法返回，带有结果对象。
 void fine(String msg)
          记录一条 FINE 消息。
 void finer(String msg)
          记录一条 FINER 消息。
 void finest(String msg)
          记录一条 FINEST 消息。
static Logger getAnonymousLogger()
          创建一个匿名的 Logger。
static Logger getAnonymousLogger(String resourceBundleName)
          创建一个匿名的 Logger。
 Filter getFilter()
          获取此 Logger 的当前过滤器。
 Handler[] getHandlers()
          获得与此 logger 相关的 Handler。
 Level getLevel()
          获取已为此 Logger 指定的日志级别（Level）。
static Logger getLogger(String name)
          为指定子系统查找或创建一个 logger。
static Logger getLogger(String name, String resourceBundleName)
          为指定子系统查找或创建一个 logger。
 String getName()
          获取此 logger 的名称。
 Logger getParent()
          返回此 Logger 的父 logger。
 ResourceBundle getResourceBundle()
          获取此 logger 在当前默认语言环境的本地化资源包。
 String getResourceBundleName()
          获取此 logger 的本地化资源包名称。
 boolean getUseParentHandlers()
          获知此 logger 是否将其输出发送到它的父 logger。
 void info(String msg)
          记录一条 INFO 消息。
 boolean isLoggable(Level level)
          检查给定级别的消息实际上是否由此 logger 记录。
 void log(Level level, String msg)
          记录一条不带参数的消息。
 void log(Level level, String msg, Object param1)
          记录带有一个对象参数的消息。
 void log(Level level, String msg, Object[] params)
          记录带有一组对象参数的消息。
 void log(Level level, String msg, Throwable thrown)
          记录带有相关的可抛出信息的消息。
 void log(LogRecord record)
          记录一条 LogRecord。
 void logp(Level level, String sourceClass, String sourceMethod, String msg)
          记录一条消息，具有指定的源类和方法，不带参数。
 void logp(Level level, String sourceClass, String sourceMethod, String msg, Object param1)
          记录一条消息，具有指定的源类和方法，带有单个日志消息的对象参数。
 void logp(Level level, String sourceClass, String sourceMethod, String msg, Object[] params)
          记录一条消息，具有指定的源类和方法，带有一组对象参数。
 void logp(Level level, String sourceClass, String sourceMethod, String msg, Throwable thrown)
          记录一条消息，具有指定源类和方法，带有相关的可抛出信息。
 void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg)
          记录一条消息，具有指定的源类、方法和资源包名，不带参数。
 void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg, Object param1)
          记录一条消息，具有指定的源类、方法和资源包名，带有单个日志消息的对象参数。
 void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg, Object[] params)
          记录一条消息，具有指定的源类、方法和资源包名，带有一组对象参数。
 void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg, Throwable thrown)
          记录一条消息，具有指定的源类、方法和资源包名，带有相关的可抛出对象。
 void removeHandler(Handler handler)
          移除一个日志 Handler。
 void setFilter(Filter newFilter)
          设置过滤器以控制此 Logger 的输出。
 void setLevel(Level newLevel)
          设置日志级别，指定此 logger 记录的消息级别。
 void setParent(Logger parent)
          设置此 Logger 的父 Logger。
 void setUseParentHandlers(boolean useParentHandlers)
          指定此 logger 是否应该将其输出发送到它的父 Logger。
 void severe(String msg)
          记录一条 SEVERE 消息。
 void throwing(String sourceClass, String sourceMethod, Throwable thrown)
          正抛出异常的记录。
 void warning(String msg)
          记录一条 WARNING 消息。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

GLOBAL_LOGGER_NAME

public static final String GLOBAL_LOGGER_NAME
GLOBAL_LOGGER_NAME 是全局 logger 的一个名称。此名称是向偶尔使用 Logging 包的开发人员提供的一种便捷方法。认真使用 logging 包（例如在产品中）的开发人员应创建并使用其自己的 Logger 对象（带合适的名称），这样才能在适合于每个 Logger 粒度的级别上控制日志记录。

获取全局 logger 的首选方法是通过调用 Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)。

从以下版本开始：
1.6
另请参见：
常量字段值

global

@Deprecated
public static final Logger global
已过时。  此字段的初始化会容易出现死锁。必须由 Logger 类初始化来初始化字段，这可能会导致 LogManager 类初始化的死锁。在这种情况下，两个类初始化都要等待对方完成。从 JDK version 1.6 开始，获取全局 logger 对象的首选方法是通过调用 Logger.getLogger(Logger.GLOBAL_LOGGER_NAME)。
“全局”Logger 对象是向偶尔使用 Logging 包的开发人员提供的一种便捷方法。对于经常使用 logging 包（如在产品中）的开发人员应创建和使用其自己的 Logger 对象（带合适的名称），这样才能在适合于每个 Logger 粒度的级别上控制日志记录。

构造方法详细信息

Logger

protected Logger(String name,
                 String resourceBundleName)
受保护的方法，它用于为一个指定子系统的构造 logger。

该 logger 初始配置的 Level 为 null，并且 useParentHandler 为 true。

参数：
name - logger 的名称。这应该是一个圆点分隔的名称，并且通常应该基于子系统的包名或类名（如 java.net 或 javax.swing）。对于匿名 Logger 来说，名称可以为 null。
resourceBundleName - 用来本地化此 logger 消息的 ResourceBundle 的名称。如果消息不需要本地化，则名称可能为 null。
抛出：
MissingResourceException - 如果 ResourceBundleName 不为 null，并且无法找到相应的资源。
方法详细信息

getLogger

public static Logger getLogger(String name)
为指定子系统查找或创建一个 logger。如果已经创建了具有给定名称的 logger，则返回该 logger。否则创建一个新的 logger。

如果创建了新的 logger，则根据 LogManager 的配置来配置其日志级别，并将日志输出发送到其父处理程序。日志配置注册在 LogManager 全局名称空间内。

参数：
name - logger 的名称。这应该是一个圆点分隔的名称，并且通常应该基于子系统的包名或类名（如 java.net 或 javax.swing）
返回：
适合的 Logger
抛出：
NullPointerException - 如果 name 为 null。

getLogger

public static Logger getLogger(String name,
                               String resourceBundleName)
为指定子系统查找或创建一个 logger。如果已经创建了具有给定名称的 logger，则返回该 logger。否则创建一个新的 logger。

如果创建了新的 logger，则根据 LogManager 来配置其日志级别，并将日志输出发送到其父处理程序。日志配置注册在 LogManager 全局名称空间内。

如果指定的 Logger 已经存在，并且没有本地化资源包，则使用给定的资源包名称。如果给定的 Logger 已经存在，并有不同的资源包名称，则抛出 IllegalArgumentException。

参数：
name - logger 的名称。这应该是一个圆点分隔的名称，并且通常应该基于子系统的包名或类名（如 java.net 或 javax.swing）。
resourceBundleName - 用来本地化此 logger 消息的 ResourceBundle 的名称。如果消息不需要本地化，则名称可以为 null。
返回：
合适的 Logger。
抛出：
MissingResourceException - 如果无法找到指定的 ResourceBundle。
IllegalArgumentException - 如果 Logger 已经存在，并使用了不同的资源包名称。
NullPointerException - 如果 name 为 null。

getAnonymousLogger

public static Logger getAnonymousLogger()
创建一个匿名的 Logger。新创建的 Logger 不是注册在 LogManager 名称空间内。不必对是否更新到 logger 进行访问检查。

此工厂方法主要适合从 applet 来使用。因为得到的 Logger 是匿名的，所以它可通过创建类而保持为私有的。这就不需要进行常规安全检查，从而允许不受信任的 applet 代码可更新 Logger 的控制状态。例如，applet 可以在匿名的 Logger 上执行 setLevel 或 addHandler 操作。

即使新的 logger 是匿名的，也要配置它将根 logger ("") 作为其父 logger。这意味着在默认情况下此 logger 从根 logger 继承有效级别和处理程序。

返回：
新创建的私有 Logger。

getAnonymousLogger

public static Logger getAnonymousLogger(String resourceBundleName)
创建一个匿名的 Logger。新创建的 Logger 不是注册在 LogManager 名称空间内。不会对 logger 是否更新进行访问检查。

此工厂方法主要适合从 applet 使用。因为得到的 Logger 是匿名的，所以它可通过创建类而保持为私有的。这就不需要进行常规安全检查，从而允许不受信任的 applet 代码可更新 Logger 的控制状态。例如，applet 可以在匿名的 Logger 上执行 setLevel 或 addHandler 操作。

即使新的 logger 是匿名的，也要把它配置为将根 logger ("") 作为其父 logger。这意味着在默认情况下此 logger 从根 logger 继承有效级别和处理程序。

参数：
resourceBundleName - 用来本地化此 logger 消息的 ResourceBundle 的名称。如果消息不需要本地化，则名称可以为 null。
返回：
新创建的私有 Logger。
抛出：
MissingResourceException - 如果无法找到指定的 ResourceBundle。

getResourceBundle

public ResourceBundle getResourceBundle()
获取此 logger 在当前默认语言环境的本地化资源包。注意，如果结果为 null，则 Logger 将使用从其父 Logger 继承的资源包。

返回：
本地化包（可能为 null）

getResourceBundleName

public String getResourceBundleName()
获取此 logger 的本地化资源包名称。注意，如果结果为 null，则 Logger 将使用从其父 Logger 继承的资源包名称。

返回：
本地化包名称（可能为 null）

setFilter

public void setFilter(Filter newFilter)
               throws SecurityException
设置过滤器以控制此 Logger 的输出。

通过初始的“级别”检查之后，Logger 将调用此 Filter 以检查是否确实应该发布某个日志记录。

参数：
newFilter - filter 对象（可能为 null）
抛出：
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control")。

getFilter

public Filter getFilter()
获取此 Logger 的当前过滤器。

返回：
过滤器对象（可能为 null）

log

public void log(LogRecord record)
记录一条 LogRecord。

此类中的其他所有日志记录方法都调用此方法以实际执行所有日志记录操作。子类可以重写此单个方法，从而捕获所有的日志活动。

参数：
record - 要发布的 LogRecord

log

public void log(Level level,
                String msg)
记录一条不带参数的消息。

如果当前对于给定的消息级别而言 logger 是启用的，那么将给定的消息转发到所有已注册的输出 Handler 对象。

参数：
level - 某个消息级别标识符，例如 SEVERE
msg - 字符串消息（或消息类别中的键）

log

public void log(Level level,
                String msg,
                Object param1)
记录带有一个对象参数的消息。

如果当前对于给定的消息级别而言 logger 是启用的，则创建相应的 LogRecord 并转发到所有已注册的输出 Handler 对象。

参数：
level - 某个消息级别标识符，例如 SEVERE
msg - 字符串消息（或消息类别中的键）
param1 - 消息的参数

log

public void log(Level level,
                String msg,
                Object[] params)
记录带有一组对象参数的消息。

如果当前对于给定的消息级别而言 logger 是启用的，则创建相应的 LogRecord 并转发到所有已注册的输出 Handler 对象。

参数：
level - 某个消息级别标识符，例如 SEVERE
msg - 字符串消息（或消息类别中的键）
params - 消息的一组参数

log

public void log(Level level,
                String msg,
                Throwable thrown)
记录带有相关的可抛出信息的消息。

如果当前对于给定的消息级别而言 logger 是启用的，那么将给定的参数存储在 LogRecord 中，而 LogRecord 则被转发到所有已注册的输出处理程序。

注意，抛出的参数存储在 LogRecord 抛出属性中，而不是存储在 LogRecord 参数属性中。因此特别通过输出 Formatter 来处理参数，而不是将其视为 LogRecord 消息属性的格式化参数。

参数：
level - 某个消息级别标识符，例如 SEVERE
msg - 字符串消息（或消息类别中的键）
thrown - 与日志消息相关的可抛出对象。

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String msg)
记录一条消息，具有指定的源类和方法，不带参数。

如果当前对于给定的消息级别而言 logger 是启用的，那么将给定的消息转发到所有已注册的输出 Handler 对象。

参数：
level - 某个消息级别标识符，例如 SEVERE
sourceClass - 发出日志记录请求的类名
sourceMethod - 发出日志记录请求的方法名
msg - 字符串消息（或消息类别中的键）

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String msg,
                 Object param1)
记录一条消息，具有指定的源类和方法，带有单个日志消息的对象参数。

如果当前对于给定的消息级别而言 logger 是启用的，则创建相应的 LogRecord 并转发到所有已注册的输出 Handler 对象。

参数：
level - 某个消息级别标识符，例如 SEVERE
sourceClass - 发出日志记录请求的类名
sourceMethod - 发出日志记录请求的方法名
msg - 字符串消息（或消息类别中的键）
param1 - 日志消息的参数。

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String msg,
                 Object[] params)
记录一条消息，具有指定的源类和方法，带有一组对象参数。

如果当前对于给定的消息级别而言 logger 是启用的，则创建相应的 LogRecord 并转发到所有已注册的输出 Handler 对象。

参数：
level - 某个消息级别标识符，例如 SEVERE
sourceClass - 发出日志记录请求的类名
sourceMethod - 发出日志记录请求的方法名
msg - 字符串消息（或消息类别中的键）
params - 消息的一组参数

logp

public void logp(Level level,
                 String sourceClass,
                 String sourceMethod,
                 String msg,
                 Throwable thrown)
记录一条消息，具有指定源类和方法，带有相关的可抛出信息。

如果当前对于给定的消息级别而言 logger 是启用的，那么将给定的参数存储在 LogRecord 中，而 LogRecord 则被转发到所有已注册的输出处理程序。

注意，抛出的参数存储在 LogRecord 抛出属性中，而不是存储在 LogRecord 参数属性中。因此特别通过输出 Formatter 来处理参数，而不是将其视为 LogRecord 消息属性的格式化参数。

参数：
level - 某个消息级别标识符，例如 SEVERE
sourceClass - 发出日志记录请求的类名
sourceMethod - 发出日志记录请求的方法名
msg - 字符串消息（或消息类别中的键）
thrown - 与日志消息相关的可抛出对象。

logrb

public void logrb(Level level,
                  String sourceClass,
                  String sourceMethod,