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/wls710/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/wls710/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. We do not recommended using 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: 

...

Table 2-1 describes all of the fields that NonCatalogLogger log messages can contain.

Table 2-1 NonCatalogLogger Log Message Format

Field	Description
Localized Timestamp	Date and time when message originated, including the year, month, day of month, hours, minutes and seconds. For example, <Jun 26, 2002 12:04:21 PM EDT>.
Severity	One of the following severity values, which corresponds to the type of method that you used to generate the message: Info, Warning, Error, Debug
Subsystem	Indicates the source of the message. This is the string that you supply for the NonCatalogLogger constructor.
Server Name Machine Name Thread ID	Identify the origins of the message. Log messages that are generated within a client JVM client do not include these fields. For example, if your application runs in a client JVM and it uses the WebLogic logging services, the messages that it generates and sends to the WebLogic Server log files will not include these fields.
User Id	User on behalf of whom the system was executing when the error was reported. Log messages that are generated within a client JVM client do not include this field.
TransactionId	Present only for messages logged within the context of a transaction.
Message Id	A six-digit identifier for the message. The message ID for NonCatalogLogger messages is always 000000.
Message text	The text that you supply for the NonCatalogLogger method.
ExceptionName	If the message is logging an Exception, this field contains the name of the Exception.

 

---

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.

JSPs do not extend from GenericServlet and cannot use these APIs. If you want your JSPs to send messages to a log file, consider using the I18N message catalog services or NonCatalogLogger APIs.

 

---

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 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. For example, you can configure a JVM to generate messages about garbage collection. 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 JVM Messages 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