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
10. Views
11. Direct SQL Queries
12. Building TJDO
13. Release History
14. Frequently Asked Questions

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.ApacheReferenceEnhancer"/>
    <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 a number of configuration properties. They fall into two groups:

• The first group can be included either in the properties passed to JDOHelper.getPersistenceManagerFactory() or as system properties or both, with the former overriding the latter. They consist of the commonly modified properties.

  Configuration Properties - PersistenceManagerFactory or system

  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. Can be overridden for individual PersistenceManagerFactories or individual Transactions using the setTransactionIsolation() method.
  com.triactive.jdo.ResultSetType	"forward only" "scroll insensitive" "scroll sensitive"	"scroll insensitive"	Selects the default JDBC result set type for all PersistenceManagerFactories. The values are case-insensitive, and spaces and underscores are equivalent. Can be overridden for individual PersistenceManagerFactories or individual Transactions using the setResultSetType() method.
  com.triactive.jdo.FetchSize	Integer ≥ 0	0	Selects the default JDBC fetch size for all PersistenceManagerFactories. Zero means no specific size. Can be overridden for individual PersistenceManagerFactories or individual Transactions using the setFetchSize() method.
  com.triactive.jdo.ForceConnectionInit	"true" "false"	"false"	Selects whether to forcibly initialize every JDBC connection obtained from your underlying DataSource. If enabled, setAutoCommit() and setTransactionIsolationLevel() are called on every connection before use. Otherwise, they're called only if the required setting differs from the connection's default setting. If your DataSource config results in InconsistentConnectionStateExceptions, set this to "true" to compensate.
  com.triactive.jdo.JdbcTrace	See Tracing	null	Controls the JDBC trace facility. The value is a comma-separated list of tracing options. An empty string disables tracing.

• The second group can only be provided as system properties. They are rarely used, and may be replaced or removed in future versions.

  Configuration Properties - system

  Property	Possible Values	Default Value	Purpose
  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	Integer > 0	"3"	A few internal JDO operations execute a transaction with SERIALIZABLE isolation, independent of the configured transactionIsolation. These transactions can produce concurrency collisions (such as "ORA-08177: can't serialize access for this transaction"), in which case they are retried. This property specifies the maximum number of attempts (including the first attempt).
  com.triactive.jdo.store.schemaIdleExpirationHours	Integer > 0	"24"	The amount of time in hours after which knowledge of a specific database schema is considered stale and eligible for discarding. Discarding is equivalent to SchemaManager.reset(). Default is 24 hours.
  com.triactive.jdo.store.timeDiffTolerance	Integer ≥ 0	"10000"	The amount of time difference tolerated between this host and the database, in milliseconds. If the difference exceeds this value a warning is logged. Ignored if the database cannot provide a current timestamp. Default is 10 seconds.

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 (sample.log4j.properties) 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):