モジュール java.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」などを基本ファイル名に追加することで、古いファイルの名前が付けられます。

デフォルトで、バッファリングは入出力ライブラリで使用可能ですが、各ログ・レコードは完了時にフラッシュされます。

デフォルトで、XMLFormatterクラスはフォーマット処理に使用されます。

構成: デフォルトで各FileHandlerは次のLogManager構成プロパティを使用して初期化されます。ここで<handler-name>はハンドラの完全修飾クラス名を示します。 プロパティが未定義である場合(または無効な値を持つ場合)、指定されたデフォルト値が使用されます。

  • <handler-name>.levelはHandlerのデフォルト・レベルを指定します(デフォルトはLevel.ALL)。
  • <handler-name>.filterは使用するFilterクラスの名前を指定します(デフォルトはFilterなし)。
  • <handler-name>.formatterは使用するFormatterクラスの名前を指定します(デフォルトはjava.util.logging.XMLFormatter)。
  • <handler-name>.encodingは使用する文字セット・エンコーディングの名前を指定します(デフォルトは、デフォルト・プラットフォームのエンコーディング)。
  • <handler-name>.limitは任意の1ファイルに書き込むおおよその最大量(バイト)を指定します。 これがゼロの場合は無制限となる。 (デフォルトは無制限)
  • <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"フィールドが指定されず、ファイル・カウントが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」フィールドが指定されない場合、ファイル名の末尾のドットのあとに追加されます。 これは自動的に追加される生成番号のあとになります。

このため、3つのプロセスのすべてがfred%u.%g.txtにログを記録しようとする場合、プロセスのローテーションの順番に従って、最初のファイルとしてfred0.0.txt、fred1.0.txt、fred2.0.txtを使用することになります。

重複を避けるための一意のIDの使用は、ローカル・ディスクのファイル・システム使用時にのみ、確実な動作が保証されることに注意してください。

