SolarMetric Kodo™ JDO 3.0 Developers Guide

Table of Contents

I. Introduction

1. SolarMetric Kodo JDO

1.1. About This Document

II. Java Data Objects

1. Introduction

1.1. Intended Audience

1.2. Transparent Persistence

2. Why JDO?

3. JDO Architecture

3.1. JDO Exceptions

4. PersistenceCapable

4.1. JDO Enhancer

4.2. Persistence-Capable vs. Persistence-Aware

4.3. Restrictions on Persistent Classes

4.3.1. Inheritance

4.3.2. Persistent Fields

4.3.3. Conclusions

4.4. InstanceCallbacks

4.5. JDO Identity

4.5.1. Datastore Identity

4.5.2. Application Identity

4.6. Conclusions

5. Metadata

5.1. Metadata DTD

5.2. Metadata Placement

6. JDOHelper

6.1. Persistence-Capable Operations

6.2. Lifecycle Operations

6.3. PersistenceManagerFactory Construction

7. PersistenceManagerFactory

7.1. Obtaining a PersistenceManagerFactory

7.2. PersistenceManagerFactory Properties

7.2.1. Connection Configuration

7.2.2. PersistenceManagerFactory and Transaction Defaults

7.3. Obtaining PersistenceManagers

7.4. Properties and Supported Options

8. PersistenceManager

8.1. User Object Association

8.2. Configuration Properties

8.3. Transaction Association

8.4. Persistence-Capable Lifecycle Management

8.5. Lifecycle Examples

8.6. JDO Identity Management

8.7. Extent Factory

8.8. Query Factory

8.9. Closing

9. Transaction

9.1. Transaction Types

9.2. The JDO Transaction Interface

10. Extent

11. Query

11.1. Required Query Elements

11.2. Optional Query Elements

11.3. JDOQL

11.4. Executing Queries

11.5. Query Compilation

12. Conclusion

III. Kodo JDO Tutorials

1. Kodo JDO Tutorials

1.1. Tutorial Requirements

2. Kodo JDO Tutorial

2.1. The Pet Shop

2.1.1. Included Files

2.1.2. Important Utilities

2.2. Getting Started

2.2.1. Configuring the Data Store

2.3. Inventory Maintenance

2.3.1. Persisting Objects

2.3.2. Deleting Objects

2.4. Inventory Growth

2.5. Behavioral Analysis

2.5.1. Complex Queries

2.6. Extra Features

3. Reverse Mapping Tool Tutorial

3.1. Magazine Shop

3.2. Setup

3.2.1. Tutorial Files

3.2.2. Important Utilities

3.3. Generating Persistent Classes

3.4. Using the Finder

4. J2EE Tutorial

4.1. Prerequisites for the Kodo J2EE Tutorial

4.2. J2EE Installation Types

4.3. Installing Kodo JCA

4.3.1. JBoss 3.0

4.3.2. JBoss 3.2

4.3.3. WebLogic 6.2 and Higher

4.3.4. WebSphere 5

4.3.5. SunONE Application Server

4.4. Installing the J2EE Sample Application

4.4.1. Compiling and Building The Sample Application

4.4.2. Deploying Sample To JBoss

4.4.3. Deploying Sample To WebLogic

4.4.4. Deploying Sample To SunONE

4.4.5. Deploying Sample To WebSphere

4.5. Using The Sample Application

4.6. Sample Architecture

4.7. Code Notes and J2EE Tips

IV. Kodo JDO Reference Guide

1. Introduction

1.1. Intended Audience

2. Configuration

2.1. Introduction

2.2. Runtime Configuration

2.3. Command Line Configuration

2.3.1. Code Formatting

2.4. Plugin Configuration

2.5. JDO Standard Properties

2.5.1. javax.jdo.PersistenceManagerFactoryClass

2.5.2. javax.jdo.option.ConnectionDriverName

2.5.3. javax.jdo.option.ConnectionFactoryName

2.5.4. javax.jdo.option.ConnectionFactory2Name

2.5.5. javax.jdo.option.ConnectionPassword

