Generating Log Messages

Clearly, it becomes easier to manage your application setup if its log messages can be found in the same places as the log messages generated by WebLogic's subsystems. This is especially true when your applications operate within a distributed environment. There are several ways to generate log messages and integrate them automatically with WebLogic's logging architecture:

• Use WebLogic's tools to build custom log message catalogs and their associated Java APIs. Clients can conveniently invoke these various log methods exposed by these interfaces to generate log messages. These message catalogs can easily be internationalized.
• Use WebLogic's noncatalog logger to generate log messages. This logger doesn't rely on a message catalog, and hence cannot be internationalized. However, it does allow you to publish log messages in a straightforward fashion. When localized log messages aren't a requirement for your applications, the noncatalog logger makes it quick and easy to use WebLogic's logging framework.
• Use one of the log( ) methods available to an HTTP servlet.

We will also see how you can use WebLogic's catalog and noncatalog logging from a remote Java client. In this case, the log messages are not transmitted to the server's end but are simply logged to a local file and/or the console window.

21.3.1 Log Message Catalogs

WebLogic supports two types of message catalogs: simple text and log message catalogs. Simple text catalogs are collections of internationalized text messages, and their use in WebLogic's environment is not very different from the use of standard Java for outputting internationalized text. For this reason, we will not consider them any further.

Log message catalogs are collections of log messages, instances of which will be recorded in the log files. Each of these catalog types supports locale-specific text versions, thus allowing your messages to be presented in different languages when WebLogic is run under different locales. WebLogic also provides tools that support automatic generation of Java classes and methods that represent the log messages. By invoking these Java classes, you automatically generate the appropriate log messages while utilizing the underlying logging framework.

21.3.1.1 Creating log message catalogs

Message catalogs are written using two types of XML documents. The top-level, default catalog that describes the various log messages and method names must conform to the msgcat.dtd DTD. If you are going to supply localized variants, these must conform to the l10n_msgcat.dtd DTD. These DTDs can be found in the samples directory in your WebLogic installation, WL_HOMEsamplesserverexamplessrcexamplesi18nmsgcat.

The top-level catalog should contain the definitions of all the log messages that you would like to make available. Each message has a unique ID, a message body containing the text that should be generated, a subsystem name, a severity level (debug, info, warning, or error), and a method name. WebLogic's logging tools use the method names to generate Java methods that you then can use to send instances of the message to the log. These methods can take arguments, allowing you to insert dynamic text into the log message. Messages also can contain other text that will be output when the message is logged. The subsystem name is just a convenient way of grouping related messages together, making it easier for the reader to determine who/what generated the log message for instance, the default log messages sent to the console window of a WebLogic instance include , , , etc. before the actual message.

The easiest way to create a message catalog is to use WebLogic's Message Editor. This GUI-based tool lets you create a top-level catalog, and then it automatically generates the XML representation for you. You can launch the Message Editor by running the following command:

 java weblogic.MsgEditor

Before creating a message catalog, the directory in which you want to store the catalog must hold the DTD files that the Message Editor uses. These can be copied from the samples directory referenced earlier.

Let's now look at an example that illustrates all the tooling and formats used. Here, we'll create a new log message catalog file called ocat.xml. When creating a new catalog file, you have to supply package names for the code that will be generated from the catalog files. We've chosen the com.oreilly.wlguide.i18n package to provide all the internationalization support, and the com.oreilly.wlguide.i10n package to provide the localization support. You also must choose a subsystem name. We've chosen OREILLY. Using the tool, you now can create a number of messages. As an example, we created a message with a method name of testing(String msg) and message body of I am hungry: {0}. The tool then will generate an XML representation of the log message similar to this:

 
 I am hungry: {0}
 
 
 
 
 
 
 

As illustrated in the preceding excerpt, the method can take a number of arguments, thereby allowing you to embed text into the log message dynamically. You may specify up to 10 arguments, and these can be referenced within the message body using {0} {1} ... {9}. Besides string-valued parameters, WebLogic also supports numeric parameters using the {n,number} syntax and dates using the {n,date} syntax.

The master catalog of log messages can be created using any language of your choice. Once you've created the master catalog, you can create other locale-specific translations of these messages. Each translation should be placed in an identically named file within a subdirectory labeled by the two-letter language code. So, for instance, if we were to create a Dutch translation of the earlier message, it has to be placed under the nl subdirectory. If you need to support multiple variants for a locale for instance, the U.S. English variant you should place the variant under the language directory. Thus, an American English translation for the same message catalog would be placed under the en/US subdirectory. The XML representation for the localized translations must include an entry for each message, along with its translation. Here are the contents of the nl/ocat.xml catalog file, which specifies the Dutch translation for the original messages:

 
 
 Ik heb honger: {0}
 
 
 
 
 

