6.2. JBoss Logging Tools

Procedure 6.1. Create an Internationalized Log Message Bundle

1. Create an Message Logger interface

   Add a Java interface to your project to contain the log message definitions. Name the interface descriptively for the log messages that will be defined in it.
   The log message interface has the following requirements:
   • It must be annotated with @org.jboss.logging.MessageLogger.
   • It must extend org.jboss.logging.BasicLogger.
   • The interface must define a field of that is a typed logger that implements this interface. Do this with the getMessageLogger() method of org.jboss.logging.Logger.

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

2. Add method definitions

   Add a method definition to the interface for each log message. Name each method descriptively for the log message that it represents.
   Each method has the following requirements:
   • The method must return void.
   • It must be annotated with the @org.jboss.logging.LogMessage annotation.
   • It must be annotated with the @org.jboss.logging.Message annotation.
   • The value attribute of @org.jboss.logging.Message contains the default log message. This is the message that is used if no translation is available.

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

   The default log level is INFO.

3. Invoke the methods

   Add the calls to the interface methods in your code where the messages must be logged from. It is not necessary to create implementations of the interfaces, the annotation processor does this for you when the project is compiled.

   AccountsLogger.LOGGER.customerQueryFailDBClosed();

   The custom loggers are sub-classed from BasicLogger so the logging methods of BasicLogger (debug(), error() etc) can also be used. It is not necessary to create other loggers to log non-internationalized messages.

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

Procedure 6.2. Create and Use Internationalized Messages

1. Create an interface for the exceptions

   JBoss Logging Tools defines internationalized messages in interfaces. Name each interface descriptively for the messages that will be defined in it.
   The interface has the following requirements:
   • It must be declared as public
   • It must be annotated with @org.jboss.logging.MessageBundle.
   • The interface must define a field that is a message bundle of the same type as the interface.

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

2. Add method definitions

   Add a method definition to the interface for each message. Name each method descriptively for the message that it represents.
   Each method has the following requirements:
   • It must return an object of type String.
   • It must be annotated with the @org.jboss.logging.Message annotation.
   • The value attribute of @org.jboss.logging.Message must be set to the default message. This is the message that is used if no translation is available.

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

3. Invoke methods

   Invoke the interface methods in your application where you need to obtain the message.

   System.console.out.println(helloworldString());

Procedure 6.3. Create and use Internationalized Exceptions

1. Add JBoss Logging Tools configuration

   Add the required project configuration to support JBoss Logging Tools. Refer to Section 6.2.6.1, “JBoss Logging Tools Maven Configuration”

2. Create an interface for the exceptions

   JBoss Logging Tools defines internationalized exceptions in interfaces. Name each interface descriptively for the exceptions that will be defined in it.
   The interface has the following requirements:
   • It must be declared as public.
   • It must be annotated with @org.jboss.logging.MessageBundle.
   • The interface must define a field that is a message bundle of the same type as the interface.

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

3. Add method definitions

   Add a method definition to the interface for each exception. Name each method descriptively for the exception that it represents.
   Each method has the following requirements:
   • It must return an object of type Exception or a sub-type of Exception.
   • It must be annotated with the @org.jboss.logging.Message annotation.
   • The value attribute of @org.jboss.logging.Message must be set to the default exception message. This is the message that is used if no translation is available.
   • If the exception being returned has a constructor that requires parameters in addition to a message string, then those parameters must be supplied in the method definition using the @Param annotation. The parameters must be the same type and order as the constructor.

   @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. Invoke methods

   Invoke the interface methods in your code where you need to obtain one of the exceptions. The methods do not throw the exceptions, they return the exception object which you can then throw.

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

Procedure 6.4. Generate New Translation Properties Files with Maven

1. Add Maven configuration

   Add the -AgenereatedTranslationFilePath compiler argument to the Maven compiler plug-in configuration and assign it the path where the new files will be created.

   <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>

   The above configuration will create the new files in the target/generated-translation-files directory of your Maven project.

2. Build the project

   Build the project using Maven.

   [Localhost]$ mvn compile

Procedure 6.5. Translate an internationalized logger, exception or message

1. Generate the template properties files

   Run the mvn compile command to create the template translation properties files.