2.5.6. javax.jdo.option.ConnectionURL

2.5.7. javax.jdo.option.ConnectionUserName

2.5.8. javax.jdo.option.IgnoreCache

2.5.9. javax.jdo.option.Multithreaded

2.5.10. javax.jdo.option.NontransactionalRead

2.5.11. javax.jdo.option.NontransactionalWrite

2.5.12. javax.jdo.option.Optimistic

2.5.13. javax.jdo.option.RestoreValues

2.5.14. javax.jdo.option.RetainValues

2.6. Kodo JDO Properties

2.6.1. kodo.ClassResolverClass

2.6.2. kodo.ClassResolverProperties

2.6.3. kodo.ConnectionProperties

2.6.4. kodo.ConnectionFactoryProperties

2.6.5. kodo.Connection2DriverName

2.6.6. kodo.Connection2Password

2.6.7. kodo.Connection2URL

2.6.8. kodo.Connection2UserName

2.6.9. kodo.Connection2Properties

2.6.10. kodo.ConnectionFactory2Properties

2.6.11. kodo.ConnectionRetainMode

2.6.12. kodo.DataCacheClass

2.6.13. kodo.DataCacheProperties

2.6.14. kodo.DataCacheTimeout

2.6.15. kodo.EagerFetchMode

2.6.16. kodo.FetchBatchSize

2.6.17. kodo.FetchGroups

2.6.18. kodo.FetchThreshold

2.6.19. kodo.FilterListenerClasses

2.6.20. kodo.FilterListenerProperties

2.6.21. kodo.FlushBeforeQueries

2.6.22. kodo.LicenseKey

2.6.23. kodo.ManagedRuntimeClass

2.6.24. kodo.ManagedRuntimeProperties

2.6.25. kodo.PersistenceManagerClass

2.6.26. kodo.PersistenceManagerProperties

2.6.27. kodo.PersistentClasses

2.6.28. kodo.ProxyManagerClass

2.6.29. kodo.ProxyManagerProperties

2.6.30. kodo.QueryCacheClass

2.6.31. kodo.QueryCacheProperties

2.6.32. kodo.RemoteCommitProviderClass

2.6.33. kodo.RemoteCommitProviderProperties

2.6.34. kodo.ResultListClass

2.6.35. kodo.ResultListProperties

2.6.36. kodo.TransactionMode

2.6.37. kodo.jdbc.AutoIncrementConstraints

2.6.38. kodo.jdbc.ClassIndicatorClass

2.6.39. kodo.jdbc.ConnectionDecoratorClasses

2.6.40. kodo.jdbc.ConnectionDecoratorProperties

2.6.41. kodo.jdbc.DBDictionaryClass

2.6.42. kodo.jdbc.DBDictionaryProperties

2.6.43. kodo.jdbc.ForeignKeyConstraints

2.6.44. kodo.jdbc.JDBCListenerClasses

2.6.45. kodo.jdbc.JDBCListenerProperties

2.6.46. kodo.jdbc.MappingFactoryClass

2.6.47. kodo.jdbc.MappingFactoryProperties

2.6.48. kodo.jdbc.SchemaFactoryClass

2.6.49. kodo.jdbc.SchemaFactoryProperties

2.6.50. kodo.jdbc.Schemas

2.6.51. kodo.jdbc.SequenceFactoryClass

2.6.52. kodo.jdbc.SequenceFactoryProperties

2.6.53. kodo.jdbc.SubclassMappingClass

2.6.54. kodo.jdbc.TransactionIsolation

2.6.55. kodo.jdbc.UpdateManagerClass

2.6.56. kodo.jdbc.UpdateManagerProperties

2.6.57. kodo.jdbc.VersionIndicatorClass

3. Logging

3.1. Logging Channels

3.2. Log4J

3.3. JDK 1.4 java.util.logging

3.4. Simple Log

3.5. Custom Log

4. JDBC

4.1. Using the Kodo JDO DataSource

4.2. Using a Third-Party DataSource

4.3. Database Support

