[Jdo Wiki] Update of "LoggingDetails" by MichaelWatzek

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jdo Wiki" for change notification.

The following page has been changed by MichaelWatzek:
http://wiki.apache.org/jdo/LoggingDetails

------------------------------------------------------------------------------
+ = TCK20 Logging =
+ 
+ A TCK run involves several tools/components. Each of these components use standard or proprietary logging implementations:
+ 
+  * '''Derby''' uses propriatary logging.
+  * '''JPOX''' uses Log4J.
+  * '''Spring``Framework''' (called by TCK) uses Apache commons-logging.
+  * '''TCK testcases''' use Apache commons-logging.
+  * '''TCK JUnit''' result logging uses proprietary logging.
+  * '''TCK result summary''' uses proprietary logging.
+ 
+ Log files are written under a common root directory `tck20/target/logs`. All of the involved tools/components above are configured to write to a separate subdirectory. When you run the TCK, the following directories are created:
+ 
+  * `.../logs/database/`
+  * `.../logs/enhancer/`
+  * `.../logs/<timestamp>/`
+ 
+ Each of these directories contains one or more log files. The log files in the database and enhancer subdirectories are configured to append log messages for consecutive TCK runs. In contrast, the `<timestamp>` directory is always created for each TCK run. The naming pattern is `yyyyMMdd-HHmmss`.
+ 
+ Below, log files for all involved tools/components are listed:
+ 
+  * Derby writes log messages to `.../logs/database/derby.txt`.
+  * JPOX enhancer writes log messages to directory `.../logs/enhancer/`. Two log files are written, one for each identity type. The naming pattern is `<identity type>-jpox.txt`.
+  * JPOX runtime writes log messages to the `<timestamp>` directory. Several log files are written for each TCK configuration, one per database and one per identity type. The naming pattern is `<database>-<identity type>-<TCKConfiguration>-jpox.txt`.
+  * TCK test cases write log messages to the `<timestamp>` directory. Several log files are written for each TCK configuration, one per database and one per identity type. The naming pattern is `<database>-<identity type>-<TCKConfiguration>-tck.txt`.
+  * TCK writes JUnit result output to the `<timestamp>` directory. Several log files are written for each TCK configuration, one per database and one per identity type. The naming pattern is `<database>-<identity type>-<TCKConfiguration>-junit.txt`.
+  * TCK writes a result summary file for each run. This file contains information about each TCK configuration per database and per identity type. It is written to the `<timestamp>` directory. The file name is `TCK-results.txt`.
+ 
+ = TCK20 Logging Configuration =
+ 
+ Each of the involved logging implementations use different properties files configuring logging. These properties files are located in directory `tck20/test/conf`:
+ 
+  * Derby uses `derby.properties`.
+  * Log4J uses `log4j.properties`.
+  * Apache commons-logging uses `common-logging.properties`.
+ 
+ The TCK junit result logging as well as the TCK result summary logging is not configurable.
+ 
+ We provide another properties file configuring JDK 1.4 logging. This file may be used by implementations under test. Besides, it is used if Apache commons-logging is configured to run with JDK 1.4 logging.
+ 
+ = TCK20 Logging Configuration for JDO vendors =
+ 
+ JDO implementations using Log4J or JDK 1.4 logging may use specific file appender or file handler implementations of tck20 in order to write logging output to directory `tck20/target/logs/<timestamp>/`. This may be achieved by editing files `tck20/test/log4j.properties` or `tck20/test/logging.properties`:
+ 
+ {{{
+ # log4j vendor specific appender
+ log4j.appender.vendor=org.apache.jdo.tck.util.TCKFileAppender
+ log4j.appender.vendor.File=vendor.txt
+ 
+ # JDK 1.4 vendor specific handler
+ handlers = org.apache.jdo.tck.util.TCKFileHandler
+ org.apache.jdo.tck.util.TCKFileHandler.fileName = vendor.txt
+ org.apache.jdo.tck.util.TCKFileHandler.level = FINEST
+ }}}
+ 
+ JDO implementations using other logging implementations may use a static public tck20 method to retrieve the name of the logging file to be
+ generated in directory `tck20/target/logs/<timestamp>/`:
+ 
+ {{{
+     org.apache.jdo.tck.util.BatchTestRunner#changeFileName(String fileName)
+ }}}
+ 
+ This method returns a file name which is constructed by values of some system properties appended by the given file name. The system properties are:
+ 
+  * `jdo.tck.log.directory`: Specifies the directory for the file.
+  * `jdo.tck.database`, `jdo.tck.cfg`: The values of these properties prepend the given file name.
+  * `jdo.tck.identitytype`: The value of this property is replaced by `app` if it equals `applicationidentity`, else it is replaced by `dsid`.
+ 
+ The returned file name is constructed as follows:
+ 
+ {{{
+     <jdo.tck.log.directory>/<jdo.tck.database>-<jdo.tck.identitytype>-<jdo.tck.cfg>-<given file name>
+ }}}
+ 
+ Values of properties which do not exist default to `""`. 
+ 
  = Logging =
  
  The prototype (see version 2005-02-10 at SubversionRepository) replaces the proprietary logging implementation in ri11 and tck11 by using the apache commons logging API. This removes the Logger implementation in ri11 and its query and model specific subclasses. Now the implementation classes in sub-projects ri11 and tck11 retrieve a logger instance by name and directly call the logger methods as defined in the apache commons Log interface.