Documentum Developer Program

Transcription

1 Program Enabling Logging in DFC Applications Using the com.documentum.fc.common.dflogger class April 2003 Program 1/5

2 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, 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 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. Program 2/5

3 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. Program 3/5

4 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. Program 4/5

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 Program 5/5