第4章 Logging

1. JBoss EAP Maven レポジトリーを使用するよう Maven を設定します (まだそのように設定していない場合)。

   詳細については、「Maven 設定を使用した JBoss EAP Maven リポジトリーの設定」を参照してください。

2. JBoss Logging Tools を使用するようプロジェクトの pom.xml ファイルを設定します。

   詳細については、「JBoss Logging Tools の Maven 設定」を参照してください。

3. ログメッセージ定義を含めるために Java インターフェースをプロジェクトに追加して、メッセージロガーインターフェースを作成します。

   定義するログメッセージの内容がわかるようインターフェースに名前を付けます。ログメッセージインターフェースの要件は次のとおりです。

   • @org.jboss.logging.annotations.MessageLogger アノテーションを付ける必要があります。
   • オプションで、org.jboss.logging.BasicLogger を拡張できます。

   • インターフェースと同じ型のメッセージロガーであるフィールドをインターフェースで定義する必要があります。これは、@org.jboss.logging.Logger の getMessageLogger() を使用して行います。

     例: メッセージロガーの作成

     package com.company.accounts.loggers;
     
     import org.jboss.logging.BasicLogger;
     import org.jboss.logging.Logger;
     import org.jboss.logging.annotations.MessageLogger;
     
     @MessageLogger(projectCode="")
     interface AccountsLogger extends BasicLogger {
        AccountsLogger LOGGER = Logger.getMessageLogger(
              AccountsLogger.class,
              AccountsLogger.class.getPackage().getName() );
     }

4. 各ログメッセージのインターフェースにメソッド定義を追加します。

   ログメッセージの各メソッドにその内容を表す名前を付けます。各メソッドの要件は次のとおりです。

   • メソッドは void を返す必要があります。
   • @org.jboss.logging.annotation.LogMessage アノテーションを付ける必要があります。
   • @org.jboss.logging.annotations.Message アノテーションを付ける必要があります。
   • デフォルトのログレベルは INFO です。

   • @org.jboss.logging.annotations.Message の値属性にはデフォルトのログインメッセージが含まれます。このメッセージは翻訳がない場合に使用されます。

     @LogMessage
     @Message(value = "Customer query failed, Database not available.")
     void customerQueryFailDBClosed();

5. メッセージをログに記録する必要があるコードで呼び出しをインターフェースメソッドに追加してメソッドを呼び出します。

   インターフェースの実装を作成する必要はありません。これは、プロジェクトがコンパイルされる時にアノテーションプロセッサーにより行われます。

   AccountsLogger.LOGGER.customerQueryFailDBClosed();

   カスタムのロガーは BasicLogger からサブクラス化されるため、BasicLogger のロギングメソッドを使用することもできます。国際化されていないメッセージをログに記録するために他のロガーを作成する必要はありません。

   AccountsLogger.LOGGER.error("Invalid query syntax.");

6. プロジェクトで、現地語化できる 1 つ以上の国際化されたロガーがサポートされるようになります。

1. JBoss EAP Maven レポジトリーを使用するよう Maven を設定します (まだそのように設定していない場合)。詳細については、「Maven 設定を使用した JBoss EAP Maven リポジトリーの設定」を参照してください。
2. JBoss Logging Tools を使用するようプロジェクトの pom.xml ファイルを設定します。詳細については、「JBoss Logging Tools の Maven 設定」を参照してください。

3. 例外のインターフェースを作成します。JBoss Logging Tools はインターフェースで国際化されたメッセージを定義します。含まれるメッセージのインターフェースにその内容を表す名前を付けます。インターフェースの要件は以下のとおりです。

   • public として宣言する必要があります。
   • @org.jboss.logging.annotations.MessageBundle アノテーションを付ける必要があります。

   • インターフェースと同じ型のメッセージバンドルであるフィールドをインターフェースが定義する必要があります。

     例: MessageBundle インターフェースの作成

     @MessageBundle(projectCode="")
     public interface GreetingMessageBundle {
        GreetingMessageBundle MESSAGES = Messages.getBundle(GreetingMessageBundle.class);
     }

     注記

     Messages.getBundle(GreetingMessagesBundle.class) を呼び出すのは Messages.getBundle(GreetingMessagesBundle.class, Locale.getDefault()) を呼び出すのと同等です。

     Locale.getDefault() は、Java Virtual Machine のこのインスタンスのデフォルトロケールに対する現在の値を取得します。起動時に、ホストの環境に基づいて Java Virtual Machine によりデフォルトのロケールが設定されます。これは、ロケールが明示的に指定されない場合に、ロケールに関連する多くのメソッドにより使用され、setDefault メソッドを使用して変更できます。

     詳細は、JBoss EAP『設定ガイド』の「 サーバーのデフォルトロケールの設定」を参照してください。

