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:
|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.
If your application already uses Log4J, Cayenne will simply use your existing configuration.
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:
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:
Default behaviour of Cayenne is to look for a file called cayenne-log.properties, first in the directory $HOME/.cayenne/, then in the CLASSPATH (i.e. a file called .cayenne/cayenne-log.properties 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.
If you are not satisfied with the default location or default file name of the logging configuration, you can supply your own:
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.
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.