Using WebLogic Logging Services for Application Logging
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
The following sections describe message catalogs and how to use them:
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 using weblogic.i18ngen during the build process. (See weblogic.i18ngen Utility for more information). The methods of the resulting classes are the objects used to log messages at runtime.
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.
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:\bea\weblogic90
, however, you are not required to install this directory under BEA_HOME
.
You can also download the DTDs at: http://www.bea.com/servers/wls90/dtd/msgcat.dtd
.
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. BEA recommends using multiple subsystem catalogs so you can focus on specific portions of the log during viewing.
For simple text catalogs, BEA recommends 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.
All messages must be defined in the default, top-level catalog. The WebLogic Server installation includes a collection of sample catalogs in the SAMPLES_HOME
\server\examples\src\examples\i18n\msgcat
directory, where SAMPLES_HOME
represents the WebLogic Server examples home directory at WL_HOME
\samples
.
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 SAMPLES_HOME
\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.
Because the name of a message catalog file (without the .xml
extension) is used to generate runtime class and property names, you should choose the name carefully.
Follow these guidelines for naming message catalogs:
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:
Note: This only applies to log message catalogs. Simple text catalogs can have any string value.
ResourceBundle
property files.
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 Listing 4-1, {0}
represents the file that cannot be opened, while {1}
represents the file that will be opened in its place.
Listing 4-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
, Stringpath
)"
The message example in Listing 4-1 expects two arguments, {0}
and {1}
:
<messagebody>
<messagedetail>
<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.
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:
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.
Listing 4-2 Example of a Log Message 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"
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>
This section provides reference information for the following elements of a log message catalog:
The message_catalog
element represents the log message catalog. The following table describes the attributes that you can define for the message_catalog
element.
The following table describes the attributes that you can define for the log_message
element.
Unique identifier for this log message. Uniqueness should extend across all catalogs. Value must be in range defined by Use: Value must be in the range defined by the |
|||
Date/time stamp used for managing modifications to this message. The date is supplied by utilities that run on the catalogs.
Use: The date is supplied by utilites (such as MessageEditor), that run on the catalogs. |
|||
Indicates the severity of the log message. Must be one of the following: |
|||
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 Arguments can be any valid name, but should follow the convention of |
|||
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: |
|||
Indicates whether to generate a stack trace for Throwable arguments. Possible values are |
|||
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. |
The following table describes the child elements of the log_message element.
The following example shows a simple text catalog, MyUtilLabels.xml
, with one simple text definition:
<messagebody>
File
</messagebody>
Listing 4-3 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>
This section provides reference information for the following simple text catalog elements:
The following table describes the attributes that you can define for the message_catalog
element.
The following table describes the attributes that you can define for the message
element.
The following table describes the child element of the message element.
The text associated with the message. This element may contain zero or more placeholders |
The following example shows a French translation of a message that is available in ...\msgcat\fr\MyUtilLabels.xml.
The translated message appears as shown in Listing 4-4.
Listing 4-4 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.
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.
The following table describes the attributes that you can define for the locale_message_catalog
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.
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.
![]() ![]() |
![]() |
![]() |