4. 各メッセージのインターフェースにメソッド定義を追加します。メッセージに対する各メソッドにその内容を表す名前を付けます。各メソッドの要件は以下のとおりです。

   • 型 String のオブジェクトを返す必要があります。
   • @org.jboss.logging.annotations.Message アノテーションを付ける必要があります。

   • デフォルトメッセージに @org.jboss.logging.annotations.Message の値属性を設定する必要があります。翻訳がない場合にこのメッセージが使用されます。

     @Message(value = "Hello world.")
     String helloworldString();

5. メッセージを取得する必要があるアプリケーションでインターフェースメソッドを呼び出します。

   System.out.println(helloworldString());

1. JBoss Logging Tools を使用するようプロジェクトの pom.xml ファイルを設定します。詳細については、「JBoss Logging Tools の Maven 設定」を参照してください。

2. 例外のインターフェースを作成します。JBoss Logging Tools はインターフェースで国際化されたメッセージを定義します。各インターフェースに定義する例外を表す名前を付けます。インターフェースの要件は以下のとおりです。

   • public として宣言する必要があります。
   • @MessageBundle アノテーションを付ける必要があります。

   • インターフェースと同じ型のメッセージバンドルであるフィールドをインターフェースが定義する必要があります。

     例: ExceptionBundle インターフェースの作成

     @MessageBundle(projectCode="")
     public interface ExceptionBundle {
        ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
     }

3. 各例外のインターフェースにメソッド定義を追加します。例外に対する各メソッドにその内容を表す名前を付けます。各メソッドの要件は以下のとおりです。

   • Exception オブジェクトまたは Exception のサブタイプを返す必要があります。
   • @org.jboss.logging.annotations.Message アノテーションを付ける必要があります。
   • デフォルトの例外メッセージに @org.jboss.logging.annotations.Message の値属性を設定する必要があります。このメッセージは翻訳がない場合に使用されます。

   • メッセージ文字列の他にパラメーターを必要とするコンストラクターが返される例外にある場合は、@Param アノテーションを使用してこれらのパラメーターをメソッド定義に提供する必要があります。パラメーターは、例外のコンストラクターと同じ型および順番である必要があります。

     @Message(value = "The config file could not be opened.")
     IOException configFileAccessError();
     
     @Message(id = 13230, value = "Date string '%s' was invalid.")
     ParseException dateWasInvalid(String dateString, @Param int errorOffset);

4. 例外を取得する必要があるコードでインターフェースメソッドを呼び出します。メソッドによって例外はスローされませんが、スローできる例外オブジェクトがメソッドによって返されます。

   try {
      propsInFile=new File(configname);
      props.load(new FileInputStream(propsInFile));
   }
   catch(IOException ioex) {
     //in case props file does not exist
      throw ExceptionBundle.EXCEPTIONS.configFileAccessError();
   }

翻訳プロパティーファイルの生成

1. -AgenereatedTranslationFilePath コンパイラー引数を Maven コンパイラープラグイン設定に追加し、新しいファイルが作成されるパスを割り当てます。

   この設定では、Maven プロジェクトの target/generated-translation-files ディレクトリーに新しいファイルが作成されます。

   例: 翻訳ファイルパスの定義

   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>2.3.2</version>
      <configuration>
         <source>1.6</source>
         <target>1.6</target>
         <compilerArgument>
         -AgeneratedTranslationFilesPath=${project.basedir}/target/generated-translation-files
         </compilerArgument>
         <showDeprecation>true</showDeprecation>
      </configuration>
   </plugin>

2. Maven を使用してプロジェクトをビルドします。

   $ mvn compile

   @MessageBundle または @MessageLogger アノテーションが付けられた各インターフェースに対して 1 つのプロパティーファイルが作成されます。

   • 各インターフェースが宣言された Java パッケージに対応するサブディレクトリーに新しいファイルが作成されます。

   • 新しい各ファイルには、以下のパターンで名前が付けられます。ここで、INTERFACE_NAME はファイルを生成するために使用するインターフェースの名前です。

     INTERFACE_NAME.i18n_locale_COUNTRY_VARIANT.properties

国際化されたロガー、例外、またはメッセージの翻訳

1. 以下のコマンドを実行して、テンプレート翻訳プロパティーファイルを作成します。

   $ mvn compile

