TriActive Java Data Objects

Release: $Name: TJDO_2_0 $
Updated: $Date: 2003/10/20 05:59:24 $

TriActive JDO (TJDO) is an implementation of Sun's Java Data Objects specification. It is based on version 1.0.1 of the 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. Query Extensions
  7. Schema Management
  8. Collections
  9. Views
  10. Direct SQL Queries
  11. Building TJDO
  12. Release History
  13. Frequently Asked Questions

Distribution Contents

docs/ This document and other supporting docs.
docs/api/ Javadoc API documentation (not very helpful yet).
lib/tjdo.jar The TriActive JDO runtime.
lib/pg72jdbc2-tjdo.jar A patched copy of the PostgreSQL 7.2 JDBC driver.
log4jexample.properties An example Log4J properties file.

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).


Using TJDO

Third-Party Dependencies

* = optional.

File Needed To Description
Enhance Apps Run Apps Build TJDO Test TJDO
jdo.jar X X X X JDO 1.0.1 API interfaces. Available from Sun by downloading the reference implementation. This does not need to be included in your CLASSPATH; TJDO finds it automatically using the manifest "Class-Path:" mechanism. Note: the older 1.0 jar won't work, you need to download 1.0.1.
log4j-version.jar X X X X Jakarta Log4J.
jdori.jar
jdori-enhancer.jar
X     X Sun's JDO 1.0.1 reference implementation, which is used for class enhancing. This only needs to be in your CLASSPATH when running the class enhancer (i.e. - at compile time, not run time). This is also available from Sun by downloading the reference implementation. Note: the older 1.0 jars won't work, you need to download 1.0.1.
xercesImpl.jar
xml-apis.jar
(aka xmlParserAPIs.jar)
X* X* X* X* TJDO requires an XML parser. If you're using a JRE older than 1.4 we recommend using Xerces2, as this is what TJDO has been tested with.
jta.jar   X* X* X* Java Transaction API (JTA). Usually not needed if running within an application server. Available from Sun at http://java.sun.com/products/jta/.
jdbc2_0-stdext.jar   X* X* X* The JDBC 2.0 optional package. Only needed for JRE's older than 1.4, which don't include the javax.sql package. Otherwise you can download this from Sun.
ojdbc14.jar or
classes_12.jar, etc.
  X* X* X* The Oracle JDBC drivers are necessary in order to build the Oracle adapter classes in TJDO. If the Oracle adapter classes are not built then the resulting tjdo.jar will not work with Oracle.
junit.jar       X JUnit. http://www.junit.org.
commons-dbcp.jar
commons-collections.jar
commons-pool.jar
      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.
xalan.jar       X Xalan. Used to create unit test reports.

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 1.0 or 1.0.1 specs.

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

java com.triactive.jdo.enhance.SunReferenceEnhancer [-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"/>
</copy>
<apply executable="java" parallel="true" failonerror="true">
    <arg value="com.triactive.jdo.enhance.SunReferenceEnhancer"/>
    <arg value="-d"/>
    <arg value="${project.classes}"/>
    <fileset dir="${project.classes}" includes="**/*.jdo"/>
</apply>

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 the following system properties:

Property Possible Values Default Value Purpose
com.triactive.jdo.validateTables "true"
"false"
"true" Selects whether TJDO should automatically validate the structure of all database tables to ensure they're compatible with your Java classes.
com.triactive.jdo.validateConstraints "true"
"false"
"true" Selects whether TJDO should automatically validate the existence of all appropriate foreign key constraints and indexes.
com.triactive.jdo.autoCreateTables "true"
"false"
"false" Selects whether TJDO should automatically create any missing database tables and/or table constraints. Only applicable if table and/or constraint validation is enabled.
com.triactive.jdo.transactionIsolation "serializable"
"repeatable read"
"read committed"
"read uncommitted"
"serializable" Selects the default JDBC transaction isolation level for all PersistenceManagerFactories. The values are case-insensitive, and spaces and underscores are equivalent.
com.triactive.jdo.useUpdateLock "true"
"false"
"false" Selects whether TJDO should use SELECT ... FOR UPDATE on all fetch operations to prevent the possibility of dirty writes. This only applies if the transaction isolation level is "read committed" or "read uncommitted".
com.triactive.jdo.useValidatingXmlParser "true"
"false"
"true" Selects whether TJDO should use a validating XML parser to parse metadata files.
com.triactive.jdo.oracle.nlsSortOrder Any valid Oracle linguistic definition name "LATIN" On Oracle, selects the sort ordering for String fields in queries. TJDO applies the NLSSORT() function to all String columns in generated ORDER BY clauses. This property selects the NLS_SORT parameter passed to the function.
com.triactive.jdo.store.maxRetries Positive Integer "3" A number of internal JDO operations obtain a database connection with an isolation level of serializable, regardless of the transactionIsolation property. Occasionally this was resulting in an Oracle exception "ORA-08177: can't serialize access for this transaction". Retry loops were added around these operations. This property specifies the number of retry attempts for these operations. The value includes the first attempt.

Logging

TJDO uses Jakarta Log4J for logging certain run-time events. Log4J can be configured via a number of different mechanisms, the simplest of which is to place a log4j.properties file somewhere in your CLASSPATH (see the Log4J documentation for details). A sample configuration file (log4jexample.properties) is included with TJDO. If you fail to configure it, Log4J will output a warning to System.err and no logging will take place.

The following Log4J 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
com.triactive.jdo.store.AbstractMapStore Executed SQL statements w/execution time
com.triactive.jdo.store.AbstractSetStore Executed SQL statements w/execution time
com.triactive.jdo.store.AbstractTable Executed SQL statements w/execution time
com.triactive.jdo.store.BaseTable Executed SQL statements w/execution time
com.triactive.jdo.store.DeleteRequest Executed SQL statements w/execution time
com.triactive.jdo.store.FetchRequest Executed SQL statements w/execution time
com.triactive.jdo.store.InsertRequest Executed SQL statements w/execution time
com.triactive.jdo.store.JDOQLQuery Executed SQL statements w/execution time
com.triactive.jdo.store.JDOQLQuery$Compiler Compiler input (filter, ordering), output (SQL), and compilation time
com.triactive.jdo.store.MapEntrySetStore Executed SQL statements w/execution time
com.triactive.jdo.store.MapValueSetStore Executed SQL statements w/execution time
com.triactive.jdo.store.NormalMapStore Executed SQL statements w/execution time
com.triactive.jdo.store.OracleClobMapping Executed SQL statements w/execution time
com.triactive.jdo.store.SchemaTable Executed SQL statements w/execution time
com.triactive.jdo.store.StatementText Generated SQL statements
com.triactive.jdo.store.StoreManager Loading of table metadata w/load time
com.triactive.jdo.store.TJDOSQLQuery Executed SQL statements w/execution time
com.triactive.jdo.store.UpdateRequest Executed SQL statements w/execution time
com.triactive.jdo.util.Imports References to non-existent classes
com.triactive.jdo.util.ReadWriteLock Notifications of extended waiting (> 5 sec.) for a lock
com.triactive.jdo.util.ReferenceValueMap Periodic cache statistics (size/hits/misses/clears)

The logging of executed SQL statements usually provides the most valuable feedback re. activity in the TJDO runtime.


SourceForge.net