TriActive Java Data Objects

TriActive JDO (TJDO) is an implementation of Sun's Java Data Objects specification. It is based on version 1.0.1 of the spec, but includes some features found in the 2.0 spec.

TJDO is licensed under the Apache Software License.

Table Of Contents

  1. Distribution Contents
  2. Using TJDO
  3. Feature List
  4. DBMS Compatibility
  5. Unsupported Features
  6. JDO Metadata & Extensions
  7. Query Extensions
  8. Schema Management
  9. Collections
  11. Direct SQL Queries
  12. Building TJDO
  13. Release History
  14. Frequently Asked Questions

Distribution Contents

conf Sample configuration files.
docs/ This document and other supporting docs.
docs/api/ Javadoc API documentation.
lib/jdo.jar The JDO 1.1 API.
lib/jdori.jar The JDO 1.1 Reference Implementation.
lib/tjdo.jar The TriActive JDO runtime.

tjdo.jar and jdo.jar need to be stored together in the same directory, but only tjdo.jar actually needs to be in your CLASSPATH (it finds jdo.jar automatically using the manifest "Class-Path:" mechanism). jdori.jar is only needed when enhancing classes.

Using TJDO

Third-Party Dependencies

* = optional.

File(s) Needed To Description
Enhance Apps Run Apps Build TJDO Test TJDO
jdo.jar X X X X JDO 1.1 API interfaces. Packaged with TJDO.
X     X The Apache JDO 1.1 Reference Implementation, which is used for class enhancing. Packaged with TJDO.
X X X X Jakarta Logging. Used by TJDO and the Apache JDO RI.
jta.jar   X* X* X* Java Transaction API (JTA). Usually not needed if running within an application server. Available from Sun at
ojdbc14.jar   X* X* X* The Oracle JDBC driver jar is necessary in order to build the Oracle adapter classes in TJDO. If the adapter classes are not built then the resulting tjdo.jar will not work with Oracle.
junit.jar       X JUnit 1.8 or greater.
      X* Jakarta DBCP and its dependent packages, the Collections and Pool components. These are optional but, if present, are used for connection pooling during TJDO unit testing.

Bytecode Enhancement

JDO requires that bytecode be "enhanced" to make designated classes persistence-capable. TriActive JDO does not include a bytecode enhancer utility, but its runtime can be used with any classes enhanced by a utility that conforms to the JDO spec.

TJDO does include an invocation wrapper around the class enhancer in the Apache Reference Implementation. It can be invoked from the command line as:

java com.triactive.jdo.enhance.ApacheReferenceEnhancer [-l listfile] [-v] [-d outputdirectory] jdometadatafile ...

If you're using Ant to build your project, you can add the lines similar to those below to your compile task to perform class enhancement:

<copy todir="${project.classes}">
    <fileset dir="${project.src}" includes="**/*.jdo"/>
<apply executable="java" parallel="true" failonerror="true">
    <arg value="com.triactive.jdo.enhance.ApacheReferenceEnhancer"/>
    <arg value="-d"/>
    <arg value="${project.classes}"/>
    <fileset dir="${project.classes}" includes="**/*.jdo"/>

Note that this also copies all JDO metadata files to your classes/ directory. The metadata files are needed at both enhancement time and at run time.

Configuration Properties

TJDO can be configured using a number of configuration properties. They fall into two groups:

Logging & Tracing

TJDO uses Jakarta Commons Logging for logging certain run-time events. Commons Logging can be configured to use any of a number of different underlying log mechanisms, including Log4J. A sample configuration file ( for Log4J is included with TJDO. If you fail to configure a logger no logging will take place.

Debug Logging

The following log categories provide debug logging (they all correspond to internal TJDO class names):

Category Name Data Logged At DEBUG Level
com.triactive.jdo.NonmanagedTransaction Transaction begin and end notifications and transactional cache updates
com.triactive.jdo.model.ClassMetaData Metadata loading
com.triactive.jdo.sco.* State changes on second-class wrapper objects
com.triactive.jdo.state.* State changes on PersistenceCapable objects Loading of table metadata w/load time* Compiler input (filter, ordering, etc.), output (SQL), and compilation time Periodic cache statistics (capacity/size/calls/hits) JDBC statement parameters (for most statement executions)
com.triactive.jdo.util.Imports References to non-existent classes
com.triactive.jdo.util.ReferenceValueMap Periodic cache statistics (size/hits/misses/clears)

JDBC Tracing

Most of the JDBC activity generated by TJDO can be traced and logged. In particular, the logging of executed SQL statements often provides valuable feedback re. the activity of the TJDO runtime.

When enabled, all trace output is sent to a single log category:

Category Name Data Logged
com.triactive.jdo.JdbcTrace Trace of JDBC activity

Tracing is enabled by setting the config property com.triactive.jdo.JdbcTrace. The setting is a comma-separated string of keywords indicating which tracing options to enable. All options not specified are disabled by default.

The available trace options are:

Option keyword Description Log level
LogExecutionTimes Logs every executed SQL statement and its execution time in milliseconds INFO
LogExecutionFailures Logs every SQL statement whose execution throws a SQLException ERROR
LogWarnings Logs every SQLWarning produced by a Connection, Statement, or ResultSet WARN

LogExecutionFailures is particularly useful with those very unhelpful JDBC drivers (such as Oracle's) whose SQLExceptions don't report the offending SQL.