2. 翻訳したいインターフェースのテンプレートを、テンプレートが作成されたディレクトリーからプロジェクトの src/main/resources ディレクトリーにコピーします。プロパティーファイルは翻訳するインターフェースと同じパッケージに存在する必要があります。
3. GreeterLogger.i18n_fr_FR.properties のように、含まれる言語を示すように、コピーされたテンプレートファイルの名前を変更します。

4. 新しい翻訳プロパティーファイルの内容を編集し、適切な翻訳が含まれるようにします。

   # Level: Logger.Level.INFO
   # Message: Hello message sent.
   logHelloMessageSent=Bonjour message envoyé.

5. テンプレートをコピーし、バンドルの各翻訳のために変更するプロセスを繰り返します。

前提条件

1. 国際化されたログメッセージが含まれるプロジェクトが存在する必要があります。「国際化されたログメッセージの作成」を参照してください。
2. 使用するプロジェクトコードを知っている必要があります。プロジェクトコードを 1 つ使用することも、各インターフェースに異なる複数のコードを定義することも可能です。

ログメッセージへのメッセージ ID とプロジェクトコードの追加

1. カスタムのロガーインターフェースに付けられる @MessageLogger アノテーションの projectCode 属性を使用してプロジェクトコードを指定します。インターフェースに定義されるすべてのメッセージがこのプロジェクトコードを使用します。

   @MessageLogger(projectCode="ACCNTS")
   interface AccountsLogger extends BasicLogger {
   
   }

2. メッセージを定義するメソッドに付けられる @Message アノテーションの id 属性を使用して、各メッセージのメッセージ ID を指定します。

   @LogMessage
   @Message(id=43, value = "Customer query failed, Database not available.")  void customerQueryFailDBClosed();

3. メッセージ ID とプロジェクトコードの両方が関連付けられたログメッセージでは、メッセージ ID とプロジェクトコードがログに記録されたメッセージの前に付けられます。

   10:55:50,638 INFO  [com.company.accounts.ejb] (MSC service thread 1-4) ACCNTS000043: Customer query failed, Database not available.

1. ログメッセージメソッド定義の @LogMessage アノテーションに level 属性を追加します。

2. level 属性を使用してこのメッセージにログレベルを割り当てます。level の有効値は org.jboss.logging.Logger.Level で定義された DEBUG、ERROR、FATAL、INFO、TRACE、および WARN の 6 つの列挙定数です。

   import org.jboss.logging.Logger.Level;
   
   @LogMessage(level=Level.ERROR)
   @Message(value = "Customer query failed, Database not available.")
   void customerQueryFailDBClosed();

パラメーターによるログメッセージのカスタマイズ

1. すべての型のパラメーターをメソッド定義に追加します。型に関係なくパラメーターの String 表現がメッセージに表示されます。

2. ログメッセージにパラメーター参照を追加します。参照は明示的なインデックスまたは通常のインデックスを使用できます。

   • 通常のインデックスを使用するには、各パラメーターを表示したいメッセージ文字列に %s 文字を挿入します。%s の最初のインスタンスにより最初のパラメーターが挿入され、2 番目のインスタンスにより 2 番目のパラメーターが挿入されます。
   • 明示的なインデックスを使用するには、文字 %#$s をメッセージに挿入します。ここで、# は表示したいパラメーターの数を示します。

例外をログメッセージの原因として指定

1. Throwable 型のパラメーターまたはサブクラスをメソッドに追加します。

   @LogMessage
   @Message(id=404, value="Loading configuration failed. Config file:%s")
   void loadConfigFailed(Exception ex, File file);

2. パラメーターに @Cause アノテーションを追加します。

   import org.jboss.logging.annotations.Cause
   
   @LogMessage
   @Message(value = "Loading configuration failed. Config file: %s")
   void loadConfigFailed(@Cause Exception ex, File file);

3. メソッドを呼び出します。コードでメソッドが呼び出されると、正しい型のオブジェクトが渡され、ログメッセージの後に表示されます。

   try
   {
      confFile=new File(filename);
      props.load(new FileInputStream(confFile));
   }
   catch(Exception ex) //in case properties file cannot be read
   {
        ConfigLogger.LOGGER.loadConfigFailed(ex, filename);
   }

前提条件

1. 国際化された例外が含まれるプロジェクトが存在する必要があります。詳細については、「国際化された例外の作成」を参照してください。
2. 使用するプロジェクトコードを知っている必要があります。プロジェクトコードを 1 つ使用することも、各インターフェースに異なる複数のコードを定義することも可能です。

メッセージ ID およびプロジェクトコードの例外メッセージへの追加

