Log4j 1.1.3

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

Configuration

Using this package in your programs differs little from using Category. In this initial version, only property file initialization is supported.

Automatic Configuration

The following properties serve to configure the AppServerCategoryFactory.

PropertyDescription
log4j.categoryFactory The CategoryFactory implementation to use.
log4j.factory.server The value assigned to the server attribute.
log4j.factory.component The value assigned to the component attribute.
log4j.factory.version The value assigned to the version attribute.
log4j.factory.messageBundle The name of bundle file to populate the message ResourceBundle. Because the ResourceBundle.getBundle method is used to load the message file, the ".properties" extension should not be included as part of this property.

A sample configuration might look like this.

log4j.categoryFactory=org.apache.log4j.examples.appserver.AppServerCategoryFactory
log4j.factory.server=TestServer
log4j.factory.component=TestComponent
log4j.factory.version=SomeVersion
log4j.factory.messageBundle=app_messages

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.examples.appserver.AppServerPatternLayout
log4j.appender.stdout.layout.ConversionPattern=[%h:%s:%b:%v] %m%n

The only change needed to your source file is to invoke the AppServerCategory.getInstance(String) instead of the usual Category.getInstance(String) to acquire an implementation of Category.

Manual Configuration

You can manually invoke the configuration much like the static initializer would have.

import org.apache.log4j.Category;
import org.apache.log4j.PropertyConfigurator;
import org.apache.log4j.examples.appserver.AppServerCategory;
...
PropertyConfigurator.configure("test.properties");
Category cat = AppServerCategory.getInstance("some.cat");
...
cat.info("This is an INFO statement.");

Very Manual Configuration

If you want complete control over the configuration process, you can leave PropertyConfigurator out of it all together. This could be useful if you want only some of your categories to be AppServerCategory instances.

Simply create an AppServerCategoryFactory instance. The constructor automatically installs the new instance as the default factory for future calls to AppServerCategory.getInstance(String).

import org.apache.log4j.Category;
import org.apache.log4j.examples.appserver.AppServerCategoryFactory;
import org.apache.log4j.examples.appserver.AppServerCategory;
...
org.apache.log4j.BasicConfigurator.configure();
new AppServerCategoryFactory("MyServer", null, null);
...
Category cat = AppServerCategory.getInstance("my.category");
cat.info("Entry"); 

A Note on Configurators

Using the very manual approach to configure AppServerCategory with PropertyConfigurator or DOMConfigurator requires a note of caution. Since the very manual method does not provide the log4j.categoryFactory property, 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. One way to around this is decribed below.

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.

Remote Usage

Including attributes such as hostname and server are only relevant if the logging entries somehow end up on other hosts or mixed with those of other servers. Remote logging in a distributed application environment allows the logging of various remote components to be collected together in a single location. The basic building blocks for remote usage are the SimpleSocketServer used in conjunction with the SocketAppender.

The configuration of SimpleSocketServer receiving serialized AppServerLoggingEvent classes is much the same as with the standard LoggingEvent class. The main difference to keep in mind is that the layout implementation should be org.apache.log4j.examples.appserver.AppServerPatternLayout. This will allow for the interpretation of %h, %s, %b and %v symbols.

Try It Yourself

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 distribution that will take you step by step through the extension process.


Log4j 1.1.3

Please notify me about new log4j releases.