Module java.logging
Package java.util.logging

Class FileHandler

java.lang.Object
java.util.logging.Handler
java.util.logging.StreamHandler
java.util.logging.FileHandler
public class FileHandler extends StreamHandler
简单文件记录 处理程序。

FileHandler 可以写入指定的文件，也可以写入一组旋转的文件。

对于一组旋转的文件，当每个文件达到给定的大小限制时，它将被关闭，旋转出去，并打开一个新文件。较旧的文件通过在基本文件名中添加“0”、“1”、“2”等来命名。

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

默认情况下，使用 XMLFormatter 类进行格式化。

配置：默认情况下，每个 FileHandler 都是使用以下 LogManager 配置属性进行初始化的，其中 <handler-name> 是处理程序的完全限定类名。如果未定义属性（或具有无效值），则使用指定的默认值。

  • <handler-name>.level 指定 处理程序 的默认级别（默认为 Level.ALL）。
  • <handler-name>.filter 指定要使用的 Filter 类的名称（默认为无 Filter）。
  • <handler-name>.formatter 指定要使用的 Formatter 类的名称（默认为 java.util.logging.XMLFormatter）
  • <handler-name>.encoding 要使用的字符集编码的名称（默认为默认平台编码）。
  • <handler-name>.limit 指定写入任一文件的近似最大量（以字节为单位）。如果为零，则没有限制。（默认为无限制）。
  • <handler-name>.count 指定要循环的输出文件数（默认为 1）。
  • <handler-name>.pattern 指定生成输出文件名的模式。有关详细信息，请参见下文。（默认为 "%h/java%u.log"）。
  • <handler-name>.append 指定 FileHandler 是否应追加到任何现有文件（默认为 false）。
  • <handler-name>.maxLocks 指定 FileHandler 持有的最大并发锁数（默认为 100）。

例如，FileHandler 的属性将是：

  • java.util.logging.FileHandler.level=INFO
  • java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

对于自定义处理程序，例如 com.foo.MyHandler，属性将是：

  • com.foo.MyHandler.level=INFO
  • com.foo.MyHandler.formatter=java.util.logging.SimpleFormatter

模式由一个字符串组成，其中包括以下在运行时将被替换的特殊组件：

  • "/" 本地路径名分隔符
  • "%t" 系统临时目录
  • "%h" “user.home” 系统属性的值
  • "%g" 区分旋转日志的生成号
  • "%u" 用于解决冲突的唯一编号
  • "%%" 转换为单个百分号 "%"
如果未指定 "%g" 字段且文件计数大于一，则在生成的文件名末尾将添加生成号，之后是一个点。

因此，例如，模式为 "%t/java%g.log"，计数为 2，在 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 作为它们旋转序列中的第一个文件。

请注意，使用唯一标识以避免冲突的方法仅在使用本地磁盘文件系统时才能可靠地工作。

