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