3 Using Message Catalogs with WebLogic Server

A message catalog is a single XML file that contains a collection of text messages, with each message indexed by a unique identifier. You compile these XML files into classes that contain methods, which are the objects used to log messages at run time.

• Overview of Message Catalogs

• Message Catalog Hierarchy

• Guidelines for Naming Message Catalogs

• Using Message Arguments

• Message Catalog Formats

Overview of Message Catalogs

Message catalogs support multiple locales or languages. For a specific message catalog, there is exactly one default version known as the top-level catalog, which contains the English version of the messages. Then there are corresponding locale-specific catalogs, one for each additional supported locale. You use the weblogic.i18ngen utility during the build process to compile the XML message catalog files. See weblogic.i18ngen Utility.

The top-level catalog (English version) includes all the information necessary to define the message. The locale-specific catalogs contain only the message ID, the date changed, and the translation of the message for the specific locale.

The message catalog files are defined by an XML document type definition (DTD). The DTDs are stored in the weblogic\msgcat directory of WL_HOME\server\lib\weblogic.jar, where WL_HOME represents the top-level installation directory for WebLogic Server. The default path is c:\Oracle\Middleware\Oracle_Home\wlserver; however, you are not required to install this directory in the Oracle home, represented as ORACLE_HOME.

Two DTDs are included in the WebLogic Server installation:

• msgcat.dtd - Describes the syntax of top-level, default catalogs.

• l10n_msgcat.dtd - Describes the syntax of locale-specific catalogs.

The weblogic\msgcat directory of WL_HOME\server\lib\weblogic.jar contains templates that you can use to create top-level and locale-specific message catalogs.

You can create a single log message catalog for all logging requirements, or create smaller catalogs based on a subsystem or Java package. Oracle recommends using multiple subsystem catalogs so you can focus on specific portions of the log during viewing.

For simple text catalogs, we recommend creating a single catalog for each utility being internationalized. You create message catalogs using the Message Editor as described in Using the WebLogic Server Message Editor.

Message Catalog Hierarchy

All messages must be defined in the default, top-level catalog. The WebLogic Server installation includes a collection of sample catalogs in the ORACLE_HOME\wlserver\samples\server\examples\src\examples\i18n\msgcat directory.

Catalogs that provide different localizations of the base catalogs are defined in msgcat subdirectories named for the locale (for example, msgcat/de for Germany). You might have a top-level catalog named mycat.xml, and a German translation of it called ..de/mycat.xml. Typically the top-level catalog is English. However, English is not required for any catalogs, except for those in the ORACLE_HOME\wlserver\samples\server\examples\src\examples\i18n\msgcat directory.

Locale designations (for example, de) also have a hierarchy as defined in the java.util.Locale documentation. A locale can include a language, country, and variant. Language is the most common locale designation. Language can be extended with a country code. For instance, en\US, indicates American English. The name of the associated catalog is ..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.

Guidelines for Naming Message Catalogs

Because the name of a message catalog file (without the .xml extension) is used to generate runtime class and property names, you must choose the name carefully. Follow these guidelines for naming message catalogs:

• Do not choose a message catalog name that conflicts with the names of existing classes in the target package for which you are creating the message catalog.

• The message catalog name should only contain characters that are allowed in class names.

• Follow class naming standards.

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

The following considerations also apply to message catalog files:

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

  Note:

  This only applies to log message catalogs. Simple text catalogs can have any string value.

• Java lets you group classes into a collection called a package. 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.

Using Message Arguments

Your message contents must conform to the patterns specified by java.text.MessageFormat.

The message body, message detail, cause, and action sections of a log message can include message arguments, as described by java.text.MessageFormat. Only the message body section in a simple text message can include arguments. Arguments are values that can be dynamically set at runtime. These values are passed to routines, such as printing out a message. A message can support up to 10 arguments, numbered 0-9. You can include any subset of these arguments in any text section of the message definition (Message Body, Message Detail, Probable Cause), although the message body must include all of the arguments. You insert message arguments into a message definition during development, and these arguments are replaced by the appropriate message content at runtime when the message is logged.

