Writing Messages to the WebLogic Server Log

4 Writing Messages to the WebLogic Server Log

You can facilitate the management of your application by writing log messages to the WebLogic Server log file.

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.
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.
Using ServletContext
The servlet specification provides the log(java.lang.String msg)and log(java.lang.String msg, java.lang.Throwable t) APIs in javax.servlet.ServletContext that your servlets and JSPs can use to write a simple message to the WebLogic Server log.
Configuring Servlet and Resource Adapter Logging
You can configure Web application and resource adapter logging behavior using WebLogic specific deployment descriptors. The logging configuration deployment descriptor elements define similar attributes used to configure server logging through the LogMBean interface, such as the log file name, location, and rotation policy.
Writing Messages from a Client Application
If your application runs in a JVM that is separate from a WebLogic Server instance, it can use message catalogs and NonCatalogLogger, but the messages are not written to the WebLogic Server log. Instead, the application's messages are written to the client JVM's standard out.
Writing Debug Messages
While your application is under development, you can 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.

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.To write log messages using the I18N message catalog framework, complete the tasks described in the following sections.

Parent topic: Writing Messages to the WebLogic Server Log

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 optionally, 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:

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.
Enter the following command: java weblogic.MsgEditor
To create a new catalog, choose File > New Catalog.

See Using the WebLogic Server Message Editor.
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:

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.
Enter the following command: java weblogic.MsgLocalizer
Use the Message Localizer GUI to create locale-specific catalogs.

For basic command line help, type: java weblogic.MsgEditor -help

Parent topic: Using the I18N Message Catalog Framework: Main Steps

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. See Using the WebLogic Server Internationalization Utilities.

To compile the message catalogs, do the following:

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.
Enter the following command:
```
java weblogic.i18ngen -build -d targetdirectory source-files
```
In the preceding command:
- targetdirectory represents 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 represents 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.
If you created locale-specific catalogs in 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, above, 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 weblogic.l10ngen -d targetdirectory source-files
```
  In the preceding command:
  - targetdirectory represents 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 represents 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.
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, see Using the WebLogic Server Internationalization Utilities.

Example: Compiling Message Catalogs

Parent topic: Using the I18N Message Catalog Framework: Main Steps

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.

Example 4-1 shows the contents of the message catalog.

Example 4-1 Sample Message Catalog

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
"http://www.bea.com/servers/wls90/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, shown in Example 4-2.

Example 4-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/wls90/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>

Parent topic: Compile Message Catalogs

Compiling the 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

Parent topic: Example: Compiling Message Catalogs

Creating Properties Files

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

Add the i18n classes to the command prompt's classpath by entering the following:
set CLASSPATH=%CLASSPATH%;c:\MessageOutput

Enter the following command:

java weblogic.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

Parent topic: Example: Compiling Message Catalogs

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:

In the class files for your application, import the Logger classes that you compiled in 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 Example 4-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;
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 to display the message. For example, the following segment of the message catalog in Example 4-1 shows the name of the method:
```
<logmessage
 messageid="700000"
 datelastchanged="1039193709347"
 datehash="-1776477005"
 severity="info"
 method="startup()"