2. Add the template file to your project

   Copy the template for the interfaces that you want to translate from the directory where they were created into the src/main/resources directory of your project. The properties files must be in the same package as the interfaces they are translating.

3. Rename the copied template file

   Rename the copy of the template file according to the translation it will contain. E.g. GreeterLogger.i18n_fr_FR.properties.

4. Translate the contents of the template.

   Edit the new translation properties file to contain the appropriate translation.

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

   Repeat steps two, three, and four for each translation of each bundle being performed.

Procedure 6.6. Add message IDs and Project Codes to Log Messages

1. Specify the project code for the interface.

   Specify the project code using the projectCode attribute of the @MessageLogger annotation attached to a custom logger interface. All messages that are defined in the interface will use that project code.

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

2. Specify Message IDs

   Specify a message ID for each message using the id attribute of the @Message annotation attached to the method that defines the message.

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

Procedure 6.7. Specify the log level for a message

1. Specify level attribute

   Add the level attribute to the @LogMessage annotation of the log message method definition.

2. Assign log level

   Assign the level attribute the value of the log level for this message. The valid values for level are the six enumerated constants defined in org.jboss.logging.Logger.Level: DEBUG, ERROR, FATAL, INFO, TRACE, and WARN.

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

Procedure 6.8. Customize log messages with parameters

1. Add parameters to method definition

   Parameters of any type can be added to the method definition. Regardless of type, the String representation of the parameter is what is displayed in the message.

2. Add parameter references to the log message

   References can use explicit or ordinary indexes.
   • To use ordinary indexes, insert the characters %s in the message string where you want each parameter to appear. The first instance of %s will insert the first parameter, the second instance will insert the second parameter, and so on.
   • To use explicit indexes, insert the characters %{#$}s in the message, where # indicates the number of the parameter you wish to appear.

Procedure 6.9. Specify an exception as the cause of a log message

1. Add the parameter

   Add a parameter of the type Throwable or a sub-class to the method.

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

2. Add the annotation

   Add the @Cause annotation to the parameter.

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

3. Invoke the method

   When the method is invoked in your code, an object of the correct type must be passed and will be displayed after the log message.

   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);
   }
   

   Below is the output of the above code samples if the code threw an exception of type FileNotFoundException.

   10:50:14,675 INFO [com.company.app.Main] (MSC service thread 1-3) Loading configuration failed. Config file: customised.properties
   java.io.FileNotFoundException: customised.properties (No such file or directory)
      at java.io.FileInputStream.open(Native Method)
      at java.io.FileInputStream.<init>(FileInputStream.java:120)
      at com.company.app.demo.Main.openCustomProperties(Main.java:70)
      at com.company.app.Main.go(Main.java:53)
      at com.company.app.Main.main(Main.java:43)

Procedure 6.10. Add Message IDs and Project Codes to Exception Messages

1. Specify a project code

   Specify the project code using the projectCode attribute of the @MessageBundle annotation attached to a exception bundle interface. All messages that are defined in the interface will use that project code.

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

2. Specify message IDs

   Specify a message ID for each exception using the id attribute of the @Message annotation attached to the method that defines the exception.

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

Procedure 6.11. Customize an exception message with parameters

1. Add parameters to method definition

   Parameters of any type can be added to the method definition. Regardless of type, the String representation of the parameter is what is displayed in the message.

2. Add parameter references to the exception message

   References can use explicit or ordinary indexes.
   • To use ordinary indexes, insert the characters %s in the message string where you want each parameter to appear. The first instance of %s will insert the first parameter, the second instance will insert the second parameter, and so on.
   • To use explicit indexes, insert the characters %{#$}s in the message where #indicates the number of the parameter which you wish to appear.
   Using explicit indexes allows the parameter references in the message to be in a different order than they are defined in the method. This is important for translated messages which may require different ordering of parameters.

Procedure 6.12. Specify one exception as the cause of another exception

1. Add the parameter

   Add the a parameter of the type Throwable or a sub-class to the method.

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

2. Add the annotation

   Add the @Cause annotation to the parameter.

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

3. Invoke the method

   Invoke the interface method to obtain an exception object. The most common use case is to throw a new exception from a catch block using the caught exception as the cause.

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