1. Introduction

This document describes how logging is implemented and how it can be configured for the freebXML Registry and related clients.

The freebXML Registry relies on Apache Commons-Logging for the logging abstraction. Furthermore, it is deployed with Apache Log4J, which is the first implementation choice for Commons-Logging.

Note: Consult 3rd party documentation for logging details on libraries used by the freebXML Registry.

2. Basics on Apache Commons-Logging

This section briefly describes Commons Logging configuration. Detailed information can be obtained from Commons-Logging User Guide.

Commons-Logging uses 2 abstractions: Log (the logger) and LogFactory (which creates Log instances). The Log implementation chosen by the default LogFactory implementation is the first match on the following discovery process:

  1. Look for a configuration attribute of this factory named org.apache.commons.logging.Log in resource commons-logging.properties.
  2. Look for a system property named org.apache.commons.logging.Log.
  3. If the Log4J is available in the class path, use it.
  4. If the application is executing on a JDK 1.4 system, use JDK 1.4 logger.
  5. Finally, fall back to the default SimpleLog.

Optionally, Commons-Logging can be turned off and produce no log at all by setting org.apache.commons.logging.Log=org.apache.commons.logging.NoOpLog.

3. Basics on Apache Log4J

This section briefly describes Apache Log4J configuration. For detailed information, check Log4J Documentation.

Log4J is configured using system properties and/or a properties file (log4j.properties, by default). Log4J accepts many hierarchically configured Loggers (used by the source code to log something) with the RootLogger residing on top of the hierarchy. Loggers can be mapped to one or more appenders (which actually write the log message that the user can see). Both Logger and Appender can have a minimal Priority to start logging. These are some relevant properties:

  • log4j.rootCategory=priority [, appender]* : Set the RootLogger priority and its appenders.
  • log4j.logger.logger.name=priority : Set the priority for the named logger and all loggers hierarchically below it.
  • log4j.appender.appender.Threshold=priority : Set the priority to the given appender only.

priority can be: DEBUG, INFO, WARN, ERROR, or FATAL.

appender corresponds to a configured output device.

logger.name corresponds to the parameter of LogFactory.getLog(logger.name), used to create the logger instance. logger.name could be a package name, for instance com.foo, which would be a parent for a com.foo.Bar logger.

4. freebXML Registry Log Configuration

There are 3 basic situations where log can be configured for freebXML Registry: build time, server runtime and client runtime.

4.1 Build -time Log

Some of the the targets in build scripts will use the apacheLog variable to configure Commons-Logging. In build.xml, it is defined by default to quiet mode like this:

<!-- A properties to control whether apache common logging is enabled -->

<property name="apacheLog" value="org.apache.commons.logging.impl.NoOpLog"/>

It should not be changed there, but in the build.properties file:

#Used to control apache common logging

#Use SimpleLog to have logging output

apacheLog=org.apache.commons.logging.impl.SimpleLog


//TODO: Give more information on using Log4J/selective package logging here.

Note: This configures only the client side of the building process. For server side, see the next section.

4.2 Server Run -time Log

Server side log is configured by commons-logging.properties and (possibly)log4j.properties resources present in classpath. These files can be found at:

<TOMCAT_HOME>/webapps/omar/WEB-INF/classes

By the time this document was written, commons-logging.properties was setting log to NoOpLog (quiet mode). In order to get freebXMLRegistry Server to start producing log, change org.apache.commons.logging.Log property value; check the file for other possibilities or comment the property to fall back to Log4J.

Next you should decide the desired priority levels and appenders in log4j.properties. Again, by the time this document was written, there were 2 appenders configure, stdout (Console) and R (ebxmlrr.log file in current directory), and priority was INFO. If you need to debug the server, you could change the RootLogger (log4j.rootLogger property) to trace or debug. Although, that will generate a huge amount of unnecessary log that might be quite difficult to follow. The solution for that is to add a new Logger just for the class/package you want to debug. For instance, in order to debug server security module, leave the RootLogger on INFO and add the following line to the configuration:

log4j.logger.org.freebxml.omar.server.security=trace

Hint: If you want Tomcat to redirect Console log messages generated by OMAR webapp to a .log file in <TOMCAT_HOME>/logs, edit Tomcat server configuration (<TOMCAT_HOME>/conf/server.xml) and add a context like this:

<Context path="/omar" docBase="omar" debug="0"

reloadable="true" crossContext="true" swallowOutput="true">

<Logger className="org.apache.catalina.logger.FileLogger"

prefix="omar_log." suffix=".txt"

timestamp="true"/>

</Context>


4.3 Client Run -time Log

This section is under construction.

//TODO: URGENT! reconsider choice and review this!

Client runtime log is similar to server in the sense that Commons-Logging and Log4J are present (loaded by jaxr-ebxml.jar), although there are a couple of basic differences:

  1. commons-logging.properties and log4j.properties are currently packed in the client jars and can be in different jars
  2. If run from build script, the same system property with value apacheLog presented in Buil Log section will be in use.

5. Log FAQ

Help to write this section by throwing your questions to ebxmlrr-tech@lists.sourceforge.net.

How to turn trace on for RegistrySOAPServlet so one can see each request / response that is received/sent by the server?

Follow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):

  1. Check file commons-logging.properties. Make sure property org.apache.commons.logging.Log property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".
  2. Edit file log4j.properties. Add this line (or change, if property exists):

    log4j.logger.org.freebxml.omar.server.interfaces.soap.RegistrySOAPServlet=trace
  3. Restart server or reload webapp.

Note: Currently uses the default platform charset for logging the request / response message.

How to trace log of AuthorizationServiceImpl (Auth checking)?

Follow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):

  1. Check file commons-logging.properties. Make sure property org.apache.commons.logging.Log property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".
  2. Edit file log4j.properties. Add the line (or change, if property exists):

    log4j.logger.org.freebxml.omar.server.security.authorization.AuthorizationServiceImpl=trace

    or, for full Authorization package trace logging, the line
  3. log4j.logger.org.freebxml.omar.server.security.authorization=trace

  4. Restart server or reload webapp.

How to trace DAO activity / persistence module?

Follow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):

  1. Check file commons-logging.properties. Make sure property org.apache.commons.logging.Log property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".
  2. Edit file log4j.properties. For tracing only the DAO classes, add the line (or change, if property exists):

    log4j.logger.org.freebxml.omar.server.persistence.rdb.AbstractDAO=trace

    Probably it is more useful to trace (rdb) Persistence module:

    log4j.logger.org.freebxml.omar.server.persistence=trace

    Or:

    log4j.logger.org.freebxml.omar.server.persistence.rdb=trace
  3. Restart server or reload webapp.

How to trace input/ouput queries to SQLQueryProcessor?

Follow these steps (configuration files located in <TOMCAT_HOME>/webapps/omar/WEB-INF/classes):

  1. Check file commons-logging.properties. Make sure property org.apache.commons.logging.Log property in is commented or has value "org.apache.commons.logging.impl.Log4JLogger".
  2. Edit file log4j.properties. Add the line (or change, if property exists):

    log4j.logger.org.freebxml.omar.server.query.sql.SQLQueryProcessor=trace

    or, for full logging of SQL Query module, the line
  3. log4j.logger.org.freebxml.omar.server.query.sql=trace

  4. Restart server or reload webapp.

6. Links