自 JDK 版本:
1.4

  • Constructor Details

    • FileHandler

      public FileHandler() throws IOException, SecurityException
      构造默认的 FileHandler。这将完全根据 LogManager 属性（或其默认值）进行配置。
      抛出:
      IOException - 如果打开文件时出现 IO 问题。
      SecurityException - 如果存在安全管理器且调用方没有 LoggingPermission("control"))。
      NullPointerException - 如果模式属性是空字符串。

    • FileHandler

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

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

      可以写入的数据量没有限制，因此请谨慎使用。

      参数:
      pattern - 输出文件的名称
      抛出:
      IOException - 如果打开文件时出现 IO 问题。
      SecurityException - 如果存在安全管理器且调用方没有 LoggingPermission("control")。
      IllegalArgumentException - 如果模式是空字符串

    • FileHandler

      public FileHandler(String pattern, boolean append) throws IOException, SecurityException
      初始化一个 FileHandler 以写入给定的文件名，并可选择追加。

      FileHandler 根据 LogManager 属性（或其默认值）进行配置，除了使用给定的模式参数作为文件名模式，文件限制设置为无限制，文件计数设置为 1，并将追加模式设置为给定的 append 参数。

      可以写入的数据量没有限制，因此请谨慎使用。

      参数:
      pattern - 输出文件的名称
      append - 指定追加模式
      抛出:
      IOException - 如果打开文件时出现 IO 问题。
      SecurityException - 如果存在安全管理器且调用方没有 LoggingPermission("control")。
      IllegalArgumentException - 如果模式是空字符串

    • FileHandler

      public FileHandler(String pattern, int limit, int count) throws IOException, SecurityException
      初始化一个 FileHandler 以写入一组文件。当（大约）向一个文件写入了给定的限制时，将打开另一个文件。输出将循环通过一组计数文件。

      FileHandler 根据 LogManager 属性（或其默认值）进行配置，除了使用给定的模式参数作为文件名模式，文件限制设置为限制参数，文件计数设置为给定的计数参数。

      计数必须至少为 1。

      参数:
      pattern - 用于命名输出文件的模式
      limit - 写入任一文件的最大字节数
      count - 要使用的文件数
      抛出:
      IOException - 如果打开文件时出现 IO 问题。
      SecurityException - 如果存在安全管理器且调用方没有 LoggingPermission("control")。
      IllegalArgumentException - 如果 limit < 0，或 count < 1。
      IllegalArgumentException - 如果模式是空字符串

    • FileHandler

      public FileHandler(String pattern, int limit, int count, boolean append) throws IOException, SecurityException
      初始化一个 FileHandler 以写入一组文件，并可选择追加。当（大约）向一个文件写入了给定的限制时，将打开另一个文件。输出将循环通过一组计数文件。

      FileHandler 根据 LogManager 属性（或其默认值）进行配置，除了使用给定的模式参数作为文件名模式，文件限制设置为限制参数，文件计数设置为给定的计数参数，并将追加模式设置为给定的 append 参数。

      计数必须至少为 1。

      参数:
      pattern - 输出文件命名的模式
      limit - 写入任一文件的最大字节数
      count - 要使用的文件数
      append - 指定追加模式
      抛出:
      IOException - 如果打开文件时出现IO问题。
      SecurityException - 如果存在安全管理器且调用者没有LoggingPermission("control")。
      IllegalArgumentException - 如果limit < 0，或count < 1。
      IllegalArgumentException - 如果pattern是空字符串

    • FileHandler

      public FileHandler(String pattern, long limit, int count, boolean append) throws IOException
      初始化一个FileHandler以写入一组文件，并可选择追加。当大约写入给定限制的字节数到一个文件时，将打开另一个文件。输出将循环遍历一组计数文件。

      FileHandler根据LogManager属性（或其默认值）进行配置，除了给定的模式参数用作文件名模式，文件限制设置为限制参数，文件计数设置为给定的计数参数，并且追加模式设置为给定的append参数。

      计数必须至少为1。

      参数:
      pattern - 输出文件命名的模式
      limit - 写入任一文件的最大字节数
      count - 要使用的文件数
      append - 指定追加模式
      抛出:
      IOException - 如果打开文件时出现IO问题。
      SecurityException - 如果存在安全管理器且调用者没有LoggingPermission("control")。
      IllegalArgumentException - 如果limit < 0，或count < 1。
      IllegalArgumentException - 如果pattern是空字符串
      自 JDK 9 起:
      9

  • Method Details

    • publish

      public void publish(LogRecord record)
      格式化并发布一个LogRecord。
      覆盖:
      publish 在类 StreamHandler中
      参数:
      record - 日志事件的描述。空记录将被静默忽略并不会被发布

    • close

      public void close() throws SecurityException
      关闭所有文件。
      覆盖:
      close 在类 StreamHandler中
      抛出:
      SecurityException - 如果存在安全管理器且调用者没有LoggingPermission("control")。