JPOX
JPOX
 Project  |  Ver 1.1  |  Ver 1.2  |  JDO  |  JPA  |  Guides  |  Tools
1.2 | Persistence | JDO ORM | JPA ORM | Runtime | JDO Runtime | JPA Runtime | Extensions | Developer
JPOX Runtime
RDBMS Datastores
DB4O Datastore
JPOX Logging

JPOX can be configured to log significant amounts of information regarding its process. This information can be very useful in tracking the persistence process, and particularly if you have problems. JPOX will log as follows :-

  • Log4J - if you have Log4J in the CLASSPATH, Apache Log4J will be used
  • JDK1.4 - if you don't have Log4J in the CLASSPATH, but you are using JDK1.4 or later java.util.logging will be used
  • No logging - if you have neither Log4J, nor JDK1.4+ then no logging will be performed

JPOX logs messages to various categories (in Log4J and JDK1.4 these correspond to a "Logger"), allowing you to filter the logged messages by these categories - so if you are only interested in a particular category you can effectively turn the others off. JPOX's log is written by default in English. If your JDK is running in a Spanish locale then your log will be written in Spanish. If you have time to translate our log messages into other languages, please contact one of the developers via the Online Forum.

Logging Categories

JPOX uses a series of categories, and logs all messages to these categories. Currently JPOX uses the following

  • JPOX.JDO - All messages general to JDO
  • JPOX.JPA - All messages general to JPA
  • JPOX.Persistence - All messages relating to the persistence process
  • JPOX.Query - All messages relating to queries
  • JPOX.Lifecycle - All messages relating to object lifecycle changes
  • JPOX.Reachability - All messages relating to "persistence-by-reachability"
  • JPOX.Cache - All messages relating to the JPOX Cache
  • JPOX.ClassLoading - All exceptions relating to class loading issues
  • JPOX.MetaData - All messages relating to MetaData
  • JPOX.Management - All messages relating to Management
  • JPOX.General - All general operational messages
  • JPOX.Connection - All messages relating to Connections.
  • JPOX.JCA - All messages relating to Connector JCA.
  • JPOX.Transaction - All messages relating to transactions
  • JPOX.Plugin - All messages relating to JPOX plug-ins
  • JPOX.Store.Poid - All messages relating to identity generation
  • JPOX.Datastore - All general datastore messages
  • JPOX.Datastore.Schema - All schema related datastore log messages
  • JPOX.Datastore.Persist - All datastore persistence messages
  • JPOX.Datastore.Retrieve - All datastore retrieval messages
  • JPOX.Enhancer - All messages from the JPOX Enhancer.
  • JPOX.SchemaTool - All messages from JPOX SchemaTool
  • JPOX.IDE - Messages from the JPOX IDE.

Using Log4J

Log4J allows logging messages at various severity levels. The levels used by Log4J, and by JPOX's use of Log4J are DEBUG, INFO, WARN, ERROR, FATAL. Each message is logged at a particular level to a category (as described above). The other setting is OFF which turns off a logging category. This is very useful in a production situation where maximum performance is required.

To enable the JPOX log, you need to provide a Log4J configuration file when starting up your application. This may be done for you if you are running within a J2EE application server (check your manual for details). If you are starting your application yourself, you would set a JVM parameter as 

-Dlog4j.configuration=file:log4j.properties
where log4j.properties is the name of your Log4J configuration file. Please note the "file:" prefix to the file since a URL is expected. [When using JDK 1.4 logging you need to specify the system property "java.util.logging.config.file"]

The Log4J configuration file is very simple in nature, and you typically define where the log goes to (e.g to a file), and which logging level messages you want to see. Here's an example 

# Define the destination and format of our logging
log4j.appender.A1=org.apache.log4j.FileAppender
log4j.appender.A1.File=jpox.log
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d{HH:mm:ss,SSS} (%t) %-5p [%c] - %m%n

# JPOX Categories
log4j.category.JPOX.JDO=INFO, A1
log4j.category.JPOX.Cache=INFO, A1
log4j.category.JPOX.MetaData=INFO, A1
log4j.category.JPOX.General=INFO, A1
log4j.category.JPOX.Utility=INFO, A1
log4j.category.JPOX.Transaction=INFO, A1
log4j.category.JPOX.Datastore=DEBUG, A1
log4j.category.JPOX.ClassLoading=DEBUG, A1
log4j.category.JPOX.Plugin=DEBUG, A1
log4j.category.JPOX.Store.Poid=DEBUG, A1

