Using Message Catalogs with BEA WebLogic Server


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| Download Documentation \| Contact \| Glossary

\| WebLogic Server Doc Home \| Internationalization Guide \| Previous Topic \| Next Topic \| Contents \| View as PDF

All internationalized text is defined in message catalogs, each of which defines a collection of log messages or simple text.

A message catalog is an XML file that is defined in a document type description (DTD), and defines text messages. Each catalog defines the log messages or simple text used by some subset of the system. Users may choose to create a single log message catalog for all their logging requirements, or to create smaller catalogs based on a subsystem or Java package. We recommend the latter method. Using multiple subsystems allows you to focus on specific portions of the log during viewing.

For simple text catalogs, the recommended approach is to create a single catalog for each utility being internationalized. Developers can create site-specific message catalogs using the tools described in Using the BEA WebLogic Server Internationalization Tools and Utilities.

All messages and exceptions must be defined in a default, top-level catalog. WLS is distributed with a collection of catalogs located in /weblogic/msgcat within the weblogic.jar file.

This section presents information about the following topics related to message catalogs:

Message Catalog Types

DTDs that describe the syntax of the message catalogs are also stored in the weblogic/msgcat directory. Two DTDs are included in the WLS distribution:

msgcat.dtd—Describes the syntax of top-level, default catalogs. These catalogs include information that is not in the locale-specific catalogs, such as message severity.
l10n_msgcat.dtd—Describes the syntax of locale-specific catalogs.

In this directory you will also find templates that can be used to create top-level and locale-specific message catalogs.

Including Message Arguments

All of the sections of a log message can include message arguments, as described by java.text.MessageFormat. A message can support up to 10 arguments, numbered 0-9. Any subset of these arguments can be included in any of the text sections of the message definition. Message arguments are inserted into a message definition during development, and are replaced by the appropriate message content at run time when the message is logged.

The following excerpt from an XML log message definition shows how message arguments can be used. The argument number must correspond with one of the arguments specified in the method attribute. Specifically, {0} with the first argument, {1} with the second, and so on.

 <messagebody>Unable to open file, {0}.</messagebody>
     <messagedetail>
     File, {0} does not exist. The server will restore the file
     contents from {1}, resulting in the use of default values
     for all future requests.
     </messagedetail>
     <cause>The file was deleted</cause>
     <action>
     If this error repeats then investigate unauthorized access to
     the file system.
     </action>

An example of a method attribute for the above message is as follows:

 -method="logNoFile(String name, String path)"

The message expects two arguments, {0} and {1}:

{0} is used in the message body.
Both are used in the message detail.
Neither is used in the <cause> or <action> section.

In addition, the arguments are expected to be strings, or representable as strings. Numeric data is represented as {n,number}. Dates are supported as {n,date}. Log messages must be assigned a severity level. Generating a log message is accomplished via the generated Logger methods, as defined by the method attribute.

Choosing Names for Message Catalogs

The name of the message catalog file (without the .xml extension) is used to generate Localizer and Logger class names; it should be chosen carefully. For example, a name for a message catalog should:

Not conflict with any names of existing classes in the target package
Not contain characters that are not allowed in class names
Follow class naming standards

For example, the resulting class names for a catalog named Xyz.xml are XyzLogLocalizer and XyzLogger.

Message IDs are generally six-character strings with leading zeros. Some interfaces also support integer representations.

A package name should be consistent with the name of the subsystem in which a particular catalog resides.

The log Localizer "classes" are actually ResourceBundle property files.

Message Catalog Hierarchy

Message catalogs support multiple locales or languages. For a specific message catalog there is exactly one default version, known as the top-level catalog, and one catalog for each additional supported locale. For example, you might have a top-level catalog named mycat.xml, and a Japanese translation of it called ../ja/mycat.xml. Typically the top-level catalog is English, but English is not required for any catalogs except the installed WLS catalogs.

Locale designations (for example, ja) also have a hierarchy as defined in the java.util.Locale documentation. Briefly, a locale can include a language, country and variant. Language is the most standard. Language can be extended with a country code. For instance, en/US, indicates American English. The name of the associated catalog would be ../en/US/mycat.xml. Variants are vendor or browser-specific and are used to introduce minor differences (for example, collation sequences) between two or more locales defined by either language or country.

Message Catalog Formats

The catalog format for top-level and locale-specific catalog files is slightly different; locale-specific catalogs only provide translations of text defined in the top-level version. Furthermore log message catalogs are defined differently than simple text catalogs. The differences are made evident in the descriptions that follow.

Elements of a Log Message Catalog

