com.entrust.toolkit.tracing

Class TraceLogFactory

java.lang.Object

com.entrust.toolkit.tracing.TraceLogFactory

public final class TraceLogFactory
extends java.lang.Object

A factory class for creating TraceLog instances. Tracing in the Toolkit is done via this class and TraceLog instances. The trace logging capabilities provided by this class are not intended for use outside the Toolkit, although applications are free to customize the way trace is logged. Applications requiring logging would be much better served by full-fledged logging capabilities such as those provided by Java 1.4's java.util.logging package or the Apache log4j project.

When requesting a TraceLog instance with the getTraceLogInstance method, the following steps are executed:

1. Check if a logger has already been created for the given name. If so, return it.
2. Check if a logger has been defined for the package within which the class resides. If so, return it.
3. Check to see the enabled trace log level for the given class or package name. This is retrieved from the system property made up of the class name with ".trace" appended. The trace level is derived from the value of this property as follows:
   1. If the value is "1", "BASIC", or "TRACE", the level is BASIC
   2. If the value is "2", "DEBUG", or "FINE", the level is FINE
   3. If the value is "3" or "FINER", the level is FINER
   4. If the value is "4" or "FINEST", the level is FINEST
   5. If the value is an integer bigger than 4, the level is FINEST
   6. For any other value, the level is NONE and tracing is disabled.
   For example, to enable basic tracing for the com.entrust.toolkit.util.HttpDirectoryClient class, set the system property "com.entrust.toolkit.util.HttpDirectoryClient.trace" to "1".
4. Next, the type of TraceLog to create is determined. If the trace level is NONE, a NoOpTraceLog instance is returned. If the logging class has been set with setTraceLogClass(java.lang.Class)then an instance of this class is created and returned. Otherwise, the system property "com.entrust.toolkit.tracing.logclass" is queried. If this defines a sublcass of TraceLog, then an instance of this class is created. If the property is not set or does not define an appropriate class, and the "com.entrust.toolkit.trace.filename" property is not specified, an instance of ConsoleTraceLog is created and returned.
5. If the System property "com.entrust.toolkit.trace.filename=[filename]" is specified the trace logs will be written to the specified filename unless a TraceLog has been defined in the property "com.entrust.toolkit.tracing.logclass".

Note: The Toolkit classes that are capable of tracing generally obtain a static TraceLog instance as part of a static initializer block, and then use the same logger object for the rest of the class's lifetime. This means that to enable tracing for a class, it must be done before the class is loaded.

See Also:

TraceLevel, TraceLog

Method Summary

Modifier and Type	Method and Description
java.lang.String	creationErrors() Returns a String containing details of failures to allocate TraceLog instances.
void	enableTracingForClass(java.lang.String className, java.lang.String loggerName, TraceLevel traceLevel) Explicitly enable trace logging for a given class.
void	enableTracingForClass(java.lang.String className, TraceLog logger, TraceLevel traceLevel) Explicitly enable trace logging for a given class.
void	enableTracingForPackage(java.lang.String packageName, java.lang.String loggerName, TraceLevel traceLevel) Explicitly enable trace logging for a given package.
void	enableTracingForPackage(java.lang.String packageName, TraceLog logger, TraceLevel traceLevel) Explicitly enable trace logging for a given package.
static TraceLogFactory	getInstance() Returns an instance of TraceLogFactory
TraceLog	getTraceLogInstance(java.lang.String name, java.lang.String loggerName) Get a TraceLog instance for a given class or package name.
void	reset() Reset this factory to its initial state.
void	setTraceLogClass(java.lang.Class traceLogClass) Set the class that will be used as the default for all future TraceLog instances returned by this factory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static TraceLogFactory getInstance()

Returns an instance of TraceLogFactory

Returns:

an instance of TraceLogFactory

enableTracingForClass

public void enableTracingForClass(java.lang.String className,
                                  java.lang.String loggerName,
                                  TraceLevel traceLevel)

Explicitly enable trace logging for a given class. This will create a default logger for the class.

Parameters:

className - the fully qualified name of class for which to enable trace logging.

loggerName - the name of the logger that will be created.

traceLevel - the finest level at which to log trace information for the class.

enableTracingForClass

public void enableTracingForClass(java.lang.String className,
                                  TraceLog logger,
                                  TraceLevel traceLevel)

Explicitly enable trace logging for a given class.

Parameters:

className - the fully qualified name of class for which to enable trace logging.

logger - the class that trace log messages will be sent to.

traceLevel - the finest level at which to log trace information for the class.

enableTracingForPackage

public void enableTracingForPackage(java.lang.String packageName,
                                    java.lang.String loggerName,
                                    TraceLevel traceLevel)

Explicitly enable trace logging for a given package. Any class in this package that uses trace logging and has not already initialized its tracing will be enabled for tracing with a default logger.

Note that all trace messages for the package will be sent to the same TraceLog object.

Parameters:

packageName - the fully qualified pacakge name of package for which to enable trace logging.

loggerName - the name of the logger that will be created.

traceLevel - the finest level at which to log trace information for the packge.

enableTracingForPackage

public void enableTracingForPackage(java.lang.String packageName,
                                    TraceLog logger,
                                    TraceLevel traceLevel)

Explicitly enable trace logging for a given package. Any class in this package that uses trace logging and has not already initialized tracing will

Note that all trace messages for the package will be sent to logger.

Parameters:

packageName - the fully qualified pacakge name of package for which to enable trace logging.

logger - the class that trace log messages will be sent to.

traceLevel - the finest level at which to log trace information for the package.

getTraceLogInstance

public TraceLog getTraceLogInstance(java.lang.String name,
                                    java.lang.String loggerName)

Get a TraceLog instance for a given class or package name. If a TraceLog instance has already been created for this name, then it is returned instead of creating a new version. If tracing has not been enabled for name, then a NoOpTraceLog is returned.

Parameters:

name - the name of the class or package for which to log trace messages.

loggerName - the name of the logger, which can be placed in log messages to help distinguish the source of the message. Can be null.

Returns:

a TraceLog instance for the given name.

setTraceLogClass

public void setTraceLogClass(java.lang.Class traceLogClass)

Set the class that will be used as the default for all future TraceLog instances returned by this factory.

Parameters:

traceLogClass - the class to use for tracing. This must be a subclass of TraceLog, if not this method has no effect.

reset

public void reset()

Reset this factory to its initial state. Removes all references to previously created TraceLog classes.

creationErrors

public java.lang.String creationErrors()

Returns a String containing details of failures to allocate TraceLog instances. May be useful to find out why logging is not enabled, as failure to create TraceLog instances cannot be logged.

Returns:

a String containing details of failures to allocate TraceLog instances.