In some cases it might be necessary to run a Java Persistence API (JPA) trace from a Java SE environment.
About this task
Enabling enhanced tracing for 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:
Procedure
- 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
Table 1. Trace categories. Back up your server configuration
before you enable enhanced tracing.
Category |
Relevant trace levels |
Description |
JPA |
OFF, ALL, FINER, FINEST |
Adds 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. |
- 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"/>
- Add the Apache commons logging Java archive (JAR) file to your class path.
You can download the JAR file from the Apache website.
- Add the following argument to the Java virtual machine (JVM), where <WAS_install_path> is
the fully qualified path of your application server installation
directory. Be sure to use the path separator character
appropriate for your 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
- 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
- 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
Results
Enhanced tracing is now functioning in your Java SE environment.
What to do next
Avoid trouble: 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.
gotcha