This section provides reference information for the following elements of a log message catalog:

message_catalog

The following table describes the attributes that can be defined for the message_catalog element.

Attribute...	Description...
i18n_package	Optional. Java package in which to place generated Logger classes for this catalog. The classes are named after the catalog file name. For exampale, for a catalog using mycat.xml, a generated logger class called i18n_package.mycatLogger.class. The default is weblogic.i18n.
l10n_package	Optional. Java package to place generated LogLocalizer properties for this catalog. Classes are named after the catalog file name. For example, for a catalog called mycat.xml a properties file called l10n_package.mycatLogLocalizer.properties is generated. The default is weblogic.i18n
subsystem	Required. An acronym identifying the subsystem associated with this catalog. The name of the subsystem is included in the error log, and is used for message isolation purposes.
version	Required. Specifies the version of the msgcat.dtd being used. The usage is n.n, for example, version="1.0"
baseid	Optional. Specifies the lowest message ID used in this catalog. The syntax is one to six decimal units. Default is 000000 for WLS catalogs, 500000 for user catalogs.
endid	Optional. Specifies the highest message ID used in this catalog. The syntax is one to six decimal units. Default is 499999 for WLS catalogs, 999999 for user catalogs.

log_message

The following table describes the attributes that can be defined for the log_message element.

Attribute...	Description...
messageid	Required. Unique identifier for this log message. Uniqueness should extend across all catalogs. Value must be in range defined by baseid and endid attributes defined above. This is a child element of message_catalog.
datelastchanged	Optional. Date/time stamp useful for managing modifications to this message. The date will be supplied by utilities which run on the catalogs The syntax is Long.toString(new Date().getTime());
severity	Required. The severity of the log message. Must be one of the following: "debug","info", "warning", "notice", "error", "critical", "alert", or "emergency". User catalogs may only use "debug", "info", "warning", and "error".
stacktrace	Optional. Indicates whether to generate a stack trace for Throwable arguments. Possible values are true or false. Default is true. When the value is true a trace is generated. The syntax is: stacktrace="true"
method	Required. Method signature for logging this message. Two methods are actually provided: the one specified here and a similar one with an additional Throwable argument. The syntax is the standard Java method signature, less qualifiers, semicolon, and extensions. Arguments types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, they should have a useful toString() method. Argument can be any valid name, but should follow the convention of argn where n is 0 thru 9. There can be no more than ten (10) arguments. For each argn there should be at least one corresponding placeholder in the text elements described in Other Log Message Catalog Elements. Placeholders are of the form {n}, {n,number} or {n,date}.

Other Log Message Catalog Elements

Element...	Description...
messagebody	Required. A string containing a short description for this message. This element may contain zero or more placeholders, {n}, which will be replaced by the appropriate argument when the log message is localized. This is a child element of log_message.
messagedetail	Required. A string containing a detailed description of the event. This element may contain zero or more placeholders, {n}, which will be replaced by the appropriate argument when the log message is localized. This is a child element of log_message.
cause	Required. A string describing the root cause of the problem. This element may contain zero or more placeholders, {n}, which will be replaced by the appropriate argument when the log message is localized. This is a child element of log_message.
action	Required. A string describing the recommended resolution. This element may contain zero or more placeholders, {n}, which will be replaced by the appropriate argument whenn the log message is localized. This is a child element of log_message.

Log Message Catalog Syntax

The following example shows a log message catalog, MyUtilLog.xml, with one log message:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"     
"http://www.bea.com/servers/wls610/dtd/msgcat.dtd">
<message_catalog 
  l10n_package="programs.utils"
  i18n_package="programs.utils"
  subsystem="MYUTIL"
  version="1.0"
  baseid="600000"
  endid="600100"
  <log_message
    messageid="600001"
    severity="warning"
    method="logNoAuthorization(String arg0, java.util.Date arg1, 
       int arg2)"
    <messagebody>
      Could not open file, {0} on {1,date} after {2,number} attempts.
    </messagebody>
    <messagedetail>
      The configuration for this application will be defaulted to
      factory settings. Custom configuration information resides
      in file, {0}, created on {1,date}, but is not readable.
    </messagedetail>
    <cause>
      The user is not authorized to use custom configurations. Custom
     configuration information resides in file, {0}, created on
     {1,date}, but is not readable.The attempt has been logged to
     the security log.
    </cause>
    <action>
      The user needs to gain approriate authorization or learn to
      live with the default settings.
    </action>
  </log_message>
</message_catalog>

Format of a Simple Text Message Catalog

This section provides reference information for the following log message catalog elements:

message_catalog

