java.util.logging

接口
类

java.util.logging
类 FileHandler

java.lang.Object
  继承者 java.util.logging.Handler
      继承者 java.util.logging.StreamHandler
          继承者 java.util.logging.FileHandler

public class FileHandler
     

      extends 
      StreamHandler

简单的文件日志记录 Handler。

FileHandler 可以写入指定的文件，也可以写入文件轮换集。

对于文件轮换集而言，到达每个文件的给定大小限制后，就关闭该文件，将其轮换出去，并打开新的文件。通过在基本文件名中添加 "0"、"1"、"2" 等来依次命名旧文件。

默认情况下，IO 库中启用了缓冲，但当缓冲完成时，每个日志记录都要被刷新。

默认情况下，XMLFormatter 类用于格式化。

配置: 默认情况下，每个 FileHandler 都是使用以下 LogManager 配置属性执行初始化的。如果没有定义属性（或者属性具有非法值），则使用指定的默认值。

  • java.util.logging.FileHandler.level 为 Handler 指定默认的级别（默认为 Level.ALL）。
  • java.util.logging.FileHandler.filter 指定要使用的 Filter 类的名称（默认为无 Filter）。
  • java.util.logging.FileHandler.formatter 指定要使用的 Formatter 类的名称（默认为 java.util.logging.XMLFormatter）。
  • java.util.logging.FileHandler.encoding 指定要使用的字符集编码的名称（默认使用默认的平台编码）。
  • java.util.logging.FileHandler.limit 指定要写入到任意文件的近似最大量（以字节为单位）。如果该数为 0，则没有限制（默认为无限制）。
  • java.util.logging.FileHandler.count 指定有多少输出文件参与循环（默认为 1）。
  • java.util.logging.FileHandler.pattern 为生成的输出文件名称指定一个模式。有关细节请参见以下内容（默认为 "%h/java%u.log"）。
  • java.util.logging.FileHandler.append 指定是否应该将 FileHandler 追加到任何现有文件上（默认为 false）。

模式由包括以下特殊组件的字符串组成，则运行时要替换这些组件：

  • "/" 本地路径名分隔符
  • "%t" 系统临时目录
  • "%h" "user.home" 系统属性的值
  • "%g" 区分循环日志的生成号
  • "%u" 解决冲突的唯一号码
  • "%%" 转换为单个百分数符号"%"
如果未指定 "%g" 字段，并且文件计数大于 1，那么生成号将被添加到所生成文件名末尾的小数点后面。

例如，文件计数为 2 的 "%t/java%g.log" 模式通常导致在 Solaris 系统中将日志文件写入 /var/tmp/java0.log 和 /var/tmp/java1.log，而在 Windows 95 中，则将其写入 C:\TEMP\java0.log 和 C:\TEMP\java1.log。

按照 0、1、2 等的序列安排生成号。

通常，将唯一字段 "%u" 设置为 0。但是如果 FileHandler 试图打开文件名并查找当前被另一个进程使用的文件，则增加唯一的字段号并再次重试。重复此操作直到 FileHandler 找到当前没有被使用的文件名。如果有冲突并且没有指定 "%u" 字段，则将该字段添加到文件名末尾的小数点后（它将位于所有自动添加的生成号后面）。

因此，如果三个进程都试图将日志记录到 fred%u.%g.txt，那么它们可能将 fred0.0.txt、fred1.0.txt、fred2.0.txt 作为其循环序列中的首个文件而结束。

注意，使用本地磁盘文件系统时，使用唯一的 id 以避免冲突是系统可靠运行的唯一保证。

从以下版本开始：
1.4

构造方法摘要
FileHandler()
          构造一个默认的 FileHandler。
FileHandler(String pattern)
          初始化要写入给定文件名的 FileHandler 。
FileHandler(String pattern, boolean append)
          初始化要写入给定文件名的 FileHandler（使用可选的 append）。
FileHandler(String pattern, int limit, int count)
          初始化要写入文件集的 FileHandler。
FileHandler(String pattern, int limit, int count, boolean append)
          初始化要写入文件集的 FileHandler（使用可选的 append）。
 
方法摘要
 void close()
          关闭所有文件。
 void publish(LogRecord record)
          格式化并发布 LogRecord。
 
