Chapter 4. Logging

1. If you have not yet done so, configure your Maven settings to use the JBoss EAP Maven repository.

   For more information, see Configure the JBoss EAP Maven Repository Using the Maven Settings.

2. Configure the project’s pom.xml file to use JBoss Logging Tools.

   For details, see JBoss Logging Tools Maven Configuration.

3. Create a message logger interface by adding a Java interface to your project to contain the log message definitions.

   Name the interface to describe the log messages it will define. The log message interface has the following requirements:

   • It must be annotated with @org.jboss.logging.annotations.MessageLogger.
   • Optionally, it can extend org.jboss.logging.BasicLogger.

   • The interface must define a field that is a message logger of the same type as the interface. Do this with the getMessageLogger() method of @org.jboss.logging.Logger.

     Example: Creating a Message Logger

     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. 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.annotation.LogMessage annotation.
   • It must be annotated with the @org.jboss.logging.annotations.Message annotation.
   • The default log level is INFO.

   • The value attribute of @org.jboss.logging.annotations.Message contains the default log message, which is used if no translation is available.

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

5. Invoke the methods by adding the calls to the interface methods in your code where the messages must be logged from.

   Creating implementations of the interfaces is not necessary, the annotation processor does this for you when the project is compiled.

   AccountsLogger.LOGGER.customerQueryFailDBClosed();

   The custom loggers are subclassed from BasicLogger, so the logging methods of BasicLogger can also be used. It is not necessary to create other loggers to log non-internationalized messages.

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

6. The project now supports one or more internationalized loggers that can be localized.

1. If you have not yet done so, configure your Maven settings to use the JBoss EAP Maven repository. For more information, see Configure the JBoss EAP Maven Repository Using the Maven Settings.
2. Configure the project’s pom.xml file to use JBoss Logging Tools. For details, see JBoss Logging Tools Maven Configuration.

3. Create an interface for the exceptions. JBoss Logging Tools defines internationalized messages in interfaces. Name each interface descriptively for the messages that it contains. The interface has the following requirements:

   • It must be declared as public.
   • It must be annotated with @org.jboss.logging.annotations.MessageBundle.

   • The interface must define a field that is a message bundle of the same type as the interface.

     Example: Create a MessageBundle Interface

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

     Note

     Calling Messages.getBundle(GreetingMessagesBundle.class) is equivalent to calling Messages.getBundle(GreetingMessagesBundle.class, Locale.getDefault()).

     Locale.getDefault() gets the current value of the default locale for this instance of the Java Virtual Machine. The Java Virtual Machine sets the default locale during startup, based on the host environment. It is used by many locale-sensitive methods if no locale is explicitly specified. It can be changed using the setDefault method.

     See Set the Default Locale of the Server in the JBoss EAP Configuration Guide for more information.

4. 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.annotations.Message annotation.

   • The value attribute of @org.jboss.logging.annotations.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();

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

   System.out.println(helloworldString());

1. Configure the project’s pom.xml file to use JBoss Logging Tools. For details, see 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 @MessageBundle.

   • The interface must define a field that is a message bundle of the same type as the interface.

     Example: Create an ExceptionBundle Interface

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

3. 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 Exception object, or a sub-type of Exception.
   • It must be annotated with the @org.jboss.logging.annotations.Message annotation.
   • The value attribute of @org.jboss.logging.annotations.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 they are in the constructor of the exception.

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

Generate the Translation Properties Files

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

   This configuration creates the new files in the target/generated-translation-files directory of your Maven project.

   Example: Define the Translation File Path

   <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. Build the project using Maven:

   $ mvn compile

   One properties file is created for each interface annotated with @MessageBundle or @MessageLogger.

   • The new files are created in a subdirectory corresponding to the Java package in which each interface is declared.

   • Each new file is named using the following pattern where INTERFACE_NAME is the name of the interface used to generated the file.

     INTERFACE_NAME.i18n_locale_COUNTRY_VARIANT.properties

Translate an Internationalized Logger, Exception, or Message

1. Run the following command to create the template translation properties files:

   $ mvn compile

2. 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 to indicate the language it will contain. For example: GreeterLogger.i18n_fr_FR.properties.

4. Edit the contents of the new translation properties file to contain the appropriate translation:

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

5. Repeat the process of copying the template and modifying it for each translation in the bundle.

Prerequisites

1. You must already have a project with internationalized log messages. For details, see Create Internationalized Log Messages.
2. You need to know the project code you will be using. You can use a single project code, or define different ones for each interface.

Add Message IDs and Project Codes to Log Messages

1. Specify the project code for the interface by 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 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();

3. The log messages that have both a message ID and project code associated with them will prepend these to the logged message.

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

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

2. Assign the log level for this message using the level attribute. 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();

Customize Log Messages with Parameters

1. Add parameters of any type 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 %s characters 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 %#$s characters in the message, where # indicates the number of the parameter that you wish to appear.

Specify an Exception as the Cause of a Log Message

1. Add a parameter of the type Throwable or its subclass to the method.

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

2. Add the @Cause annotation to the parameter.

   import org.jboss.logging.annotations.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);
   }

Prerequisites

1. You must already have a project with internationalized exceptions. For details, see Create Internationalized Exceptions.
2. You need to know the project code you will be using. You can use a single project code, or define different ones for each interface.

Add Message IDs and Project Codes to Exception Messages

1. 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 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();

Customize Exception Messages with Parameters

1. Add parameters of any type 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 %s characters 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 %#$s characters in the message, where # indicates the number of the parameter that you wish to appear.

1. Add a parameter of the type Throwable or its subclass to the method.

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

2. Add the @Cause annotation to the parameter.

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

3. 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");
   }

1. If you have not yet done so, configure your Maven settings to use the JBoss EAP repository. For more information, see Configure the JBoss EAP Maven Repository Using the Maven Settings.

   Include the jboss-eap-javaee7 BOM in the <dependencyManagement> section of the project’s pom.xml file.

   <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. Add the Maven dependencies to the project’s pom.xml file:

   1. Add the jboss-logging dependency for access to JBoss Logging framework.

   2. If you plan to use the JBoss Logging Tools, also add the jboss-logging-processor dependency.

      Both of these dependencies are available in JBoss EAP BOM that was added in the previous step, so the scope element of each can be set to provided as shown.

      <!-- 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. The maven-compiler-plugin must be at least version 3.1 and configured for target and generated sources of 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>