Package com.plumtree.remote.logging

Provides a public interface which can send messages to the Plumtree 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 EDK Logging API, it offers static methods to configure logging, query configuration properties, and obtain ILogger instances.

Package com.plumtree.remote.logging Description

Provides a public interface which can send messages to the Plumtree 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. A Plumtree log receiver such as Plumtree Logging Spy is also needed to view the resulting log messages; see the package description section on Receiving and Viewing Log Messages.

Recommendations for Configuration

When using the EDK 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 EDK contain annotated examples of how to configure logging.

When outside a web application context we recommend that a single log management class be declared 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 Plumtree log receivers to pick up messages from the logging application. All crawler, authentication, profile or search web services running in the same EDK 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 Plumtree 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 Plumtree logging framework will avoid internally composing formatted log messages when there are no listeners. For this reason, ILogger has numerous method overloads which 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 Plumtree EDK
 * 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 Plumtree logging framework, it is necessary to install the Plumtree Logging Toolkit and use one of its log receivers such as Plumtree Logging Spy or the Plumtree Logger. The receiver must be configured with a logging application name matching the sender. For more information, see the Plumtree Developer Center.

Related Documentation

For examples, developer discussions and additional documentation, see Plumtree Developer Center

Since:

EDK 5.2