JavaTM Platform
Standard Ed. 6

java.util.logging
类 Handler

java.lang.Object
  继承者 java.util.logging.Handler
直接已知子类:
MemoryHandler, StreamHandler

public abstract class Handler
extends Object

Handler 对象从 Logger 中获取日志信息,并将这些信息导出。例如,它可将这些信息写入控制台或文件中,也可以将这些信息发送到网络日志服务中,或将其转发到操作系统日志中。

可通过执行 setLevel(Level.OFF) 来禁用 Handler,并可通过执行适当级别的 setLevel 来重新启用。

Handler 类通常使用 LogManager 属性来设置 HandlerFilterFormatterLevel 的默认值。有关每个具体的 Handler 类,请参阅指定的文档。

从以下版本开始:
1.4

构造方法摘要
protected Handler()
          默认构造方法。
 
方法摘要
abstract  void close()
          关闭 Handler,并释放所有相关的资源。
abstract  void flush()
          刷新所有的缓冲输出。
 String getEncoding()
          返回该 Handler 的字符编码。
 ErrorManager getErrorManager()
          获取该 Handler 的 ErrorManager。
 Filter getFilter()
          获得该 Handler 的当前 Filter
 Formatter getFormatter()
          返回该 HandlerFormatter
 Level getLevel()
          获得用于指定该 Handler 所记录信息的日志级别。
 boolean isLoggable(LogRecord record)
          检查该 Handler 是否实际记录给定的 LogRecord
abstract  void publish(LogRecord record)
          发布 LogRecord
protected  void reportError(String msg, Exception ex, int code)
          用于向该 Handler 的 ErrorManager 报告错误的受保护便利方法。
 void setEncoding(String encoding)
          设置该 Handler 所用的字符编码。
 void setErrorManager(ErrorManager em)
          为该 Handler 定义一个 ErrorManager。
 void setFilter(Filter newFilter)
          设置 Filter,以控制该 Handler 的输出。
 void setFormatter(Formatter newFormatter)
          设置 Formatter
 void setLevel(Level newLevel)
          设置日志级别,指定该 Handler 所记录的信息级别。
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

Handler

protected Handler()
默认构造方法。得到的 Handler 具有 Level.ALL 的日志级别,不具有 FormatterFilter。作为 ErrorManager 安装默认的 ErrorManager 实例。

方法详细信息

publish

public abstract void publish(LogRecord record)
发布 LogRecord

最初向 Logger 对象发出的日志请求,此请求可初始化 LogRecord 并可在此转发这一日志记录。

Handler 负责在必要时进行信息格式化。 格式化应该包括本地化。

参数:
record - 日志事件的描述。忽略 null 记录,并且也不发布它。

flush

public abstract void flush()
刷新所有的缓冲输出。


close

public abstract void close()
                    throws SecurityException
关闭 Handler,并释放所有相关的资源。

Close 方法将执行 flush,然后关闭 Handler。调用 close 方法后,就不应再使用该 Handler。要么默认忽略方法调用,要么抛出运行时异常。

抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")

setFormatter

public void setFormatter(Formatter newFormatter)
                  throws SecurityException
设置 Formatter。将该 Formatter 用于格式化该 HandlerLogRecords

某些 Handlers 不能使用 Formatters,在此情形下将记住而不是使用 Formatter

参数:
newFormatter - Formatter 将使用(不可为空)
抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")

getFormatter

public Formatter getFormatter()
返回该 HandlerFormatter

返回:
Formatter(可以为空)。

setEncoding

public void setEncoding(String encoding)
                 throws SecurityException,
                        UnsupportedEncodingException
设置该 Handler 所用的字符编码。

应在将任何 LogRecords 写入 Handler 之前设置编码。

参数:
encoding - 所支持字符编码的名称。可以为空,以表明应为默认平台编码。
抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")
UnsupportedEncodingException - 如果不支持指定的编码。

getEncoding

public String getEncoding()
返回该 Handler 的字符编码。

返回:
编码名称。可以为空,以表明应使用默认编码。

setFilter

public void setFilter(Filter newFilter)
               throws SecurityException
设置 Filter,以控制该 Handler 的输出。

对于 publish 的每个调用,Handler 将调用该 Filter (如果不为空),以检查是否应发布或放弃 LogRecord

参数:
newFilter - Filter 对象(可以为空)
抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")

getFilter

public Filter getFilter()
获得该 Handler 的当前 Filter

返回:
Filter 对象(可以为空)

setErrorManager

public void setErrorManager(ErrorManager em)
为该 Handler 定义一个 ErrorManager。

如果使用该 Handler 时发生任何错误,将调用 ErrorManager 的 "error" 方法。

参数:
em - 新的 ErrorManager
抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")

getErrorManager

public ErrorManager getErrorManager()
获取该 Handler 的 ErrorManager。

抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")

reportError

protected void reportError(String msg,
                           Exception ex,
                           int code)
用于向该 Handler 的 ErrorManager 报告错误的受保护便利方法。注意,该方法无需进行安全检查即可获取和使用 ErrorManager。因此,可在调用者无特权的环境下使用该方法。

参数:
msg - 描述性字符串(可以为空)
ex - 异常(可以为空)
code - 在 ErrorManager 中定义的错误代码

setLevel

public void setLevel(Level newLevel)
              throws SecurityException
设置日志级别,指定该 Handler 所记录的信息级别。将丢弃低于该值的信息级别。

其目的在于允许开发人员打开大多数日志,但是限制将信息发送到特定 Handlers

参数:
newLevel - 日志级别的新值
抛出:
SecurityException - 如果存在安全管理器,且调用者不具有 LoggingPermission("control")

getLevel

public Level getLevel()
获得用于指定该 Handler 所记录信息的日志级别。将丢弃低于该值的信息级别。

返回:
正在记录的信息级别。

isLoggable

public boolean isLoggable(LogRecord record)
检查该 Handler 是否实际记录给定的 LogRecord

该方法检查 LogRecord 是否具有适当的 Level,以及是否满足任何 Filter。它也可进行其他 Handler 特定的检查,以防处理程序记录 LogRecord。如果 LogRecord 为 Null,将返回 False。

参数:
record - 一个 LogRecord
返回:
如果要记录 LogRecord,则返回 true。

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策