Cayenne logging is based on Log4J package from Jakarta Apache Project. This is the most powerful and flexible logging framework available in Java. Log4J configuration is normally done using a property file. Later in this chapter we explain how Cayenne loads configuration files and how to customize this process. Format of the entries in this file is described in the Log4j documentation. Here is a sample configuration file contents:

# General Log4J stuff
log4j.rootLogger=WARN, A1
log4j.appender.A1.layout.ConversionPattern=cayenne %-5p [%t %d{MM-dd HH:mm:ss}] %c{1}: %m%n

# indiv. packages configuration - turning on the packages that we care about = INFO

# This is the logger that controls SQL output
# Setting the level to INFO or DEBUG will turn the logs on = INFO
Users of Other Logging Frameworks
If your application uses another package for its own logging purposes (like JDK 1.4 java.util.logging, or commons-logging from Jakarta), Cayenne Log4J-based logging will not interfere with your other logging configurations.
Log4J Users
If your application already uses Log4J, Cayenne will simply use your existing configuration.

Essential Loggers

SQL Tracing. Very important logging feature of Cayenne is tracing the execution of SQL statements. If configured appropriately, Cayenne will log opened connections, executed queries, and DDL statements. This is extremely important in understanding what is going on in the application, tracing bugs, etc. Logger that is responsible for SQL logging is "org.apache.cayenne.access.QueryLogger". Its default logging level is INFO, so the following lines in the configuration file will turn it on or off:

# Turn SQL tracing on = INFO

# Turn SQL tracing off, e.g. to increase performance = WARN

Tracing Configuration Loading. Cayenne XML files may contain errors, or maybe missing or inaccessible by the application; there maybe lots of other reasons why Cayenne fails to startup, from missing JDBC drivers to misspelled database URLs. To trace configuration loading process, you will need to turn on the following loggers: = DEBUG = DEBUG

Default Configuration

Default behaviour of Cayenne is to look for a file called, first in the directory $HOME/.cayenne/, then in the CLASSPATH (i.e. a file called .cayenne/ at the root of one of the locations accessible by the ClassLoader). $HOME is a system specific home directory of a user running the application. If you don't know what it is, try printing it from Java like this: System.out.println(System.getProperty("user.home")).

If you don't explicitly create this file, Cayenne will use the one included in cayenne.jar (and therefore guaranteed to be in the CLASSPATH). This means - no special logging configuration is required, Cayenne will just work out of the box.

Custom Configuration File

If you are not satisfied with the default location or default file name of the logging configuration, you can supply your own:

// Obtain the URL of the custom configuration file url = ....;

// configure cayenne logging
// note that URL can be null, resulting in default settings

It is important to execute this code before any calls to Cayenne are made in the application, or otherwise it will have no effect on logging.

Configuring Log4J outside of Cayenne

Finally, if your application already uses Log4J and implements its own logic to configure logging, it would be undesirable for Cayenne to use its default behavior and override any application settings. Also it is convenient to use a single logging configuration file per application. Cayenne detects if Log4J has already been started and will stop any attempts to configure logging. This means that Log4J services must be configured prior to any calls to Cayenne.