The following table describes the attributes that can be defined for the message_catalog element

Attribute...	Description...
l10n_package	Optional. Java package to place generated LogLocalizer properties for this catalog. The classes are named after the catalog file name. mycat.xml would generate the properties file l10n_package.mycatLogLocalizer.properties. The default is "weblogic.i18n"
subsystem	Required. An acronym identifying the associated subsystem for this catalog. The subsystem is included in the error log and used for message isolation purposes.
version	Required. Specifies the version of the msgcat.dtd being used. Must be at least "1.0".

message

The following table describes the attributes that can be defined for the message element.

Attribute...	Description...
messageid	Required. Unique identifier for this log message, in alpha-numeric string format. Uniqueness is required only within the context of this catalog. message is a child element of message_catalog.
datelastchanged	Optional. Date/time stamp useful for managing modifications to this message.
method	Optional. Method signature for formatting this message. The syntax is a standard Java method signature, less return type, qualifiers, semicolon, and extensions. The return type is always String. Argument types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, Class arguments should have a useful toString() method, and the corresponding MessageFormat placeholders must be strings; they must be of the form {n}. Argument names can be any valid name. There can be no more than 10 arguments. For each argument there must be at least one corresponding placeholder in the messagebody element described below. Placeholders are of the form {n}, {n,number} or {n,date}. Example: method="getNoAuthorization (String filename, java.util.Date creDate)" This example would result in a method in the TextFormatter class as follows: public String getNoAuthorization (String filename, java.util.Date creDate)

Attribute...

Description...

messageid

Required. Unique identifier for this log message, in alpha-numeric string format. Uniqueness is required only within the context of this catalog. message is a child element of message_catalog.

datelastchanged

Optional. Date/time stamp useful for managing modifications to this message.

method

Optional. Method signature for formatting this message.

The syntax is a standard Java method signature, less return type, qualifiers, semicolon, and extensions. The return type is always String. Argument types can be any Java primitive or class. Classes must be fully qualified if not in java.lang. Classes must also conform to java.text.MessageFormat conventions. In general, Class arguments should have a useful toString() method, and the corresponding MessageFormat placeholders must be strings; they must be of the form {n}. Argument names can be any valid name. There can be no more than 10 arguments.

For each argument there must be at least one corresponding placeholder in the messagebody element described below. Placeholders are of the form {n}, {n,number} or {n,date}.

Example:

method="getNoAuthorization
(String filename, java.util.Date creDate)"

This example would result in a method in the TextFormatter class as follows:

public String getNoAuthorization
(String filename, java.util.Date creDate)

messagebody

The text associated with the message.

Use

Required. This element may contain zero or more placeholders, {n}, which will be replaced by the appropriate arguments when the log message is localized. messagebody is a child element of message.

Simple Text Catalog Example

The following example shows a simple text catalog, MyUtilLabels.xml, with one text definition:

<?xml version="1.0"?> 
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
    "http://www.bea.com/servers/wls610/dtd/msgcat.dtd"> 
<message_catalog>
 l10n_package="programs.utils"
 i18n_package="programs.utils"
 subsystem="MYUTIL"
 version="1.0"
 <message>
  messageid="FileMenuTitle"
  <messagebody>
    File
  </messagebody>
 </message>
</message_catalog>

Format of a Locale-Specific Catalog

The locale-specific catalogs are subsets of top-level catalogs. They are maintained in subdirectories named for the locales they represent. The following elements and attributes are valid in locale-specific catalogs:

locale_message_catalog element—Equivalent to message_catalog in a top-level definition
message element—Equivalent to message in a top-level definition.
messageid attribute—Governed by the same rules that apply to a top-level catalog. Must match a messageid in the associated top-level catalog.
messagebody, messagedetail, cause, action—Governed by the same rules that apply to a top-level catalog.

For example, a French translation of the message in MyUtilLabels.xml is available in the following directory:

   .../msgcat/fr/MyUtilLabels.xml

The translated message appears as follows:

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC 
   "weblogic-locale-message-catalog-dtd"
   "http://www.bea.com/servers/wls610/dtd/l10n_msgcat.dtd">
<locale_message_catalog 
  l10n_package="programs.utils"
  subsystem="MYUTIL" 
  version="1.0">
  <message>
    <messageid="FileMenuTitle">
    <messagebody> Fichier </messagebody>
  </message>
</locale_message_catalog>

When entering text in the messagebody, messagedetail, cause and action elements, you must use a tool that generates valid UTF-8 characters, and haveappropriate keyboard mappings installed. The MessageLocalizer utility is an example of such a tool.