The following excerpt from an XML log message definition shows how you can use message arguments. The argument number must correspond to one of the arguments specified in the method attribute. Specifically, {0} with the first argument, {1} with the second, and so on. In Example 3-1, {0} represents the file that cannot be opened, while {1} represents the file that will be opened in its place.

Example 3-1 Example of Message Arguments

<messagebody>Unable to open file, {0}. Opening {1}. All arguments must be in body.</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 is as follows:

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

The message example in Example 3-1 expects two arguments, {0} and {1}:

• Both are used in the <messagebody>

• Both are used in the <messagedetail>

• Neither is used in <cause> or <action>

  Note:

  A message can support up to 10 arguments, numbered 0-9. You can include any subset of these arguments in any text section of the message definition (message detail, cause, action), although the message body must include all of the arguments.

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}. You must assign a severity level for log messages. Log messages are generated through the generated Logger methods, as defined by the method attribute.

Retrieving Additional Information About an Error Message

You can retrieve the detailed description, cause, and action for any error message that appears in the log files or on the console using the weblogic.GetMessage utility.

The weblogic.GetMessage utility displays the message content and can also be used to list all or some subset of the installed messages. See weblogic.GetMessage Utility for more information about using the utility.

Message Catalog Formats

The catalog format for top-level and locale-specific catalog files is slightly different. The top-level catalogs define the textual messages for the base locale (by default, this is the English language). Locale-specific catalogs (for example, those translated to Spanish) only provide translations of text defined in the top-level version. Log message catalogs are defined differently from simple text catalogs.Examples and elements of each type of message catalog are described in the following sections:

• Example Log Message Catalog

• Elements of a Log Message Catalog

• Example Simple Text Catalog

• Elements of a Simple Text Catalog

• Example Locale-Specific Catalog

• Elements of a Locale-Specific Catalog

Example Log Message Catalog

The following example shows a log message catalog, MyUtilLog.xml, containing one log message. This log message illustrates the usage of the messagebody, messagedetail, cause, and action elements.

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd" 
"http://www.bea.com/servers/wls90/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>

Elements of a Log Message Catalog

The following sections provide reference information for the elements of a log message catalog:

• message_catalog Element

• log_message Element

• Child Elements of log_message Element

message_catalog Element

The message_catalog element represents the log message catalog. The following table describes the attributes that you can define for the message_catalog element.

Table 3-1 Attributes for message_catalog Element

Attribute	Default Value	Required/Optional	Description
i18n_package	weblogic.i18n	Optional	Java package containing generated Logger classes for this catalog. The classes are named after the catalog file name. For example, for a catalog using mycat.xml, a generated Logger class would be called <i18n_package>.mycatLogger.class. Syntax: standard Java package syntax Example: i18n_package="programs.utils"
l10n_package	weblogic.i18n	Optional	A Java package containing generated LogLocalizer properties for the catalog. For example, for a catalog called mycat.xml, the following property files would be generated: <l10n_package>.mycatLogLocalizer.properties and <l10n_package>mycatLogLocalizerDetail.properties. Syntax: standard Java package syntax Example: l10n_package="programs.utils"
subsystem	None	Required	An acronym identifying the subsystem associated with this catalog. The name of the subsystem is included in the server log and is used for message isolation purposes. Syntax: a String Example: subsystem="MYUTIL"
version	None	Required	Specifies the version of the msgcat.dtd being used. Use: Must be "1.0" Syntax: x.y where x and y are numeric. Example: version="1.0"
baseid	000000 for WebLogic Server catalogs 500000 for user-defined catalogs	Optional	Specifies the lowest message ID used in this catalog. Syntax: one to six decimal digits. Example: baseid="600000"
endid	499999 for WebLogic Server catalogs 999999 for user-defined catalogs	Optional	Specifies the highest message ID used in this catalog. Syntax: one to six decimal digits. Example: endid="600100"
loggable	false	Optional	Indicates whether to generate additional methods that return loggable objects. Syntax: "true" or "false" Example: loggable="true"
prefix	Null for user-defined catalogs "BEA" for WebLogic Server catalogs	Optional	Specifies a String to be prepended to message IDs when logged. Server messages default to "BEA" as the prefix and may not specify a different prefix. User messages can specify any prefix. A prefixed message ID is presented in a log entry as follows: <[prefix-]id> where prefix is this attribute and id is the six-digit message ID associated with a specific message. For example, if prefix is "XYZ", then message 987654 would be shown in a log entry as <XYZ-987654>. If the prefix is not defined, then the log entry would be <987654>. Syntax: any String (should be limited to five characters) Example: prefix="BEA"
description	Null (no description)	Optional	An optional attribute that serves to document the catalog content. Syntax: any String Example: description="Contains messages logged by the foobar application"

