Create log resource bundles and message files

We can forward messages that are written to the internal WebSphere Application Server logs to other processes for display. Messages that are displayed on the console, which can be running in a different location than the server process, can be localized using the late binding process. Late binding means that WAS does not localize messages when they are logged, but defers localization to the process that displays the message.

Every method that accepts messages localizes those messages. The mechanism for providing localized messages is the resource bundle support provided by the IBM Developer Kit, Java Technology Edition. If we are not familiar with resource bundles as implemented by the Developer Kit, we can get more information from various texts, or by reading the API documentation for the java.util.ResourceBundle, java.util.ListResourceBundle and java.util.PropertyResourceBundle classes, as well as the java.text.MessageFormat class.

The PropertyResourceBundle class is the preferred mechanism to use.

To properly localize the message, the displaying process must have access to the resource bundle where the message text is stored. We must package the resource bundle separately from the application, and install it in a location where the viewing process can access it.

By default, the WAS runtime localizes all the messages when they are logged. This localization eliminates the need to pass a .jar file to the application, unless we need to localize in a different location. However, we can use the early binding technique to localize messages as they log. An application that uses early binding must localize the message before logging it. The application looks up the localized text in the resource bundle and formats the message. Use the early binding technique to package the application resource bundles with the application.

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 white space only, or if the first non-white space character of the line is the pound sign symbol (#) 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 of white space only, 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 process is not recommended, because escaping characters is error prone and confusing. Instead, use a valid separator character that does not display 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 the construction of properties files.

2. Translate the file 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, put the bundle in a directory that is part of the application class path.

4. When a message logger is obtained from the log manager, configure it to use a particular resource bundle. Messages logged with the Logger API use this resource bundle when message localization is performed. At run time, the user locale setting determines the properties file from which to extract the message specified by a message key, ensuring that the message is delivered in the correct language.

5. If the message loggers msg method is called, a resource bundle name must be explicitly provided.

Example

We can create resource bundles in several ways. The best and easiest way is to create a properties file that supports a properties resource bundle. This example shows how to create such a properties file.

For this sample, four localizable messages are provided. The properties file is created and the key-value pairs are inserted. All the normal properties file conventions and rules apply to this file. In addition, the creator must be aware of other restrictions that are imposed on the values by the Java MessageFormat class. For example, apostrophes must be escaped or they cause a problem. Avoid the use of non-portable characters. WAS does not support the use of extended formatting conventions that the MessageFormat class supports, such as {1, date} or {0,number, integer}.

Assume that the base directory for the application that uses this resource bundle is baseDir and that this directory is in the class path. Assume that the properties file is stored in the subdirectory baseDir that is not in the class path (for example, baseDir/subDir1/subDir2/resources). To allow the messages file to resolve, the subDir1.subDir2.resources.DefaultMessage name is used to identify the property resource bundle and is passed to the message logger.

For this sample, the properties file is named DefaultMessages.properties.

# Contents of the DefaultMessages.properties file MSG_KEY_00=A message with no substitution parameters. MSG_KEY_01=A message with one substitution parameter: parm1={0} MSG_KEY_02=A message with two substitution parameters: parm1={0}, parm2 = {1} MSG_KEY_03=A message with three parameter: parm1={0}, parm2 = {1}, parm3={2}

When the DefaultMessages.properties file is created, the file can be sent to a translation center where the localized versions are generated.

What to do next

The application locates the resource bundle based on the file location relative to any directory in the class path. For instance, if the DefaultMessages.properties property resource bundle 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.