Enable Enhanced Tracing for JPA in a Java SE environment

In some cases it might be necessary to run a Java Persistence API (JPA) trace from a Java SE environment.

Enhanced trace can also be used gather additional JPA trace information in a Java SE environment. In the WebSphere Application Server environment, the application server takes care of coupling the standard OpenJPA trace with the enhanced trace function to produce a single trace output. This process must be done manually in a Java SE environment. Here are the steps to use enhanced tracing in a Java SE environment:

Tasks

1. Create a logging configuration properties file. The configuration properties file must use the standard java.util.logging configuration file format. The following code is a sample configuration file. The trace categories defined in the table can also be used in the configuration file. As standard for java.util.logging configuration files, trace categories must be suffixed with .level.

   # Sample logger.properties file
   
   # Enable a file handler
   handlers = java.util.logging.FileHandler
   
   # Set a trace file pattern - the example writes a file named jpa_jse.log to the current working directory java.util.logging.FileHandler.pattern = jpa_jse.log
   
   # Configure the basic logging level of the file handler
   java.util.logging.FileHandler.level = ALL
   
   # Set the openjp.jdbc.SQL category trace to ALL
   openjpa.jdbc.SQL.level = ALL
   
   # Set the enhanced General category trace to FINEST
   openjpa.xtrace.General.level = FINEST 
   
   # Set the enhanced Kernel category to trace at FINER
   openjpa.xtrace.Kernel.level = FINER 
   

   Category	Relevant trace levels	Description
   JPA	OFF, ALL, FINER, FINEST	Add extended trace to the JPA trace group.
   openjpa.*	OFF, ALL, FINER, FINEST	Normal OpenJPA trace in addition to extended trace for all categories in OpenJPA when extended trace is enabled.
   openjpa.xtrace.*	OFF, ALL, FINER, FINEST	Extended trace for all categories in OpenJPA when extended trace is enabled.
   openjpa.xtrace.Jdbc	OFF, ALL, FINER, FINEST	Extended trace for OpenJPA JDBC classes when extended trace is enabled.
   openjpa.xtrace.Lib	OFF, ALL, FINER, FINEST	Extended trace for OpenJPA library classes when extended trace is enabled.
   openjpa.xtrace.Persist	OFF, ALL, FINER, FINEST	Extended trace for OpenJPA persistence classes when extended trace is enabled.
   openjpa.xtrace.Kernel	OFF, ALL, FINER, FINEST	Extended trace for OpenJPA kernel classes when extended trace is enabled.
   openjpa.xtrace.General	OFF, ALL, FINER, FINEST	Extended trace for OpenJPA classes not included in the JDBC, Lib, Persist, or Kernel categories when extended trace is enabled.

2. Modify the persistence.xml file to use Apache commons logging instead of the default OpenJPA logger. Add this property to your persistence unit:

   <property name="openjpa.Log" value="commons"/>
   

3. Add the Apache commons logging JAR file to your class path. We can download the JAR file from the Apache website.

4. Add the following argument to the JVM, where <WAS_install_path> is the fully qualified path of the application server installation directory. Be sure to use the path separator character appropriate for our operating system. This parameter must be specified before the name of the class or JAR file to be used.

   -javaagent:<WAS_install_path>/optionalLibraries/IBM/wsjpa/wsjpatrace.jar
   

5. Add this additional argument to the JVM which specifies the path to your logging configuration file. This option must also be specified before the name of the class or JAR to be used.

   -Djava.util.Logging.config.file=Logger.properties
   

6. Run your Java SE application. Here is a sample Java SE application invocation with enhanced trace enabled:

   java 
   -javaagent:"<WAS_install_path>/optionalLibraries/IBM/wsjpa/wsjpatrace.jar"
   -Djava.util.logging.config.file=Logger.properties 
    my.JPAApplication
   

Enhanced tracing is now functioning in your Java SE environment.

What to do next

Do not use extended trace agent in combination with the OpenJPA PCEnhancer agent in a Java SE environment. If enhanced tracing is used, the OpenJPA PCEnhancer must be used at compile time. If the enhancer and enhanced trace agents are used together, the results are unpredictable.