从类 java.util.logging.StreamHandler 继承的方法
flush, isLoggable, setEncoding, setOutputStream
 
从类 java.util.logging.Handler 继承的方法
getEncoding, getErrorManager, getFilter, getFormatter, getLevel, reportError, setErrorManager, setFilter, setFormatter, setLevel
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

构造方法详细信息

FileHandler

public FileHandler()
            throws IOException,
                   SecurityException
构造一个默认的 FileHandler。可完全从 LogManager 属性（或其默认值）进行配置。

抛出：
IOException - 如果打开文件时存在 IO 问题。
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control"))。
NullPointerException - 如果模式属性是一个空的 String。

FileHandler

public FileHandler(String pattern)
            throws IOException,
                   SecurityException
初始化要写入给定文件名的 FileHandler 。

根据 LogManager 属性（或其默认值）来配置 FileHandler（给定的模式参数用作文件名模式的情况除外），将文件限制设置为无限制，文件计数设置为 1。

由于对写入的数据量没有限制，因此要谨慎使用。

参数：
pattern - 输出文件的名称。
抛出：
IOException - 如果打开文件时存在 IO 问题。
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control")。
IllegalArgumentException - 如果模式是一个空的 string。

FileHandler

public FileHandler(String pattern,
                   boolean append)
            throws IOException,
                   SecurityException
初始化要写入给定文件名的 FileHandler（使用可选的 append）。

根据 LogManager 属性（或其默认值）来配置 FileHandler（给定的模式参数用作文件名模式的情况除外），将文件限制设置为无限制，文件计数设置为 1，将 append 模式设置为给定的 append 参数。

由于对写入的数据量没有限制，因此要谨慎使用。

参数：
pattern - 输出文件的名称。
append - 指定 append 模式。
抛出：
IOException - 如果打开文件时存在 IO 问题。
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control")。
IllegalArgumentException - 如果模式是一个空的 string。

FileHandler

public FileHandler(String pattern,
                   int limit,
                   int count)
            throws IOException,
                   SecurityException
初始化要写入文件集的 FileHandler。已向某个文件写入给定限制的数据量（近似）后，则打开另一个文件。输出将在计数文件集中进行循环。

根据 LogManager 属性（或其默认值）来配置 FileHandler（给定的模式参数用作文件名模式的情况除外），将文件限制设置为限制参数，将文件计数设置为给定的计数参数。

计数必须至少为 1。

参数：
pattern - 为输出文件命名的模式。
limit - 写入到任何一个文件的最大字节数。
count - 要使用的文件数。
抛出：
IOException - 如果打开文件时存在 IO 问题。
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control")。
IllegalArgumentException - 如果 limit < 0，或 count < 1。
IllegalArgumentException - 如果模式是一个空的 string。

FileHandler

public FileHandler(String pattern,
                   int limit,
                   int count,
                   boolean append)
            throws IOException,
                   SecurityException
初始化要写入文件集的 FileHandler（使用可选的 append）。已向某个文件写入给定限制的数据量（近似）后，则打开另一个文件。输出将在计数文件集中进行循环。

根据 LogManager 属性（或其默认值）来配置 FileHandler（给定的模式参数用作文件名模式的情况除外），将文件限制设置为限制参数，将文件计数设置为给定的计数参数，将 append 模式设置为给定的 append 参数。

计数必须至少为 1。

参数：
pattern - 为输出文件命名的模式。
limit - 写入到任何一个文件的最大字节数。
count - 要使用的文件数。
append - 指定 append 模式。
抛出：
IOException - 如果打开文件时存在 IO 问题。
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control")。
IllegalArgumentException - 如果 limit < 0，或 count < 1。
IllegalArgumentException - 如果模式是一个空的 string。
方法详细信息

publish

public void publish(LogRecord record)
格式化并发布 LogRecord。

覆盖：
类 StreamHandler 中的 publish
参数：
record - 日志事件的描述。忽略 null 记录，并且也不发布它。

close

public void close()
           throws SecurityException
关闭所有文件。

覆盖：
类 StreamHandler 中的 close
抛出：
SecurityException - 如果安全管理器存在并且调用者不具有 LoggingPermission("control")。