| |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | ||||||||
java.util.logging
类 Logger
java.lang.Objectjava.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，那么它的有效级别继承自父亲，这可以通过其父亲一直沿树向上递归得到。
可以根据日志配置文件的属性来配置日志级别，在 LogManager 类的描述中对此有所说明。但是也可以通过调用 Logger.setLevel 方法动态地改变它。如果日志级别改变了，则此变化也会影响它的孩子 logger，因为任何级别为 null 的孩子 logger 的有效级别都继承自它的父亲。
对于每次日志记录调用，Logger 最初都依照 logger 的有效日志级别对请求级别（例如 SEVERE 或 FINE）进行简单的检查。如果请求级别低于日志级别，则立即返回日志记录调用。
通过此初始（简单）测试后，Logger 将分配一个 LogRecord 来描述日志记录消息。接着调用 Filter（如果存在）进行更详细的检查，以确定是否应该发布该记录。如果检查通过，则将 LogRecord 发布到其输出 Handler。在默认情况下，logger 也将 LogRecord 沿树递推发布到其父的 Handler。
每个 Logger 都有一个与其关联的 ResourceBundle 名称。该指定的包用于本地化日志消息。如果一个 Logger 没有自己的 ResourceBundle 名称，则它将通过其父亲沿树递归继承到 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 对象是向偶尔使用 Logging 包开发的人员提供的一种便捷方法。 |
| 构造方法摘要 | |
|---|---|
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
public static final Logger global
- “全局”Logger 对象是向偶尔使用 Logging 包开发的人员提供的一种便捷方法。对于经常使用 logging 包（如在产品中）的开发人员应创建和使用其自己的 Logger 对象（带合适的名称），这样才能在适合于每个 Logger 粒度的级别上控制日志记录。
通过调用 Logger.getLogger("global") 来初始化全局 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 将使用从其父亲继承的资源包。
- 返回：
- 本地化包（可能为 null）。
getResourceBundleName
public String getResourceBundleName()
- 检索此 logger 的本地化资源包名称。注意，如果结果为 null，则 Logger 将使用从其父亲继承的资源包名称。
- 返回：
- 本地化包名称（可能为 null）。
setFilter
public void setFilter(Filter newFilter) throws SecurityException
- 设置过滤器以控制此 Logger 的输出。
通过初始的“级别”检查之后，Logger 将调用此 Filter 以检查是否确实应该发布某个日志记录。
- 参数：
newFilter- filter 对象（可能为 null）。- 抛出：
SecurityException- 如果安全管理器存在并且调用方不具有 LoggingPermission("control")。