log4j.category.JPOX.Enhancer=INFO, A1
log4j.category.JPOX.SchemaTool=INFO, A1

In this example, I am directing my log to a file (jpox.log). I have defined a particular "pattern" for the messages that appear in the log (to contain the date, level, category, and the message itself). In addition I have assigned a level "threshold" for each of the JPOX categories. So in this case I want to see all messages down to DEBUG level for the JPOX RDBMS persister.

Using java.util.logging

java.util.logging allows logging messages at various severity levels. The levels used by java.util.logging, and by JPOX's internally are fine, info, warn, severe. Each message is logged at a particular level to a category (as described above).

By default, the java.util.logging configuration is taken from a properties file <JRE_DIRECTORY>/lib/logging.properties". Modify this file and configure the categories to be logged, or use the java.util.logging.config.file system property to specify a properties file (in java.util.Properties format) where the logging configuration will be read from. Here is an example: 

handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler
JPOX.General.level=fine 
JPOX.JDO.level=fine 

# --- ConsoleHandler ---
# Override of global logging level
java.util.logging.ConsoleHandler.level=SEVERE
java.util.logging.ConsoleHandler.formatter=java.util.logging.SimpleFormatter

# --- FileHandler ---
# Override of global logging level
java.util.logging.FileHandler.level=SEVERE

# Naming style for the output file:
java.util.logging.FileHandler.pattern=jpox.log

# Limiting size of output file in bytes:
java.util.logging.FileHandler.limit=50000

# Number of output files to cycle through, by appending an
# integer to the base file name:
java.util.logging.FileHandler.count=1

# Style of output (Simple or XML):
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

Please read the javadocs for java.util.logging for additional details on its configuration.

Sample Log Output

Here is a sample of the type of information you may see in the JPOX log when using Log4J. 

21:26:09,000 (main) INFO  JPOX.RDBMS - Adapter initialised : MySQLAdapter, MySQL version 4.0.11a-gamma'-Max'
21:26:09,365 (main) INFO  JPOX.RDBMS - Creating table null.DELETE_ME1080077169045
21:26:09,370 (main) DEBUG JPOX.RDBMS.DDL - CREATE TABLE DELETE_ME1080077169045
(
    UNUSED INTEGER NOT NULL
) TYPE=INNODB
21:26:09,375 (main) DEBUG JPOX.RDBMS.DDL - Execution Time = 3 ms
21:26:09,388 (main) WARN  JPOX.RDBMS.Schema - Schema Name could not be determined for this datastore
21:26:09,388 (main) INFO  JPOX.RDBMS - Dropping table null.DELETE_ME1080077169045
21:26:09,388 (main) DEBUG JPOX.RDBMS.DDL - DROP TABLE DELETE_ME1080077169045
21:26:09,392 (main) DEBUG JPOX.RDBMS.DDL - Execution Time = 3 ms
21:26:09,392 (main) INFO  JPOX.RDBMS.Schema - Initialising Schema "" using "SchemaTable" auto-start option
21:26:09,401 (main) DEBUG JPOX.RDBMS - Retrieving type for table JPOX_TABLES
21:26:09,406 (main) INFO  JPOX.RDBMS - Creating table null.JPOX_TABLES
21:26:09,406 (main) DEBUG JPOX.RDBMS.DDL - CREATE TABLE JPOX_TABLES
(
    CLASS_NAME VARCHAR (128) NOT NULL UNIQUE ,
    `TABLE_NAME` VARCHAR (127) NOT NULL UNIQUE 
) TYPE=INNODB
21:26:09,416 (main) DEBUG JPOX.RDBMS.DDL - Execution Time = 10 ms
21:26:09,417 (main) DEBUG JPOX.RDBMS - Retrieving type for table JPOX_TABLES
21:26:09,418 (main) DEBUG JPOX.RDBMS - Validating table : null.JPOX_TABLES
21:26:09,425 (main) DEBUG JPOX.RDBMS - Execution Time = 7 ms

So you see the time of the log message, the level of the message (DEBUG, INFO, etc), the category (JPOX.RDBMS, etc), and the message itself. So, for example, if I had set the JPOX.RDBMS.DDL to DEBUG and all other categories to INFO I would see *all* DDL statements sent to the database and very little else.