Create JRas resource bundles and message files

The WebSphere Application Server - Express message logger provides the message() and msg() methods to allow the user to log localized messages. In addition, it provides the textMessage() method for logging of messages that are not localized. Applications can use either or both, as appropriate.

The mechanism for providing localized messages is the Resource Bundle support provided by the Java Development Kit (JDK). If you are not familiar with resource bundles as implemented by the JDK, you can get more information from various texts, or by reading the javadoc for the java.util.ResourceBundle, java.util.ListResourceBundle and java.util.PropertyResourceBundle classes, as well as the java.text.MessageFormat class.

The PropertyResourceBundle is the preferred mechanism to use. In addition, note that the JRas extensions do not support the extended formatting options such as {1, date} or {0,number, integer} that are provided by the MessageFormat class.

You can forward messages that are written to the internal WebSphere Application Server - Express logs to other processes for display. For example, messages displayed on the administration console can be localized using the late binding process. Late binding means that WebSphere Application Server - Express does not localize messages when they are logged, but defers localization to the process that displays the message.

To properly localize the message, the displaying process must have access to the resource bundle where the message text is stored. This means that you must package the resource bundle separately from the application, and install it in a location where the viewing process can access it. If you do not want to take these steps, you can use the early binding technique to localize messages as they are logged.

The techniques are described as follows:

• Early binding

  The application must localize the message before logging it. The application looks up the localized text in the resource bundle and formats the message. When formatting is complete, the application logs the message using the textMessage() method. Use this technique to package the application's resource bundles with the application.

• Late binding

  The application can choose to have the WebSphere Application Server - Express runtime localize the message in the process where it is displayed. Using this technique,the resource bundles are packaged in a standalone .jar file, separately from the application. You must then install the resource bundle .jar file on every machine in the installation from which an administrator's console or log viewing program might be run. You must install the .jar file in a directory that is part of the extensions classpath. In addition, if you forward logs to IBM service, you must also forward the .jar file containing the resource bundles.

To create a resource bundle, perform the following steps.

1. Create a text properties file that lists message keys and the corresponding messages.

   The properties file must have the following characteristics:

   • Each property in the file is terminated with a line-termination character.
   • If a line contains only white space, or if the first non-white space character of the line is the symbol # (pound sign) or ! (exclamation mark), the line is ignored. The # and ! characters can therefore be used to put comments into the file.
   • Each line in the file, unless it is a comment or consists only of white space, denotes a single property. A backslash (\) is treated as the line-continuation character.
   • The syntax for a property file consists of a key, a separator, and an element. Valid separators include the equal sign (=), colon (:), and white space ( ).
   • The key consists of all characters on the line from the first non-white space character to the first separator. Separator characters can be included in the key by escaping them with a backslash (\), but doing this is not recommended, because escaping characters is error prone and confusing. It is instead recommended that you use a valid separator character that does not appear in any keys in the properties file.
   • White space after the key and separator is ignored until the first non-white space character is encountered. All characters remaining before the line-termination character define the element.

   See the Java documentation for the java.util.Properties class for a full description of the syntax and construction of properties files.

2. The file can then be translated into localized versions of the file with language-specific file names (for example, a file named DefaultMessages.properties can be translated into DefaultMessages_de.properties for German and DefaultMessages_ja.properties for Japanese).
3. When the translated resource bundles are available, write them to a system-managed persistent storage medium. Resource bundles are then used to convert the messages into the requested national language and locale.
4. When a message logger is obtained from the JRas manager, it can be configured to use a particular resource bundle. Messages logged via the message() API will use this resource bundle when message localization is performed. At run time, the user's locale setting is used to determine the properties file from which to extract the message specified by a message key, thus ensuring that the message is delivered in the correct language.
5. Optional: If the message loggers msg() method is called, a resource bundle name must be explicitly provided.

The application locates the resource bundle based on the file's location relative to any directory in the classpath. For instance, if the property resource bundle named DefaultMessages.properties is located in the baseDir/subDir1/subDir2/resources directory and baseDir is in the class path, the name subdir1.subdir2.resources.DefaultMessage is passed to the message logger to identify the resource bundle.

For more information on creating JRas resource bundles, see Develop JRas resource bundles.