>
```

The following example illustrates a simple class that calls this startup method.

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.

Parent topic: Using the I18N Message Catalog Framework: Main Steps

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.Oracle 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, Writing Messages from a Client 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:

Imports the weblogic.logging.NonCatalogLogger interface.
Uses the following constructor to instantiate a NonCatalogLogger object:
```
NonCatalogLogger(java.lang.String myApplication)
```
In the preceding syntax, myApplication represents a name that you supply to identify messages that your application sends to the WebLogic Server log.
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 or 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 or 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, see 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 server log. For information on the NonCatalogLogger APIs, see the weblogic.logging.NonCatalogLogger Javadoc.

The following example illustrates a servlet that uses NonCatalogLogger APIs to write messages of various severity levels to the WebLogic Server log.

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 (< >).

####<May 27, 2004 8:45:42 AM EDT> <Error> <MySubsystem> <myhost> <adminServer>
 <ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <system> 
<> <> <1085661942864> <BEA-000000> <Test NonCatalogLogger message
java.lang.Exception: Test NonCatalogLogger message
...
>

Parent topic: Writing Messages to the WebLogic Server Log

Using ServletContext

The servlet specification provides the log(java.lang.String msg)and log(java.lang.String msg, java.lang.Throwable t) APIs in javax.servlet.ServletContext that your servlets and JSPs can use to write a simple message to the WebLogic Server log.For more information on using these APIs, see the Javadoc for the javax.servlet.ServletContext interface at http://docs.oracle.com/cd/E17802_01/products/products/servlet/2.3/javadoc/javax/servlet/ServletContext.html.

The following example illustrates JSP logging using the ServletContext:

<%@ page language="java" %>
<!DOCTYPE HTML PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<title>INDEX</title>
</head>
<body bgcolor="#FFFFFF">
<%
config.getServletContext().log("Invoked ServletContext.log() From a JSP");
out.write("Request param arg0 = " + request.getParameter("arg0"));
%>
</body>
</html>

Parent topic: Writing Messages to the WebLogic Server Log

Configuring Servlet and Resource Adapter Logging

You can configure Web application and resource adapter logging behavior using WebLogic specific deployment descriptors. The logging configuration deployment descriptor elements define similar attributes used to configure server logging through the LogMBean interface, such as the log file name, location, and rotation policy.

When configured, application events are directed to a Web application specific log file. When the deployment descriptor does not include any logging configuration information, the default behavior is to write these events in the server log file.

Similarly, WebLogic logging services are provided to Jakarta EE resource adapters for ManagedConnectionFactory scoped logging. You configure the log file name, location, and rotation policy for resource adapter logs through the weblogic-ra.xml deployment descriptor. See weblogic-ra.xml Schema in Developing Resource Adapters for Oracle WebLogic Server.

The following example illustrates a snippet of the deployment descriptor for configuring the logging behavior of Web application and resource adapter logging. The elements of logging correspond to attribute definitions on the LogMBean interface. All the LogMBean attributes are not listed in this example. Logging configuration is defined in the WEB-INF/weblogic.xml file for Web applications and in the META-INF/weblogic-ra.xml file for resource adapters.

<!DOCTYPE weblogic-web-app PUBLIC "//DTD Web Application 9.0//EN" 
"http://www.bea.com/servers/wls90/dtd/weblogic90-web-jar.dtd">
<weblogic-web-app>
  <logging>
    <log-filename>d:\tmp\mywebapp.log</log-filename>
    <rotation-type>bySize</rotation-type>
    <number-of-files-limited>true</number-of-files-limited>
    <file-count>3</file-count>
    <file-size-limit>50</file-size-limit>
    <rotate-log-on-startup>true</rotate-log-on-startup>
    <log-file-rotation-dir>config/MedRecDomain/WebApp</log-file-rotation-dir>
  </logging>
</weblogic-web-app>
<weblogic-connector xmlns="http://www.bea.com/ns/weblogic/90">
  <jndi-name>eis/900BlackBoxNoTxConnector</jndi-name>
  <outbound-resource-adapter>
    <connection-definition-group> 
      <connection-factory-interface>javax.sql.DataSource</connection-factory-interface>
      <connection-instance>
        <jndi-name>eis/900BlackBoxNoTxConnectorJNDINAME</jndi-name>
        <connection-properties>
          <pool-params>
            <initial-capacity>5</initial-capacity>
            <max-capacity>10</max-capacity>
            <capacity-increment>1</capacity-increment>
            <shrinking-enabled>true</shrinking-enabled>
            <shrink-frequency-seconds>60</shrink-frequency-seconds>
            <highest-num-waiters>1</highest-num-waiters>
            <highest-num-unavailable>3</highest-num-unavailable>
            <connection-reserve-timeout-seconds>11</connection-reserve-timeout-seconds>
          </pool-params>
          <logging>
            <log-filename>900BlackBoxNoTxOne.log</log-filename>
            <logging-enabled>true</logging-enabled>
            <rotation-type>bySize</rotation-type>
            <number-of-files-limited>true</number-of-files-limited>
            <file-count>3</file-count>
            <file-size-limit>100</file-size-limit>
            <rotate-log-on-startup>true</rotate-log-on-startup>
            <log-file-rotation-dir>c:/mylogs</log-file-rotation-dir>
            <rotation-time>3600</rotation-time>
            <file-time-span>7200</file-time-span>
          </logging>
          <properties>
            <property>
              <name>ConnectionURL</name>
              <value>jdbc:oracle:thin:@bcpdb:1531:bay920</value>
            </property>
            <property>
              <name>unique_ra_id</name>
              <value>blackbox-notx.oracle.810</value>
            </property>
          </properties>
        </connection-properties>
      </connection-instance>
    </connection-definition-group>
  </outbound-resource-adapter>
</weblogic-connector>

Parent topic: Writing Messages to the WebLogic Server Log

Writing Messages from a Client Application

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

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

-Dweblogic.log.FileName=logfilename

In the preceding argument, logfilename represents 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 argument:

-Dweblogic.log.StdoutSeverityLevel=String

In the preceding argument, valid values for StdoutSeverityLevel are Debug, Info, Warning, Error, Notice, Critical, Alert, Emergency, and Off.

For a description of the supported severity levels, see weblogic.logging.Severities in Java API Reference for Oracle WebLogic Server.

Parent topic: Writing Messages to the WebLogic Server Log

Writing Debug Messages

While your application is under development, you can 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 all WebLogic Server logging destinations, depending on the configured minimum threshold severity level.

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 DEBUG 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

Parent topic: Writing Messages to the WebLogic Server Log