Instrumenting Your Code for Localization

 

This section discusses the following types of code instrumentation:

• Logging a Message

• Creating a New Catalog

• Creating New Messages

• Modifying a Message

Logging a Message

The following sample code shows a log message named Stuff.xml:

<?xml version="1.0"?>
<!DOCTYPE message_catalog SYSTEM "msgcat.dtd">
<message_catalog
  i18n_package=weblogic.stuff
  subsystem=STF
  baseid="500000">
  <logmessage
    severity=warning
    messageid=501234
    method="logNoFile(String name)"
    <messagebody>
      Unable to open file, {0}
    </messagebody>
    <messagedetail>
      The file, {0}, does not exist. In its absence default
      values will be used and a new version of the file will
      be created automatically.
    </messagedetail>
    <cause>
      The file was deleted.
    </cause>
    <action>
      If this error repeats then investigate unauthorized
      access to the file system. Consider stiffening the
      permissions on the file and directory.
    </action>
  </logmessage>
</message_catalog>

The following sample code shows how the weblogic.stuff package logs message 1234:

Code in the weblogic.stuff package would log message 1234 as follows:

package weblogic.stuff;
import weblogic.stuff.StuffLogger;
import java.io.FileInputStream;
. . .
try {
  FileInputStream fis = new FileInputStream(myfile);
  . . .
}
catch (FileNotFoundException fnfe) {
StuffLogger.logNoFile(myfile);
}

Creating a New Catalog

To create a catalog, create a file with the Message Editor, or a text editor. For information about using the Message Editor, see Using the BEA WebLogic Server Internationalization Tools and Utilities.

Because a catalog is an XML file, the format must conform to the syntax specified in the msgcat.dtd. A template for log messages is provided in logmessage_template. Once created, the catalog must be processed by i18ngen, as described in Chapter 4, Using the BEA WebLogic Server Internationalization Tools and Utilities section " Creating a New Catalog."

The following points are important to consider when creating a new catalog:

1. The name of the file should follow Java class naming standards.

2. Messages should be added in numerical order.

3. All messages IDs must be larger than the base ID.

4. The base ID is specified not only in the catalog but in the Msgids file.

Once created the catalog must be processed by i18ngen as described in Chapter 4, Using the BEA WebLogic Server Internationalization Tools and Utilities section " Creating a New Catalog."

For easier management, all catalogs should reside in the same source directory.

Creating New Messages

Add the new message definition to the end of the catalog using a message ID one number greater than the last message defined. Select a method name that is unique within the catalog. Make sure the new ID is within the range specified for the catalog in the Msgids file. If it is not (for example, you have run out of IDs) then you will have to create a new catalog, or extend the range of your catalog using the endid attribute.

Once the changes have been made then the catalog must be processed by i18ngen as described in " Entering a New Log Message" in Chapter 4.

Modifying a Message

In general, only the message body, message detail, cause and action data should be changed within an existing message. This restriction is necessary because changing values in any other fields may result in code in the field not interfacing correctly (for example, passing the wrong number or type of arguments).

Reprocess the catalog by runniing the i18ngen command after modifications to the catalog are complete.