1. 例外バンドルインターフェースに付けられる @MessageBundle アノテーションの projectCode 属性を使用して、プロジェクトコードを指定します。インターフェースに定義されるすべてのメッセージがこのプロジェクトコードを使用します。

   @MessageBundle(projectCode="ACCTS")
   interface ExceptionBundle
   {
      ExceptionBundle EXCEPTIONS = Messages.getBundle(ExceptionBundle.class);
   }

2. 例外を定義するメソッドに付けられる @Message アノテーションの id 属性を使用して、各例外に対してメッセージ ID を指定します。

   @Message(id=143, value = "The config file could not be opened.")
   IOException configFileAccessError();

パラメーターによる例外メッセージのカスタマイズ

1. すべての型のパラメーターをメソッド定義に追加します。型に関係なくパラメーターの String 表現がメッセージに表示されます。

2. 例外メッセージにパラメーター参照を追加します。参照は明示的なインデックスまたは通常のインデックスを使用できます。

   • 通常のインデックスを使用するには、各パラメーターを表示したいメッセージ文字列に %s 文字を挿入します。%s の最初のインスタンスにより最初のパラメーターが挿入され、2 番目のインスタンスにより 2 番目のパラメーターが挿入されます。
   • 明示的なインデックスを使用するには、文字 %#$s をメッセージに挿入します。ここで、# は表示したいパラメーターの数を示します。

1. Throwable 型のパラメーターまたはサブクラスをメソッドに追加します。

   @Message(id=328, value = "Error calculating: %s.")
   ArithmeticException calculationError(Throwable cause, String msg);

2. パラメーターに @Cause アノテーションを追加します。

   import org.jboss.logging.annotations.Cause
   
   @Message(id=328, value = "Error calculating: %s.")
   ArithmeticException calculationError(@Cause Throwable cause, String msg);

3. 例外オブジェクトを取得するため、インターフェースメソッドを呼び出します。catch ブロックから新しい例外を発生させ、キャッチした例外を原因として指定するのが最も一般的なユースケースです。

   try
   {
      ...
   }
   catch(Exception ex)
   {
      throw ExceptionBundle.EXCEPTIONS.calculationError(
                                       ex, "calculating payment due per day");
   }

1. JBoss EAP レポジトリーを使用するよう Maven を設定します (まだそのように設定していない場合)。詳細については、「Maven 設定を使用した JBoss EAP Maven リポジトリーの設定」を参照してください。

   pom.xml ファイルの <dependencyManagement> セクションに jboss-eap-javaee7 BOM を含めます。

   <dependencyManagement>
     <dependencies>
       <!-- JBoss distributes a complete set of Java EE APIs including
         a Bill of Materials (BOM). A BOM specifies the versions of a "stack" (or
         a collection) of artifacts. We use this here so that we always get the correct versions of artifacts.
         Here we use the jboss-javaee-7.0 stack (you can
         read this as the JBoss stack of the Java EE APIs). You can actually
         use this stack with any version of JBoss EAP that implements Java EE. -->
       <dependency>
         <groupId>org.jboss.bom</groupId>
          <artifactId>jboss-eap-javaee7</artifactId>
          <version>${version.jboss.bom.eap}</version>
          <type>pom</type>
          <scope>import</scope>
       </dependency>
     <dependencies>
   <dependencyManagement>

2. Maven 依存関係をプロジェクトの pom.xml ファイルに追加します。

   1. JBoss Logging フレームワークにアクセスするために jboss-logging 依存関係を追加します。

   2. JBoss Logging Tools を使用する場合は、jboss-logging-processor 依存関係も追加します。

      これら両方の依存関係は、前の手順で追加された JBoss EAP BOM で利用できます。したがって、各依存関係のスコープ要素は示されているように provided に設定できます。

      <!-- Add the JBoss Logging Tools dependencies -->
      <!-- The jboss-logging API -->
      <dependency>
         <groupId>org.jboss.logging</groupId>
         <artifactId>jboss-logging</artifactId>
         <scope>provided</scope>
      </dependency>
      <!-- Add the jboss-logging-tools processor if you are using JBoss Tools  -->
      <dependency>
         <groupId>org.jboss.logging</groupId>
         <artifactId>jboss-logging-processor</artifactId>
         <scope>provided</scope>
      </dependency>

3. maven-compiler-plugin のバージョンは 3.1 以上であり、1.8 のターゲットソースおよび生成されたソースに対して設定する必要があります。

   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.1</version>
      <configuration>
         <source>1.8</source>
         <target>1.8</target>
      </configuration>
   </plugin>