4.4. Accessing Multiple Databases

4.5. Setting the Transaction Isolation

4.6. Setting the SQL Join Syntax

4.7. Configuring the Use of JDBC Connections

4.8. Runtime Access to JDBC Connections

4.9. Large Result Sets

4.10. SQL Statement Ordering & Foreign Keys

5. Persistent Classes

5.1. Restrictions on Persistent Classes

5.2. Object Identity

5.2.1. Datastore Identity

5.2.2. Application Identity

5.2.3. Primary Key Generation

5.2.3.1. Sequence Factory

5.2.3.2. Auto-Increment

5.3. Enhancement

5.4. Auto-Generating Classes from a Schema

5.4.1. Customizing Reverse Mapping

6. Metadata

6.1. Generating Default JDO Metadata

6.2. JDO Metadata Extensions

6.2.1. Relation Extensions

6.2.1.1. inverse-owner

6.2.1.2. dependent

6.2.1.3. element-dependent

6.2.1.4. value-dependent

6.2.1.5. key-dependent

6.2.1.6. pc-class

6.2.1.7. element-pc-class

6.2.1.8. value-pc-class

6.2.1.9. key-pc-class

6.2.1.10. Example

6.2.2. Schema Extensions

6.2.2.1. jdbc-size

6.2.2.2. jdbc-element-size

6.2.2.3. jdbc-value-size

6.2.2.4. jdbc-key-size

6.2.2.5. jdbc-indexed

6.2.2.6. jdbc-element-indexed

6.2.2.7. jdbc-value-indexed

6.2.2.8. jdbc-key-indexed

6.2.2.9. jdbc-ref-indexed

6.2.2.10. jdbc-delete-action

6.2.2.11. jdbc-element-delete-action

6.2.2.12. jdbc-value-delete-action

6.2.2.13. jdbc-key-delete-action

6.2.2.14. jdbc-ref-delete-action

6.2.2.15. Example

6.2.3. Object-Relational Mapping Extensions

6.2.3.1. jdbc-use-class-map

6.2.3.2. jdbc-use-version-ind

6.2.3.3. jdbc-use-class-ind

6.2.3.4. jdbc-use-field-map

6.2.3.5. jdbc-ordered

6.2.3.6. jdbc-container-meta

6.2.3.7. jdbc-null-ind

6.2.3.8. jdbc-externalizer

6.2.3.9. jdbc-factory

6.2.3.10. jdbc-class-ind-value

6.2.3.11. Example

6.2.4. Miscellaneous Extensions

6.2.4.1. fetch-group

6.2.4.2. data-cache-timeout

6.2.4.3. data-cache-name

6.2.4.4. jdbc-sequence-factory-class

6.2.4.5. jdbc-sequence-factory-properties

6.2.4.6. jdbc-sequence-name

6.2.4.7. jdbc-auto-increment

6.2.4.8. Example

7. Object-Relational Mapping

7.1. Mapping Tool

7.1.1. Using the Mapping Tool

7.2. Mapping Factory

7.2.1. Importing and Exporting Mapping Data

7.3. Mapping File XML Format

7.4. Mapping Notes

7.4.1. Join Attributes

7.4.2. Non-Standard Joins

7.5. Class Mapping

7.5.1. Base Mapping

7.5.2. Flat Mapping

7.5.3. Vertical Mapping

7.5.4. Custom Class Mapping

7.6. Version Indicator

7.6.1. Version Number Indicator

7.6.2. Version Date Indicator

7.6.3. State Image Indicator

7.6.4. Custom Version Indicator

7.7. Class Indicator

7.7.1. In-Class-Name Indicator

7.7.2. Metadata Value Indicator

7.7.3. Custom Class Indicator

7.8. Field Mapping

7.8.1. Value Mapping

7.8.2. Blob Mapping

7.8.3. Clob Mapping

7.8.4. Stringification Mapping

7.8.5. One-to-One Mapping

7.8.6. PC One-to-One Mapping

7.8.7. Embedded One-to-One Mapping

7.8.8. Collection Mapping