導入されたバージョン:
1.4

  • コンストラクタの詳細

    • FileHandler

      public FileHandler() throws IOException, SecurityException
      デフォルトのFileHandlerを構築します。 これは常にLogManagerプロパティ(またはそのデフォルト値)から構成されます。
      例外:
      IOException - ファイルを開くときに入出力の問題が発生した場合。
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control"))を持っていない場合。
      NullPointerException - patternプロパティが空の文字列である場合。

    • FileHandler

      public FileHandler​(String pattern) throws IOException, SecurityException
      指定されたファイル名に書き込むようにFileHandlerを初期化します。

      指定されたパターンの引数がファイル名のパターンとして使用され、ファイルの制限が制限なしに設定され、ファイル・カウントが1に設定されている場合以外は、FileHandlerは、LogManagerプロパティ(またはそのデフォルト値)に基づいて構成されます。

      書き込まれるデータの総量に制限がないので、注意して使用してください。

      パラメータ:
      pattern - 出力ファイルの名前
      例外:
      IOException - ファイルを開くときに入出力の問題が発生した場合。
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
      IllegalArgumentException - patternが空の文字列である場合

    • FileHandler

      public FileHandler​(String pattern, boolean append) throws IOException, SecurityException
      オプションの追加モードで、指定されたファイル名を書き込むFileHandlerを初期化します。

      指定されたパターンの引数がファイル名のパターンとして使用され、ファイルの制限が制限なしに設定され、ファイル・カウントが1に設定され、追加モードの指定されたappend引数に設定されている場合以外は、FileHandlerは、LogManagerプロパティ(またはそのデフォルト値)に基づいて構成されます。

      書き込まれるデータの総量に制限がないので、注意して使用してください。

      パラメータ:
      pattern - 出力ファイルの名前
      append - 追加モードを指定する
      例外:
      IOException - ファイルを開くときに入出力の問題が発生した場合。
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
      IllegalArgumentException - patternが空の文字列である場合

    • FileHandler

      public FileHandler​(String pattern, int limit, int count) throws IOException, SecurityException
      一連のファイルに書き込むようにFileHandlerを初期化します。 1つのファイルに指定されたおよその制限量まで書き込まれると、別のファイルが開かれます。 出力先は、count個の一連のファイルの間で循環します。

      指定されたパターンの引数がファイル名のパターンとして使用され、ファイルの制限がlimit引数に設定され、ファイル・カウントが指定されたcount引数に設定されている場合以外は、FileHandlerは、LogManagerプロパティ(またはそのデフォルト値)に基づいて構成されます。

      カウントは少なくとも1である必要があります。

      パラメータ:
      pattern - 出力ファイルの名前付けのパターン
      limit - 任意の1つのファイルに書き込む最大バイト数
      count - 使用するファイル数
      例外:
      IOException - ファイルを開くときに入出力の問題が発生した場合。
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
      IllegalArgumentException - limit < 0またはcount < 1の場合。
      IllegalArgumentException - patternが空の文字列である場合

    • FileHandler

      public FileHandler​(String pattern, int limit, int count, boolean append) throws IOException, SecurityException
      オプションの追加モードで、一連のファイルに書き込むようにFileHandlerを初期化します。 1つのファイルに指定されたおよその制限量まで書き込まれると、別のファイルが開かれます。 出力先は、count個の一連のファイルの間で循環します。

      指定されたパターンの引数がファイル名のパターンとして使用され、ファイルの制限がlimit引数に設定され、ファイル・カウントが指定されたcount引数に設定され、追加モードが指定されたappend引数に設定されている場合以外は、FileHandlerは、LogManagerプロパティ(またはそのデフォルト値)に基づいて構成されます。

      カウントは少なくとも1である必要があります。

      パラメータ:
      pattern - 出力ファイルの名前付けのパターン
      limit - 任意の1つのファイルに書き込む最大バイト数
      count - 使用するファイル数
      append - 追加モードを指定する
      例外:
      IOException - ファイルを開くときに入出力の問題が発生した場合。
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
      IllegalArgumentException - limit < 0またはcount < 1の場合。
      IllegalArgumentException - patternが空の文字列である場合

    • FileHandler

      public FileHandler​(String pattern, long limit, int count, boolean append) throws IOException
      オプションの追加モードで、一連のファイルに書き込むようにFileHandlerを初期化します。 1つのファイルに指定されたおよその制限量まで書き込まれると、別のファイルが開かれます。 出力先は、count個の一連のファイルの間で循環します。

      指定されたパターンの引数がファイル名のパターンとして使用され、ファイルの制限がlimit引数に設定され、ファイル・カウントが指定されたcount引数に設定され、追加モードが指定されたappend引数に設定されている場合以外は、FileHandlerは、LogManagerプロパティ(またはそのデフォルト値)に基づいて構成されます。

      カウントは少なくとも1である必要があります。

      パラメータ:
      pattern - 出力ファイルの名前付けのパターン
      limit - 任意の1つのファイルに書き込む最大バイト数
      count - 使用するファイル数
      append - 追加モードを指定する
      例外:
      IOException - ファイルを開くときに入出力の問題が発生した場合。
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。
      IllegalArgumentException - limit < 0またはcount < 1の場合。
      IllegalArgumentException - patternが空の文字列である場合
      導入されたバージョン:
      9

  • メソッドの詳細

    • publish

      public void publish​(LogRecord record)
      LogRecordをフォーマットして発行します。
      オーバーライド:
      publish、クラス: StreamHandler
      パラメータ:
      record - ログ・イベントの説明。 nullレコードは何の通知もなく無視され、発行されない

    • close

      public void close() throws SecurityException
      すべてのファイルを閉じます。
      オーバーライド:
      close、クラス: StreamHandler
      例外:
      SecurityException - セキュリティ・マネージャが存在する場合で、呼出し元がLoggingPermission("control")を持っていない場合。