WebLogic provides two utilities that create Java support for the messages. The weblogic.i18ngen utility should be used to generate the Java classes that provide internationalization support, while the weblogic.l10ngen utility should be used to generate Java classes that offer localization support. Both utilities accept two command-line arguments: the name of the root catalog file and the location of the directory into which the output classes should be placed. Note that the localization tool automatically scours subdirectories. We used the following commands to generate the Java classes that provide necessary support for i18n and l10n:

java weblogic.i18ngen -compile -i18n -l10n -keepgenerated -d x:out ocat.xml
java weblogic.l10ngen -d x:out -verbose .ocat.xml
cd x:out
jar cvf x:externalJARsmylogging.jar .

To make the files available to WebLogic, you need to include the support classes within WebLogic's CLASSPATH. In the example, we created a JAR that packages all the output Java classes and added the JAR's location to WebLogic's CLASSPATH used during startup.

Among other files, WebLogic generates resource bundles representing the localizations, and a class that contains static methods for each of the messages that you defined. The name of the generated Logger class is given by the name of the message catalog with a Logger suffix in our case, com.oreilly.wlguide.i18n.ocatLogger.

21.3.1.2 Generating log messages

Now that WebLogic is aware of the generated support files for generating your own log messages, you can instrument your applications to send these messages. This can be accomplished by invoking the appropriate methods defined for the log messages. For instance, in order to trigger our example log message, you must invoke the following static method:

com.oreilly.wlguide.i18n.ocatLogger.testing("123");

This will generate a log message on the local server. This simple message call actually invokes the underlying distributed logging facilities, so depending on your log filter settings the message also may be forwarded to the domain-wide log. In our example, the following log message is fired:

<01-Feb-03 17:19:49 GMT>   <500000> 

If you run WebLogic under the Dutch locale, the following locale-specific log message is emitted instead:

<01-Feb-03 17:24:19 GMT>   <500000> 

21.3.2 Noncatalog Logging

Noncatalog logging is, as its name implies, logging without a catalog. Because you don't use a log message catalog, you lose all internationalization support. In addition, your code must explicitly supply the text that needs to be logged. On the other hand, a NonCatalogLogger object provides an easy interface for using WebLogic's underlying logging framework. The following example shows how a client (perhaps running within WebLogic) can log messages without the aid of a message catalog:

weblogic.logging.NonCatalogLogger wnc = 
 new weblogic.logging.NonCatalogLogger("News");
wnc.info("News just in");
wnc.warning("Alien's have landed");
wnc.alert("I'm here, come quickly");
wnc.emergency("Help, I'm trapped")
wnc.critical("Save yourselves!");
wnc.debug("De-bug me man, don't just stand there");

The NonCatalogLogger constructor takes a string argument that indicates the name of the subsystem that will be used to identify subsequent log messages it generates. The preceding code will result in the following output in your log file, assuming you've not configured any log level or handlers for the server's Logger:

<11-Apr-2003 17:17:07 o'clock BST>   <000000> 
<11-Apr-2003 17:17:07 o'clock BST>   <000000> 
<11-Apr-2003 17:17:07 o'clock BST>   <000000> 
<11-Apr-2003 17:17:07 o'clock BST>   <000000> 
<11-Apr-2003 17:17:07 o'clock BST>   <000000> 
<11-Apr-2003 17:17:07 o'clock BST>   <000000> 

The various log methods also can take an optional Throwable argument, thereby allowing you to include additional information about the error.

21.3.3 Servlet Logging

Because all HTTP servlets indirectly extend the javax.servlet.GenericServlet class, a servlet can avail of the following log methods:

/** Generate a log message within WebLogic's logs */
log(String message);
/** Use the Throwable object to obtain additional
 information on the exception that generated the log message */
log(String message, Throwable t);

A servlet may use either of these methods to output log messages to WebLogic's server logs.

Even though your code is guaranteed to remain portable, these methods are not particularly flexible. For example, you cannot assign a severity level for the log message, or even override the subsystem that generated the log message. In addition, JSPs are unable to use these methods because their implementation class doesn't extend the GenericServlet class. For this reason, we recommend that you create your own catalog logger or use WebLogic's noncatalog logger in order to benefit from WebLogic's logging capabilities.

21.3.4 Client Application Logging

Client applications can also use the noncatalog and catalog logging features of WebLogic. The following startup arguments control the behavior of the logging:

weblogic.log.FileName

Use this argument to specify a filename to which the log messages should be written.

weblogic.StdoutEnabled

Set this argument to true if you want a subset of the log messages to be written to stdout as well as the log file.

weblogic.StdoutDebugEnabled

Set this argument to true if you want debug messages written to stdout.

weblogic.StdoutSeverityLevel

Set this argument to the desired severity level. This can be set to either 64 for info, 32 for warning, 16 for error, 8 for notice, 4 for critical, 2 for alert, or 1 for emergency.

Here is an example:

java -Dweblogic.log.FileName=out.log -Dweblogic.StdoutEnabled=true
 -Dweblogic.StdoutSeverityLevel=16 alienClient

Chapter 22 SNMP