Package com.plumtree.remote.logging

Provides a public interface that can send messages to the ALI Logging Toolkit (See the Usage Example in the package description or Logging Example).

See:
Description

Interface Summary

ILogger

Defines the interface for logger instances, including logging methods and methods to test if various log levels are enabled.

Class Summary

LogFactory

The LogFactory is the starting point for the IDK Logging API, and offers static methods to configure logging, query configuration properties, and obtain ILogger instances.

Package com.plumtree.remote.logging Description

Provides a public interface that can send messages to the ALI Logging Toolkit (See the Usage Example in the package description or Logging Example). This console application demonstrates initialization and use of logging via this package. An ALI log receiver such as ALI Logging Spy is also needed to view the resulting log messages; see the section on Receiving and Viewing Log Messages.

Recommendations for Configuration

When using the IDK in a web application context, we recommend configuring the logging framework via Web.config (Microsoft IIS) or web.xml (Java servlet containers). The web application configuration files shipped with the IDK contain annotated examples of how to configure logging.

When outside a web application context, we recommend declaring a single log management class within the project that will initialize the LogFactory (possibly as part of static initialization). This instance will provide instances of ILogger and possibly define a set of known component names for the application. This technique will help to avoid multiple initializations.

Logging Application Name

This name is set during initialization of the LogFactory or configured in the web configuration file. The logging application name is used as a shared identifier which allows log receivers to pick up messages from the logging application. All crawler, authentication, profile or search web services running in the same IDK web application instance will have the same logging application name.

Component Name

All ILogger instances require a component name to identify the general context for a set of log messages. A component is a conceptual unit within an application. A small application may have only a single named component. It is reasonable to define component names as string constants that are localized in a log management class.

Recommendations for Efficiency

The ALI logging framework is designed to suppress logging if there are no listening applications. For better performance, logging applications should use the ILogger interface to find out if there any listening applications before composing complex log messages. For example:

    	if (logger.isDebugEnabled()) {
    		// compose a diagnostic message
    		logger.debug( complex diagnostic message...);
    	}
    	

Similarly, the ALI logging framework will avoid internally composing formatted log messages when there are no listeners. For this reason, ILogger has numerous method overloads that allow passing a format string and various Object and numeric arguments. The arguments will only be processed and composed into a log message if there is an active listener for that log level. This helps avoid unnecessary string concatenation and makes for cleaner code.

Prefer this:

    		logger.debug("An error occurred when {0} attempted to access {1} (context {2})",
                             user, resource, context);
    	

to this:

    		logger.debug(
    		    "An error occurred when " + user +
    		    " attempted to access " + resource +
    		    " (context " + context +
    		    ")");
    	

Usage Example

package com.plumtree.remote.logging.test;

import com.plumtree.remote.logging.*;

/**
 * Provides an example of using the IDK
 * logging API.
 */
public class LoggingExampleLogUser {

	private static ILogger getLogger() {
		return LoggingExampleLogHolder.getLogger(LoggingExampleLogUser.class);
	}

	public static Object createObjectFor(String customerName) {
		ILogger logger = getLogger();
		logger.functionBegin("createObjectFor");
		Object retValue = new Object();
		logger.info("Created new object for customer {0}.", customerName);
		if (logger.isDebugEnabled()) {
			logger.debug("Details of new object: {0}, runtime type {1}, customer {2}", retValue.toString(), retValue.getClass().getName(), customerName);
		}
		logger.functionEnd("createObjectFor");
		return retValue;
	}

	public static void main(String[] arguments) {
		createObjectFor("Plumtree");
		for (int i = 0; i < arguments.length; i++) {
			createObjectFor(arguments[i]);
		}
	}
}

package com.plumtree.remote.logging.test;

import com.plumtree.remote.logging.*;

public class LoggingExampleLogHolder {

	private static boolean logToNetworkWhenTrue = true;
	static {
		LogFactory.initialize("ExampleName", logToNetworkWhenTrue);
	}

	public static ILogger getLogger(Class loggingClass) {
		return LogFactory.getLogger("LoggingExample", loggingClass);
	}

}

    

Receiving and Viewing Log Messages

To receive and view log messages generated by the ALI logging framework, it is necessary to install the ALI Logging Toolkit and use one of its log receivers, such as ALI Logging Spy or the ALI Logger. The receiver must be configured with a logging application name matching the sender. For more information, see the Configuring IDK Logging Options in the online developer documentation.

Since:

IDK 5.2