7.8.9. Many-to-Many Mapping

7.8.10. One-to-Many Mapping

7.8.11. PC Collection Mapping

7.8.12. Map Mapping

7.8.13. N-to-Many Map Mapping

7.8.14. Many-to-N Map Mapping

7.8.15. Many-to-Many Map Mapping

7.8.16. PC Map Mapping

7.8.17. N-to-PC Map Mapping

7.8.18. PC-to-N Map Mapping

7.8.19. PC-to-Many Map Mapping

7.8.20. Many-to-PC Map Mapping

7.8.21. Custom Field Mapping

8. Schema Manipulation

8.1. Schema Information

8.1.1. Schema Factory

8.1.2. Schema Generator

8.2. Schema Tool

8.3. XML Schema Format

9. Runtime Deployment

9.1. JDOHelper

9.2. J2EE Deployment

9.3. Using Kodo JDO via the Java Connector Architecture

9.3.1. Deploying on JBoss 3.0

10. JDO Runtime Extensions

10.1. KodoPersistenceManagerFactory

10.2. KodoPersistenceManager

10.2.1. JDO Events

10.2.2. PersistenceManager Extension

10.3. KodoExtent

10.4. KodoQuery

10.5. Fetch Configuration

10.6. SCO Proxies

10.6.1. Smart Proxies

10.6.2. Custom Proxies

11. Enterprise Edition

11.1. Integrating with the Transaction Manager

11.2. XA Transactions

11.2.1. Requirements for Using Kodo with XA Transactions

11.2.2. Configuring Kodo to Utilize XA Transactions

12. Performance Pack

12.1. SQL Batching

12.2. Eager Fetching

12.2.1. Configuring Eager Fetching

12.3. Datastore Cache

12.3.1. Overview of Kodo JDO Datastore Caching

12.3.2. Kodo JDO Cache Usage

12.3.3. Query Caching

12.3.4. Data Cache Configuration

12.3.5. Tangosol Integration

12.3.6. Cache Extension

12.3.7. Important Notes

12.3.8. Known Issues and Limitations

12.4. Remote Event Notification Framework

12.4.1. Remote Commit Provider Configuration

12.4.2. Customization

12.5. Fetch Groups

12.5.1. Normal Default Fetch Group Behavior

12.5.2. Kodo JDO Fetch Group Behavior

12.5.3. Custom Fetch Group Configuration

12.6. Query Extensions

12.6.1. Using Query Extensions

12.6.2. Included Query Extensions

12.6.3. Developing Custom Query Extensions

12.6.4. Configuring Query Extensions

13. Third Party Integration

13.1. Overview of Third Party Integration features in Kodo

13.2. Apache Ant

13.2.1. Common Ant Configuration Options

13.2.2. JDO Enhancer Ant Task

13.2.3. Application Identity Tool Ant Task

13.2.4. JDO Metadata Tool Ant Task

13.2.5. Mapping Tool Ant Task

13.2.6. Reverse Mapping Tool Ant Task

13.2.7. Schema Tool Ant Task

13.2.8. Schema Generator Ant Task

14. Optimization Techniques

A. JDO Resources

B. Supported Databases

B.1. Example properties for IBM DB2

B.2. Example properties for Hypersonic

B.3. Example properties for Informix Dynamic Server

B.4. Example properties for Microsoft SQLServer

B.5. Example properties for MySQL

B.6. Example properties for Oracle

B.7. Example properties for Pointbase

B.8. Example properties for PostgreSQL

B.9. Example properties for Sybase

C. Common Database Errors

D. Migrating from Kodo 2 to Kodo 3

D.1. Source Code Migration

D.1.1. Package Structure Changes

D.1.2. API Changes

D.2. JDO Metadata Migration

D.3. Properties File Migration

D.4. Storing Object-Relational Mapping Data

D.5. Kodo 3 Development Process

E. Implementation Notes

E.1. jdoFlags Fields in the Default Fetch Group

F. Development and Runtime Libraries

G. Release Notes

H. Known Bugs and Limitations