Log4j 1.1b7

Package org.apache.log4j.examples.appserver

This package extends log4j by adding extra logging attributes useful in distributed application server environments.

See:
          Description

Class Summary
AppServerCategory Extends Category by adding four text attributes relevant to applications run in application servers.
AppServerCategoryFactory Creates correctly populated instances of AppServerCategory.
AppServerLoggingEvent Represents logging events for application servers.
AppServerPatternLayout Extends PatternLayout to create subclass instances of AppServerPatternParser for parsing pattern strings.
AppServerPatternParser Extend PatternParser to recognize additional conversion characters suitable for use by application servers.
 

Package org.apache.log4j.examples.appserver Description

This package extends log4j by adding extra logging attributes useful in distributed application server environments. Specifically, it adds the following text information to each logging event.

  1. host (h) - the machine from which the message was logged
  2. server (s) - the server process from which the message was logged
  3. component (b) - the component from which the message was logged
  4. version (v) - a version string for the code from which the message was logged

Usage

Using this package in your programs differs little from using the corresponding classes in org.apache.log4j. At log4j initialization you create an instance of AppServerCategoryFactory populated with the attributes you desire. You can either supply these in the factory's constructor or set them afterwards. The host name is determined automatically using the java.net API and can be reset manually. It is ok to set any of the attributes to null.

After creating an appropriate AppServerCategoryFactory instance, set a static reference to it using the AppServerCategory.setFactory method. This sets everything up for acquiring an AppServerCategory reference whenever you need one.

import org.apache.log4j.spi.CategoryFactory;
import org.apache.log4j.Category;
import org.apache.log4j.examples.appserver.AppServerCategoryFactory;
import org.apache.log4j.examples.appserver.AppServerCategory;

...

org.apache.log4j.BasicConfigurator.configure();
CategoryFactory factory = new AppServerCategoryFactory("MyServer", null, null);
AppServerCategory.setFactory( factory );

...

Category cat = AppServerCategory.getInstance("my.category");
cat.info("Entry");

A Note on Configurators

Using AppServerCategory with PropertyConfigurator or DOMConfigurator requires a note of caution. By default these configurators do not know that Category has been subclassed. Upon constructing a configuration from a set of properties, it will construct Category instances rather than instances of the desired subclass. There at least two ways to work around this.

By instanciating any anticipated AppServerCategory instances before calling a configurator, the configurator will use the instances you create rather than trying to (incorrectly) create its own. The consequence is that you can not always predict which categories will be created. Their dynamic nature is the reason for externalizing their configuration in the first place. This drawback is limited to category names explicitly defined in the configuration.

Another work-around is to take advantage of a recently added feature allowing you to specify the type of factory used for creating Category instances to a DOMConfigurator or a PropertyConfigurator. The consequence is that only the default constructor is used to create the factory instance. For AppServerCategoryFactory, this will only populate the hostname attribute. The server name, component name and version name will be blank. For many cases this may be satisfactory.

Compatibility

The log4j package naming conventions used in this package are compatible with log4j version 1.0.

Try It Yourself

While the attributes extended in this package are oriented toward application servers, there is nothing application server specific in the code structure. This package may be used as a template for specifying your own collection of attributes or extended to include additional attributes. A log4j extension manual accompanies this package that will take you step by step through the process.


Log4j 1.1b7

Please notify me about new log4j releases.