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 a local language.

To create and edit a properly formatted message catalog, use the WebLogic Message Editor utility, which is a graphical user interface that is installed with WebLogic Server.

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 more 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.

When you save your work in the Message Editor, WebLogic Server creates the XML files that comprise your message catalogs. Listing 2-1 provides a sample message catalog that defines three messages. This sample is installed along with WebLogic Server examples in the following location:
WL_HOME\samples\server\src\examples\i18n\msgcat\UserServerSCExample.xml.

Listing 2-1 Example Message Catalog

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
"http://www.bea.com/servers/wls700/msgcat.dtd">

<message_catalog
    i18n_package="examples.i18n.logging.startup"
    l10n_package="examples.i18n.logging.startup"
    subsystem="UserStartupClass"
    version="1.0"
    baseid="909050"
    endid="909059"
    >

<logmessage
    messageid="909050"
    datelastchanged="973906351125"
    datehash="-854388901"
    severity="info"
    method="logInitialMessage(int money 0)"
    stacktrace="false"
    >

	<messagebody>
	This message displays a number as currency:
	{0,number,currency}.
	</messagebody>

	<messagedetail>
	Just an example.
	</messagedetail>

	<cause>
	</cause>

	<action>
	</action>

</logmessage>

<logmessage
    messageid="909051"
    datelastchanged="973906462765"
    datehash="-1800319350"
    severity="warning"
    method="logStringAndPrevCallCount(String str0, int num1)"
    stacktrace="false"
    >

      <messagebody>
      This message displays the string "{0}". There
      {1,choice,0#were no previous calls|1#was one previous
      call|2#were {1,number} previous calls} to the logger method
      for this message.
     </messagebody>

	<messagedetail>
	</messagedetail>

	<cause>
	</cause>

	<action>
	</action>

</logmessage>

<logmessage
    messageid="909052"
    datelastchanged="973906532006"
    datehash="-160371672"
    severity="error"
    method="logFinalMessage()"
    stacktrace="false"
    >

	<messagebody>
	This is not really an error, the example has finished
	normally.
	</messagebody>

	<messagedetail>
	</messagedetail>

	<cause>
	</cause>

	<action>
	</action>

</logmessage>

</message_catalog>

Step 2: Compile Message Catalogs

After you create message catalogs, you use the following utilities to generate Java class files from the XML files:

• The i18ngen utility validates message catalogs and generates Java files that you compile and locate in your classpath. Each Java class contains methods that correspond to the messages in the XML file.

• The l10ngen utility validates locale-specific catalogs and creates additional properties files for the different locales defined by the catalogs.

To generate and compile the Java class files, do the following:

1. 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 any of the following commands:

   • java weblogic.i18ngen [options] files

   • java weblogic.i18ngen.tools.l10ngen [options] filelist

   The commands output Java source files. The package name is specified by the i18n_package and l10n_package attributes in the XML input files.

3. Compile the source files and add them to your classpath.

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

Step 3: Use Messages from Compiled Message Catalogs

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

For example, for the message catalog named UserServerSCExample.xml (see Listing 2-1), the i18ngen utility generates a class named examples.i18n.logging.startup.UserServerSCExampleLogger. If you want your application to write the logFinalMessage message, you call the UserServerSCExampleLogger.logFinalMessage() method. Listing 2-2 illustrates a JSP that calls this method.

Listing 2-2 Example JSP That Uses a Message Catalog

<html>
Order complete. Thanks for your order!

<%@ page import="examples.i18n.logging.message.UserServerSVExampleLogger" %>

<%
   UserServerSVExampleLogger.logFinalMessage();
%>

</body>
</html>

 

---

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 forwarded to the domain log. If you use this severity level, we recommend that you create a "debug mode" for your application. Then, configure your application to output debug mesages 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-3 illustrates a servlet that uses NonCatalogLogger APIs to write messages of various severity levels to the WebLogic Server log.

Listing 2-3 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-4 NonCatalogLogger Output

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

####<Jun 26, 2002 12:04:23 PM EDT> <Warning> <MyApplication> <peach> <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.
MachineName	The name of the computer that hosts the JVM on which your application runs.
ServerName	The name of the WebLogic Server instance on which your application is running.
ThreadId	Indicates the execute thread that the current process is using. You can fine-tune an application's access to execute threads (and thereby optimize or throttle its performance) by using multiple execute queues in WebLogic Server. For more information, refer to Using Execute Queues to Control Thread Usage in the BEA WebLogic Server Performance and Tuning guide.
User Id	User on behalf of whom the system was executing when the error was reported.
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 System.out and System.err to a File" in the WebLogic Server Administration Guide.

 

---

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 General Log File Settings 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:

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.