log_message Element

The following table describes the attributes that you can define for the log_message element.

Table 3-2 Attributes for log_message Element

Attribute	Default Value	Required/Optional	Description
messageid	None	Required	Unique identifier for this log message. Uniqueness should extend across all catalogs. Value must be in range defined by baseid and endid attributes. Use: Value must be in the range defined by the baseid and endid attributes defined in the message_catalog attribute. Syntax: one to six decimal digits. Example: messageid="600001"
datelastchanged	None	Optional	Date/time stamp used for managing modifications to this message. The date is supplied by utilities that run on the catalogs. The syntax is: Long.toString(new Date().getTime()); Use: The date is supplied by utilities (such as MessageEditor), that run on the catalogs. Syntax: Long.toString(new Date().getTime());
severity	None	Required	Indicates the severity of the log message. Must be one of the following: debug, info, warning, error, notice, critical, alert, or emergency. User-defined catalogs may only use debug, info, warning, and error. Example: severity="warning"
method	None	Required	Method signature for logging this message. The syntax is the standard Java method signature, without the qualifiers, semicolon, and extensions. 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. Arguments can be any valid name, but should follow the convention of argn where n is 0 through 9. There can be no more than 10 arguments. For each argn there should be at least one corresponding placeholder in the text elements described in Child Elements of log_message Element. Placeholders are of the form {n}, {n,number} or {n,date}.
methodtype	logger	Optional	Specifies type of method to generate. Methods can be loggers or getters. Logger methods format the message body into the default locale and log the results. Getter methods return the message body prefixed by the subsystem and messageid, as follows: [susbsystem:msgid]text Syntax: values are "logger" and "getter"
stacktrace	true	Optional	Indicates whether to generate a stack trace for Throwable arguments. Possible values are true or false. When the value is true, a trace is generated. Syntax: stacktrace="true"
retired	false	Optional	Indicates whether message is retired. A retired message is one that was used in a previous release but is now obsolete and not used in the current version. Retired messages are not represented in any generated classes or resource bundles. Syntax: values are "true" and "false" Example: retired="true"

Child Elements of log_message Element

The following table describes the child elements of the log_message element.

Table 3-3 Child Elements of log_message Element

Element	Parent Element	Required/Optional	Description
messagebody	log_message	Required	A short description for this message. The messagebody element can contain a 0 to 10 placeholder as {n}, to be replaced by the appropriate argument when the log message is localized. The message body must include placeholders for all arguments listed in the corresponding method attribute, unless the last argument is throwable or a subclass. Be careful when using single quotes, because these are specially parsed by java.text.MessageFormat. If it is appropriate to quote a message argument, use double quotes (as in the example below). If a message has one or more placeholders, in order for a single quote to appear correctly (for example, as an apostrophe), it must be followed by a second single quote. Syntax: a String Example: <messagebody>Could not open file "{0}" created on {1,date}.</messagebody>
messagedetail	log_message	Optional	A detailed description of the event. This element may contain any argument place holders. Syntax: a String Example: <messagedetail>The configuration for this application will be defaulted to factory settings.</messagedetail>
cause	log_message	Optional	The root cause of the problem. This element can contain any argument place holders. Syntax: a String Example: <cause>The user is not authorized to use custom configurations. The attempt has been logged to the security log.</cause>
action	log_message	Optional	The recommended resolution. This element can contain any argument place holders. Syntax: a String Example: <action>The user needs to gain appropriate authorization or learn to live with the default settings.</action>

