Skip navigation.
Downloads | Product Documentation | Support

Using WebLogic Logging Services

# Writing Messages to the WebLogic Server Log

The following sections describe how you can facilitate the management of your application by writing log messages to the WebLogic Server log files:

- Using the I18N Message Catalog Framework: Main Steps
- Using the NonCatalogLogger APIs
- Using GenericServlet

In addition, this section includes the following sections:

- Writing Messages from a Remote Application
- Writing Debug Messages

# Using the I18N Message Catalog Framework: Main Steps

The internationalization (I18N) message catalog framework provides a set of utilities and APIs that your application can use to send its own set of messages to the WebLogic Server log. The framework is ideal for applications that need to localize the language in their log messages, but even for those applications that do not need to localize, it provides a rich, flexible set of tools for communicating status and output.

To write log messages using the I18N message catalog framework, complete the following tasks:

- Step 1: Create Message Catalogs
- Step 2: Compile Message Catalogs
- Step 3: Use Messages from Compiled Message Catalogs

## Step 1: Create Message Catalogs

A message catalog is an XML file that contains a collection of text messages. Usually, an application uses one message catalog to contain a set of messages in a default language and optional, additional catalogs to contain messages in other languages.

To create and edit a properly formatted message catalog, use the WebLogic Message Editor utility, which is a graphical user interface (GUI) that is installed with WebLogic Server. To create corresponding messages in local languages, use the Message Localizer, which is also a GUI that WebLogic Server installs.

To access the Message Editor, do the following from a WebLogic Server host:

1. Set the classpath by entering `WL_HOME``\server\bin\setWLSEnv.cmd` (`setWLSEnv.sh` on UNIX), where `WL_HOME` is the directory in which you installed WebLogic Server.
2. Enter the following command: `java weblogic.MsgEditor`
3. To create a new catalog, choose File—>New Catalog.

For information on using the Message Editor, refer to the following:

- Using the BEA WebLogic Server Message Editor in the BEA WebLogic Server Internationalization Guide.
- Using Message Catalogs with BEA WebLogic Server in the BEA WebLogic Server Internationalization Guide.

4. When you finish adding messages in the Message Editor, select File—>Save Catalog. Then select File—>Exit.

To access the Message Localizer, do the following from a WebLogic Server host:

1. Set the classpath by entering `WL_HOME``\server\bin\setWLSEnv.cmd` (`setWLSEnv.sh` on UNIX), where `WL_HOME` is the directory in which you installed WebLogic Server.
2. Enter the following command: `java weblogic.MsgLocalizer`
3. Use the Message Localizer GUI to create locale-specific catalogs.

## Step 2: Compile Message Catalogs

After you create message catalogs, you use the `i18ngen` and `l10ngen` command-line utilities to generate properties files and to generate and compile Java class files. The utilities take the message catalog XML files as input and create compiled Java classes. The Java classes contain methods that correspond to the messages in the XML files.

To compile the message catalogs, do the following:

1. From a command prompt, use `WL_HOME``\server\bin\setWLSEnv.cmd` (`setWLSEnv.sh` on UNIX) to set the classpath, where `WL_HOME` is the directory in which you installed WebLogic Server.
2. Enter the following command:

`java weblogic.i18ngen -build -d` `targetdirectory``` `source-files`

where:

- `targetdirectory` is the root directory in which you want the `i18ngen` utility to locate the generated and compiled files. The Java files are placed in sub-directories based on the `i18n_package` and `l10n_package` values in the message catalog.

The catalog properties file, `i18n_user.properties`, is placed in the `targetdirectory`. The default target directory is the current directory.

- `source-files` specifies the message catalog files that you want to compile. If you specify one or more directory names, `i18ngen` processes all XML files in the listed directories. If you specify file names, the names of all files must include an XML suffix. All XML files must conform to the `msgcat.dtd` syntax.

Note that when the `i18ngen` generates the Java files, it appends `Logger` to the name of each message catalog file.

3. If you created locale-specific catalogs in Step 1: Create Message Catalogs, do the following to generate properties files:

1. In the current command prompt, add the `targetdirectory` that you specified in step 2. to the CLASSPATH environment variable. To generate locale-specific properties files, all of the classes that the `i18ngen` utility generated must be on the classpath.
2. Enter the following command:
   `java l10ngen -d` `targetdirectory``` `source-files`

where:

