Documentum Developer Program

Enabling Logging in DFC Applications

Using the com.documentum.fc.common.DfLogger class

April 2003

Documentum Developer
Program 1/5
The Documentum DFC class, DfLogger is available with DFC 5.1 or higher and can only
be used with Java. It uses the log4j logging library to enable logging from DFC
applications. The log4j.properties file in %DOCUMENTUM%\Config directory is used to
configure DfLogger. Typically, % DOCUMENTUM% refers to C:\Documentum.

Log4j is an open source project that provides a reliable, fast and extensible logging
library for Java. It is fully configurable at runtime using external configuration files. See
the Apache Jakarta Web site, http://jakarta.apache.org/log4j/docs/ for complete
information.

This document describes how to configure and use the logging library from DFC.

Enabling Logging:

Let’s look at how we can enable logging from the Java application examples that are
found on the Documentum Developer Program Component Exchange Web site. These
examples are packaged in com.documentum.devprog.

First, open the file $DOCUMENTUM\Config\log4j.properties. Then copy and paste the
following lines at the end of the file:

# Enable log messages from DevProg examples

log4j.logger.com.documentum.devprog=DEBUG,DevProgAppender

#DevProg Appender
log4j.appender.DevProgAppender=org.apache.log4j.RollingFileAppender
log4j.appender.DevProgAppender.File=DevProg.log
log4j.appender.DevProgAppender.MaxFileSize=100KB
log4j.appender.DevProgAppender.layout=org.apache.log4j.PatternLayout
log4j.appender.DevProgAppender.layout.ConversionPattern=%d{HH:mm:ss}
%p %c %m %n

Save the file and exit. Running any of the examples that belong to the package
com.documentum.devprog will now result in the creation of a file called DevProg.log in
the same location as the executing program.

Next we’ll look at each line that we’ve added.

Specify the Package, Print Level and Appender

The following line specifies that the com.documentum.devprog package will be logged,
the print level is DEBUG and the name of our appender is DevProgAppender:

log4j.logger.com.documentum.devprog=DEBUG,DevProgAppender

Printing levels for loggers are DEBUG, INFO, WARN, ERROR and FATAL. Where
DEBUG is the lowest level resulting in all messages being logged. The FATAL level, on
the other hand, results from severe errors that cause the application to abort. In our
example, we have set printing to DEBUG, the most verbose level.

Documentum Developer
Program 2/5
An appender is an output destination for logged messages. In our example,
DevProgAppender is the appender to be used by the com.documentum.devprog
package. Two of the standard appender types defined by Log4j are console and file. A
console appender implies that the console is used as the destination for all log
messages. A file appender implies that a file is used as a destination for all log
messages.

Enabling logging will log messages from all classes whose level is DEBUG or higher
within the package or within packages lower in hierarchy than the package specified, (in
the examples above the package is com.documentum.devprog).
Examples:
To enable DFC logging for all classes for WARN and higher levels,

log4j.logger.com.documentum.fc=WARN, someAppender

To enable WDK logging for all classes for WARN and higher levels,

log4j.logger.com.documentum.web=WARN, someAppender

Configuring the Appender

The following lines configure the appender instance called DevProgAppender. The first
line specifies the type of appender to use. It defines the type to be a
RollingFileAppender, which automatically backs up log files once they reach a max size
(specified by the second line). The RollingFileAppender is a specialization of the
FileAppender.

log4j.appender.DevProgAppender=org.apache.log4j.RollingFileAppender
log4j.appender.DevProgAppender.MaxFileSize=100KB

The following line specifies the name of the log file. Since a file is being used, the name
of the log file needs to be specified. Since no path is specified, the file will be created in
the same location as the executing program.

log4j.logger.DevProgAppender.File=DevProg.log

The following line defines the layout type for the DevProgAppender appender. The
layout is used to specify how the logging information should be formatted. In the
example, a pattern layout is used. A conversion pattern specifies the interpretation of the
pattern.

Documentum Developer
Program 3/5
 log4j.appender.DevProgAppender.layout=org.apache.log4j.PatternLayout
log4j.appender.DevProgAppender.layout.ConversionPattern=%d{HH:mm:ss} %p %c %m %n

The conversion pattern:

%d - Date in format {HH:mm:ss}, which is {Hours:Minutes:Secs}.
%p - The level of the log message – DEBUG(lowest), INFO, WARN, ERROR and
FATAL(highest)
%c - The category of the logger, i.e. the package to which this logger belongs.
%m – The message to be logged.
%n – A newline character so that every log message is on a new line.

Therefore, in our example, the date, level of logging, and the package will print to the file
each time a message is logged.

Using DfLogger
To log a message, insert a call to DfLogger in your DFC code as follows:

DfLogger.debug(this, "Hello My first debug message",null,null);

The first argument specifies the class for which the debug message is being logged.
Usually, it is the same as the class that calls the method and hence the this Java
keyword is used. The this keyword refers to the current class instance.
To print a stack trace of an exception, pass the instance of the Throwable class, (which
is the superclass for the Exception class) as the fourth parameter.

….
catch(DfException dfe)
{
DfLogger.debug(this, "My first stack trace.", null, dfe);
}

However, for printing exceptions the DfLogger.error(…) method might be more

appropriate.

DfLogger.error((this, "My first stack trace.", null, dfe);

The methods error(…), fatal(…), info(…), debug(…), warn(…) refer to the level of the log
messages. All of these methods have a similar method signature and are static methods
of the DfLogger class.

Documentum Developer
Program 4/5
Using a Resource Bundle
If a resource bundle is used, the second argument (i.e. message) is treated as a key and
searched for existence in the Resource Bundle. If it exists, then the value of that
property (key) is displayed. If the value is a parameterized string, the parameter values
are replaced from the String array supplied in the third argument to the above-mentioned
methods.
Example:
Assume that the Resource bundle (usually a .properties file) contains the following entry:

RENDER_TRANS_FAILED=Transformation for XML object \”{0}\” using the XSL object \”{1}\”
has failed.

The following call to DfLogger,

String strParams[] = {xmlObj.getObjectName(), xslObject.getObjectName()};

DfLogger.debug(this, “RENDER_TRANS_FAILED”,strParams, null);

will result in the message “Transformation for XML Object Ascorbic_acid.xml using the
XSL object advertising.xsl has failed”

The values in the array strParams were used to replace the parameters specified in the
value of the message (key). The {0} was replaced with the name of the XMLobject
(index position 0 in the array) and {1} was replaced with the name of the XSL object
(index position 1 in the array)

A resource bundle to be used can be registered by the following method call

DfLogger.registerResourceBundle(ResourceBundle res)

Reference
To learn more about the Log4j package, take a look at
http://jakarta.apache.org/log4j/docs/manual.html

Documentum Developer
Program 5/5