Example Simple Text Catalog

Example 3-2 shows a simple text catalog, MyUtilLabels.xml, with one simple text definition:

<messagebody>
    File
</messagebody>

Example 3-2 Example of a Simple Text Catalog

<?xml version="1.0"?> 
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
    "http://www.bea.com/servers/wls90/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>

Elements of a Simple Text Catalog

The following sections provide reference information for the simple text catalog elements:

• message_catalog Element

• message Element

• messagebody Element

message_catalog Element

The following table describes the attributes that you can define for the message_catalog element.

Table 3-4 Attributes for message_catalog Element

Attribute	Default Value	Required/Optional	Description
l10n_package	weblogic.i18n	Optional	Java package containing generated TextFormatter classes and TextLocalizer properties for this catalog. The classes are named after the catalog file name. mycat.xml would have the properties file, <l10n_package>.mycatLogLocalizer.properties generated. Syntax: standard Java package syntax Example: l10n_package="programs.utils"
subsystem	None	Required	An acronym identifying the subsystem associated with this catalog. The name of the subsystem is included in the server log and is used for message isolation purposes. Syntax: a String Example: subsystem="MYUTIL"
version	None	Required	Specifies the version of the msgcat.dtd being used. The format is n.n, for example, version="1.0". Must be at least "1.0". Example: version="1.0"
description	Null	Optional	An optional attribute that documents the catalog content. Syntax: a String Example: description="Contains labels used in the foobar GUI"

message Element

The following table describes the attributes that you can define for the message element.

Table 3-5 Attributes for message Element

Attribute	Default Value	Required/Optional	Description
messageid	None	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	None	Optional	Date/time stamp useful for managing modifications to this message.
method	None	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 Element

The following table describes the child element of the message element.

Table 3-6 Child Elements of message Element

Element	Parent Element	Required/Optional	Description
messagebody	message	Required	The text associated with the message. This element may contain zero or more placeholders {n} that will be replaced by the appropriate arguments when the log message is localized.

Example Locale-Specific Catalog

Example 3-3 shows a French translation of a message that is available in ...\msgcat\fr\MyUtilLabels.xml.

The translated message appears as shown in Example 3-3.

Example 3-3 Example of a Message Translated to French

<?xml version="1.0"?>
<!DOCTYPE message_catalog PUBLIC 
   "weblogic-locale-message-catalog-dtd"
   "http://www.bea.com/servers/wls90/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 Unicode Transformation Format-8 (UTF-8) characters, and have appropriate keyboard mappings installed. UTF-8 is an efficient encoding of Unicode character-strings that optimizes the encoding ASCII characters. Message catalogs always use UTF-8 encoding. The MessageLocalizer utility that is installed with WebLogic Server is a tool that can be used to generate valid UTF-8 characters.

Elements 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 elements and attributes described in the following sections are valid for locale-specific catalogs.

• locale_message_catalog Element

• log_message Element

• Other locale_message_catalog Elements

locale_message_catalog Element

The following table describes the attributes that you can define for the locale_message_catalog element.

Table 3-7 Attributes for locale_message_catalog Element

Attribute	Default Value	Required/Optional	Description
l10n_package	weblogic.i18n	Optional	Java package containing generated LogLocalizer or TextLocalizer properties for this catalog.properties file are named after the catalog file name. For example, for a French log message catalog called mycat.xml, a properties file called <l10n_package>.mycatLogLocalizer_fr_FR.properties is generated.
version	None	Required	Specifies the version of the msgcat.dtd being used. The format is n.n, for example, version="1.0". Must be at least "1.0".

log_message Element

The locale-specific catalog uses the attributes defined for the log_message element in the top-level log message catalog so this element does not need to be defined.

Other locale_message_catalog Elements

The locale-specific catalog uses the messagebody, messagedetail, cause, and action catalog elements defined for the top-level log message catalog so these elements do not need to be defined.