- `targetdirectory` is the root directory in which you want the `l10ngen` utility to locate the generated properties files. Usually this is the same `targetdirectory` that you specified in step 2. The properties files are placed in sub-directories based on the `l10n_package` values in the message catalog.
- `source-files` specifies the message catalogs for which you want to generate properties files. You must specify top-level catalogs that the Message Editor creates; you do not specify locale-specific catalogs that the Message Localizer creates. Usually this is the same set of `source-files` or source directories that you specified in step 2.

4. In most cases, the recommended practice is to include the message class files and properties files in the same package hierarchy as your application.

However, if you do not include the message classes and properties in the application's package hierarchy, you must make sure the classes are in the application's classpath.

For complete documentation of the `i18ngen` commands, refer to Using the BEA WebLogic Server Internationalization Utilities in the BEA WebLogic Server Internationalization Guide.

### Example: Compiling Message Catalogs

In this example, the Message Editor created a message catalog that contains one message of type `loggable`. The Message Editor saves the message catalog as the following file: `c:\MyMsgCat\MyMessages.xml`.

Listing 2-1 shows the contents of the message catalog.

Listing 2-1 Sample Message Catalog

>     <?xml version="1.0" encoding="UTF-8"?>
>     <!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
>     "http://www.bea.com/servers/wls810/dtd/msgcat.dtd">

>     <message_catalog
>        i18n_package="com.xyz.msgcat"
>        l10n_package="com.xyz.msgcat.l10n"
>        subsystem="MyClient"
>        version="1.0"
>        baseid="700000"
>        endid="800000"
>        loggables="true"
>        prefix="XYZ-"
>     >

>     <!--  Welcome message to verify that the class has been invoked-->

>        <logmessage
>          messageid="700000"
>          datelastchanged="1039193709347"
>          datehash="-1776477005"
>          severity="info"
>          method="startup()"
>     >

>           <messagebody>
>              The class has been invoked.
>              </messagebody>

>           <messagedetail>
>              Verifies that the class has been invoked
>              and is generating log messages
>           </messagedetail>

>           <cause>
>              Someone has invoked the class in a remote JVM.
>           </cause>

>           <action> </action>

>        </logmessage>
>     </message_catalog>

In addition, the Message Localizer creates a Spanish version of the message in `MyMessages.xml`. The Message Localizer saves the Spanish catalog as `c:\MyMsgCat\es\ES\MyMessages.xml`.

Listing 2-2 Locale-Specific Catalog for Spanish

>     <?xml version="1.0" encoding="UTF-8"?>
>     <!DOCTYPE locale_message_catalog PUBLIC
>     "weblogic-locale-message-catalog-dtd"
>     "http://www.bea.com/servers/wls810/dtd/l10n_msgcat.dtd">

>     <locale_message_catalog
>     version="1.0"
>     >

>     <!-- Mensaje agradable para verificar que se haya invocado la clase. -->
>     <logmessage
>         messageid="700000"
>        datelastchanged="1039546411623"
>        >

>           <messagebody>
>              La clase se haya invocado.
>              </messagebody>

>           <messagedetail>
>              Verifica que se haya invocado la clase y está
>              generando mensajes del registro.
>           </messagedetail>

>           <cause>Alguien ha invocado la clase en un JVM alejado.</cause>
>           <action> </action>
>        </logmessage>

>     </locale_message_catalog>

To compile the message catalog that the Message Editor created, enter the following command:

`java weblogic.i18ngen -build -d c:\MessageOutput c:\MyMsgCat\MyMessages.xml`

The `i18ngen` utility creates the following files:

