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")。