- `c:\MessageOutput\i18n_user.properties`
- `c:\MessageOutput\com\xyz\`msgcat\MyMessagesLogger.java
- `c:\MessageOutput\com\xyz\`msgcat\MyMessagesLogger.class
- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizer.properties`
- `c:\MessageOutput\com\xyz\`msgcat`\l10n\MyMessagesLogLocalizerDetails.properties`

To create properties files for the Spanish catalog, you do the following:

1. Add the `i18n` classes to the command prompt's classpath by entering the following:
   `set CLASSPATH=%CLASSPATH%;c:\MessageOutput`
2. Enter
   `java l10ngen -d c:\MessageOutput c:\MyMsgCat\MyMessages.xml`

The `l10ngen` utility creates the following files:

- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizer_es_ES.properties`
- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizerDetails_es_ES.properties`

## Step 3: Use Messages from Compiled Message Catalogs

The classes and properties files generated by `i18ngen` and `l10ngen` provide the interface for sending messages to the WebLogic Server log. Within the classes, each log message is represented by a method that your application calls.

To use messages from compiled message catalogs:

1. In the class files for your application, import the `Logger` classes that you compiled in Step 2: Compile Message Catalogs.

To verify the package name, open the message catalog XML file in a text editor and determine the value of the `i18n_package` attribute. For example, the following segment of the message catalog in Listing 2-1 indicates the package name:

`<message_catalog
i18n_package="com.xyz.msgcat"`

To import the corresponding class, add the following line:

`import com.xyz.msgcat.MyMessagesLogger;`

2. Call the method that is associated with a message name.

Each message in the catalog includes a `method` attribute that specifies the method you call the display the message. For example, the following segment of the message catalog in Listing 2-1 shows the name of the method:

<logmessage
messageid="700000"
datelastchanged="1039193709347"
datehash="-1776477005"
severity="info"
method="startup()"
>

Listing 2-3 illustrates a simple class that calls this `startup` method.

Listing 2-3 Example Class That Uses a Message Catalog

>     import com.xyz.msgcat.MyMessagesLogger;

>     public class MyClass {
>          public static void main (String[] args) {
>          MyMessagesLogger.startup();
>          }
>     }

If the JVM's system properties specify that the current location is Spain, then the message is printed in Spanish.

# Using the NonCatalogLogger APIs

In addition to using the I18N message catalog framework, your application can use the `weblogic.logging.NonCatalogLogger` APIs to send messages to the WebLogic Server log. With `NonCatalogLogger`, instead of calling messages from a catalog, you place the message text directly in your application code. BEA recommends that you do not use this facility as the sole means for logging messages if your application needs to be internationalized.

`NonCatalogLogger` is also intended for use by client code that is running in its own JVM (as opposed to running within a WebLogic Server JVM). A subsequent section in this topic, Writing Messages from a Remote Application, provides more information.

To use `NonCatalogLogger` in an application that runs within the WebLogic Server JVM, add code to your application that does the following:

1. Imports the `weblogic.logging.NonCatalogLogger` interface.
2. Uses the following constructor to instantiate a `NonCatalogLogger` object:

`NonCatalogLogger(java.lang.String` `myApplication``)`

where `myApplication` is a name that you supply to identify messages that your application sends to the WebLogic Server log.

3. Calls any of the `NonCatalogLogger` methods.

Use the following methods to report normal operations:

- `info(java.lang.String msg)`
- `info(java.lang.String msg, java.lang.Throwable t)`

Use the following methods to report a suspicious operation, event, or configuration that does not affect the normal operation of the server/application:

- `warning(java.lang.String msg)`
- `warning(java.lang.String msg, java.lang.Throwable t)`

Use the following methods to report errors that the system/application can handle with no interruption and with limited degradation in service.

- `error(java.lang.String msg)`
- `error(java.lang.String msg, java.lang.Throwable t)`

Use the following methods to provide detailed information about operations or the state of the application. These debug messages are not broadcast as JMX notifications. If you use this severity level, we recommend that you create a "debug mode" for your application. Then, configure your application to output debug messages only when the application is configured to run in the debug mode. For information about using debug messages, refer to Writing Debug Messages.

- `debug(java.lang.String msg)`
- `debug(java.lang.String msg, java.lang.Throwable t)`

All methods that take a `Throwable` argument can print the stack trace in the error log. For information on the `NonCatalogLogger` APIs, refer to the `weblogic.logging.NonCatalogLogger` Javadoc.

Listing 2-4 illustrates a servlet that uses `NonCatalogLogger` APIs to write messages of various severity levels to the WebLogic Server log.

Listing 2-4 Example NonCatalogLogger Messages

>     import java.io.PrintWriter;
>     import java.io.IOException;
>     import javax.servlet.http.HttpServlet;
>     import javax.servlet.http.HttpServletRequest;
>     import javax.servlet.http.HttpServletResponse;
>     import javax.servlet.ServletException;
>     import javax.naming.Context;

>     import weblogic.jndi.Environment;
>     import weblogic.logging.NonCatalogLogger;

>     public class MyServlet extends HttpServlet {

>          public void service (HttpServletRequest request,
>             HttpServletResponse response)
>             throws ServletException, IOException {

>            PrintWriter out = response.getWriter();
>            NonCatalogLogger myLogger = null;

>            try {

>               out.println("Testing NonCatalogLogger. See
>                              WLS Server log for output message.");

>     // Constructing a NonCatalogLogger instance. All messages from this
>     // instance will include a <MyApplication> string.
>               myLogger = new NonCatalogLogger("MyApplication");

>     // Outputting an INFO message to indicate that your application has started.
>               mylogger.info("Application started.");

>     // For the sake of providing an example exception message, the next
>     // lines of code purposefully set an initial context. If you run this
>     // servlet on a server that uses the default port number (7001), the
>     // servlet will throw an exception.
>             Environment env = new Environment();
>             env.setProviderUrl("t3://localhost:8000");

>             Context ctx = env.getInitialContext();

>          }

>         catch (Exception e){
>           out.println("Can't set initial context: " + e.getMessage());

>     // Prints a WARNING message that contains the stack trace.
>          mylogger.warning("Can't establish connections. ", e);

>         }

>        }

>     }

When the servlet illustrated in the previous example runs on a server that specifies a listen port other than `8000`, the following messages are printed to the WebLogic Server log file. Note that the message consists of a series of strings, or fields, surrounded by angle brackets (`< >`).

Listing 2-5 NonCatalogLogger Output

>     ####<Jun 26, 2002 12:04:21 PM EDT> <Info> <MyApplication> <MyHost>
>     <examplesServer> <ExecuteThread: '10' for queue: 'default'> <kernel identity>
>     <> <000000> <Application started.>

>     ####<Jun 26, 2002 12:04:23 PM EDT> <Warning> <MyApplication> <MyHost>
>     <examplesServer> <ExecuteThread: '10' for queue: 'default'> <kernel identity>
>     <> <000000> <Can't establish connections. >

>     javax.naming.CommunicationException.  Root exception is
>     java.net.ConnectException: t3://localhost:8000: Destination unreachable; nested
>     exception is:

>     ...

# Using GenericServlet

The `javax.servlet.GenericServlet` servlet specification provides the following APIs that your servlets can use to write a simple message to the WebLogic Server log:

- `log(``java.lang.String msg``)`
- `log(``java.lang.String msg``,` `java.lang.Throwable` `t``)`

For more information on using these APIs, refer to the J2EE Javadoc for `javax.servlet.GenericServlet` at http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/GenericServlet.html.

# Writing Messages from a Remote Application

If your application runs in a JVM that is separate from a WebLogic Server, it can use message catalogs and `NonCatalogLogger`, but the messages are not written to a WebLogic Server log. Instead, the application's messages are written to the remote JVM's standard out.

If you want the WebLogic logging service to send these messages to a log file that the remote JVM maintains, include the following argument in the command that starts the remote JVM:

`-Dweblogic.log.FileName=``logfilename`

where `logfilename` is the name that you want to use for the remote log file.

If you want a subset of the message catalog and `NonCatalogLogger` messages to go to standard out as well as the remote JVM log file, include the following additional startup arguments:

>     -Dweblogic.StdoutEnabled=true

>     -Dweblogic.StdoutDebugEnabled=boolean

>     -Dweblogic.StdoutSeverityLevel = [64 | 32 | 16 | 8 | 4 | 2 | 1 ]

where `boolean` is either `true` or `false` and the numeric values for `StdoutSeverityLevel` correspond to the following severity levels:

INFO(64) WARNING(32), ERROR(16), NOTICE(8), CRITICAL(4), ALERT(2) and EMERGENCY(1).

## Writing Messages from a Remote JVM to a File

A remote JVM can generate its own set of messages that communicate information about the state of the JVM itself. By default, the JVM sends these messages to standard out. You cannot redirect these messages to the JVM's log file, but you can save them to a separate file. For more information, refer to "Redirecting System.out and System.err to a File" in the Administration Console Online Help.

# Writing Debug Messages

While your application is under development, you might find it useful to create and use messages that provide verbose descriptions of low-level activity within the application. You can use the `DEBUG` severity level to categorize these low-level messages. All `DEBUG` messages that your application generates are sent to the WebLogic Server log file. (Unlike Log4j, which is a third-party logging service that enables you to dynamically exclude log messages based on level of severity, the WebLogic Server log includes all levels of messages that your application generates.)

You also can configure the WebLogic Server to send `DEBUG` messages to standard out. For more information refer to "Specifying Which Messages a Server Sends to Standard Out" in the Administration Console Online Help.

If you use the `DEBUG` severity level, we recommend that you create a "debug mode" for your application. For example, your application can create an object that contains a boolean value. To enable or disable the debug mode, you toggle the value of the boolean. Then, for each `DEBUG` message, you can create a wrapper that outputs the message only if your application's debug mode is enabled.

For example, the following code can produce a debug message:

>     private static boolean debug = Boolean.getBoolean("my.debug.enabled");
>     if (debug) {
>        mylogger.debug("Something debuggy happened");
>     }

You can use this type of wrapper both for messages that use the message catalog framework and that use the `NonCatalogLogger` API.

To enable your application to print this message, you include the following Java option when you start the application's JVM:

`-Dmy.debug.enabled=true`