SolarMetric Kodo™ JDO 2.5.8 Developers Guide

Table of Contents

I. Introduction

1. Introduction to SolarMetric Kodo JDO

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

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.2.3. PersistenceManager Pooling

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. JDO Identity Management

8.6. Extent Factory

8.7. Query Factory

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

III. Kodo JDO Reference Guide

1. Introduction

1.1. Intended Audience

2. Configuration Framework

2.1. JDO Standard Properties

2.1.1. javax.jdo.PersistenceManagerFactoryClass

2.1.2. javax.jdo.option.Optimistic

2.1.3. javax.jdo.option.Multithreaded

2.1.4. javax.jdo.option.IgnoreCache

2.1.5. javax.jdo.option.RetainValues

2.1.6. javax.jdo.option.RestoreValues

2.1.7. javax.jdo.option.NontransactionalRead

2.1.8. javax.jdo.option.NontransactionalWrite

2.1.9. javax.jdo.option.ConnectionURL

2.1.10. javax.jdo.option.ConnectionUserName

2.1.11. javax.jdo.option.ConnectionPassword

2.1.12. javax.jdo.option.ConnectionDriverName

2.1.13. javax.jdo.option.ConnectionFactoryName

2.1.14. javax.jdo.option.ConnectionFactory2Name

2.1.15. javax.jdo.option.MinPool

2.1.16. javax.jdo.option.MaxPool

2.1.17. javax.jdo.option.MsWait

2.2. Kodo JDO Properties

2.2.1. com.solarmetric.kodo.CacheReferenceSize

2.2.2. com.solarmetric.kodo.ConnectionProperties

2.2.3. com.solarmetric.kodo.DataCacheClass

2.2.4. com.solarmetric.kodo.DataCacheProperties

2.2.5. com.solarmetric.kodo.RemoteCommitProviderClass

2.2.6. com.solarmetric.kodo.RemoteCommitProviderProperties

2.2.7. com.solarmetric.kodo.DefaultDataCacheTimeout

2.2.8. com.solarmetric.kodo.DefaultFetchThreshold

2.2.9. com.solarmetric.kodo.DefaultFetchBatchSize

2.2.10. com.solarmetric.kodo.EnableQueryExtensions

2.2.11. com.solarmetric.kodo.FetchGroups

2.2.12. com.solarmetric.kodo.FlushBeforeQueries

2.2.13. com.solarmetric.kodo.LicenseKey

2.2.14. com.solarmetric.kodo.PersistenceManagerClass

2.2.15. com.solarmetric.kodo.PersistenceManagerProperties

2.2.16. com.solarmetric.kodo.ProxyManagerClass

2.2.17. com.solarmetric.kodo.ProxyManagerProperties

2.2.18. com.solarmetric.kodo.QueryCacheClass

2.2.19. com.solarmetric.kodo.QueryCacheProperties

2.2.20. com.solarmetric.kodo.QueryFilterListeners

2.2.21. com.solarmetric.kodo.ResultListClass

2.2.22. com.solarmetric.kodo.ResultListProperties

2.2.23. com.solarmetric.kodo.TransactionCacheClass

2.2.24. com.solarmetric.kodo.TransactionCacheProperties

2.2.25. com.solarmetric.kodo.UseSoftTransactionCache

2.2.26. com.solarmetric.kodo.PersistentTypes

2.2.27. com.solarmetric.kodo.TransactionMode

2.2.28. com.solarmetric.kodo.ConnectionFactory2Properties

2.2.29. com.solarmetric.kodo.impl.jdbc.ConnectionRetainMode

2.2.30. com.solarmetric.kodo.impl.jdbc.ConnectionTestTimeout

2.2.31. com.solarmetric.kodo.impl.jdbc.DefaultClassMappingClass

2.2.32. com.solarmetric.kodo.impl.jdbc.DefaultSubclassProviderClass

2.2.33. com.solarmetric.kodo.impl.jdbc.DefaultSubclassProviderProperties

2.2.34. com.solarmetric.kodo.impl.jdbc.DictionaryClass

2.2.35. com.solarmetric.kodo.impl.jdbc.DictionaryProperties

2.2.36. com.solarmetric.kodo.impl.jdbc.FlatInheritanceMapping

2.2.37. com.solarmetric.kodo.impl.jdbc.SequenceFactoryClass

2.2.38. com.solarmetric.kodo.impl.jdbc.SequenceFactoryProperties

2.2.39. com.solarmetric.kodo.impl.jdbc.SQLExecutionManagerClass

2.2.40. com.solarmetric.kodo.impl.jdbc.SQLExecutionListenerClass

2.2.41. com.solarmetric.kodo.impl.jdbc.StatementCacheMaxSize

2.2.42. com.solarmetric.kodo.impl.jdbc.StatementExecutionTimeout

2.2.43. com.solarmetric.kodo.impl.jdbc.SynchronizeSchema

2.2.44. com.solarmetric.kodo.impl.jdbc.TransactionIsolation

2.2.45. com.solarmetric.kodo.impl.jdbc.UseBatchedStatements

2.2.46. com.solarmetric.kodo.impl.jdbc.UseSQL92Joins

2.2.47. com.solarmetric.kodo.impl.jdbc.WarnOnPersistentTypeFailure

2.2.48. com.solarmetric.kodo.ee.ManagedRuntimeClass

2.2.49. com.solarmetric.kodo.ee.ManagedRuntimeProperties

2.3. Logging Framework

2.3.1. Disabling Logging

2.3.2. Logging using Apache Log4J

2.3.3. Logging using JDK 1.4 java.util.logging

2.3.4. Logging using Simple Log

2.3.5. Logging using a Custom Log

3. Creating Persistent Classes

3.1. Application Identity Class Generation

3.2. Enhancement

3.3. Auto-Generating Classes from a Schema

3.3.1. Customizing Reverse Mapping

3.3.2. Formatting Reverse Mapping Code

3.3.3. Schema File DTD

3.4. Smart Proxies

4. Metadata

4.1. Dependency Extensions

4.1.1. dependent

4.1.2. element-dependent

4.1.3. value-dependent

4.1.4. key-dependent

4.2. Class-level Object-Relational Mapping Extensions

4.2.1. table

4.2.2. pk-column

4.2.3. lock-column

4.2.4. class-column

4.2.5. subclass-provider

4.2.6. subclass-indicator-value

4.2.7. custom-mapping

4.2.8. can-cache

4.2.9. data-cache-name

4.2.10. cache-timeout

4.2.11. sequence-factory-class

4.2.12. sequence

4.2.13. sequence-factory-properties

4.3. Field-level Object-Relational Mapping Extensions

4.3.1. dependent

4.3.2. element-dependent

4.3.3. value-dependent

4.3.4. key-dependent

4.3.5. inverse

4.3.6. blob

4.3.7. column-length

4.3.8. column-index

4.3.9. ordered

4.3.10. table

4.3.11. data-column

4.3.12. key-column

4.3.13. ref-column

4.3.14. order-column

4.3.15. read-only

4.3.16. <tablename>-pk-column

4.3.17. fetch-group

4.3.18. custom-mapping

4.3.19. externalizer

4.3.20. factory

4.4. Extensions Under Application Identity

4.5. Examples

4.5.1. Mapping Classes to an Existing Schema

4.5.2. Mapping One to Many relations

4.5.3. Extensions Under Application Identity

4.6. Multi-table Inheritance Mapping

4.7. Generating Default JDO Metadata

5. JDBC Configuration

5.1. Supported Databases

5.2. Accessing Multiple Databases

5.3. Connection Management

5.4. Large Result Sets

5.5. Schema Manipulation

6. Standard Features

6.1. Manipulating Datastore Identity Objects

6.2. ExtentImpl

6.3. PersistenceManager Extension

6.4. Event Notification Framework

6.4.1. Transaction Event Notification

6.4.2. Remote Commit Notification

6.5. Custom Proxies

6.6. Access to SQL Connections

6.7. PersistenceManagerImpl.evictAll() API extensions

6.8. Custom Class Indicators

6.9. Storing Second Class Objects via Stringification

6.10. Primary Key Generation

6.10.1. Using table-based key generation

6.10.2. Using Database Sequences for key generation

6.11. StateManagerSet configuration

7. Enterprise Features

7.1. Datastore Cache

7.1.1. Overview of Kodo JDO Datastore Caching

7.1.2. Kodo JDO Cache Usage

7.1.3. Kodo JDO Query Caching

7.1.4. Kodo JDO Data Cache Configuration

7.1.5. Cache Extension

7.1.6. Important notes about the DataCache

7.1.7. Known issues and limitations

7.2. Query Extensions

7.2.1. Using Query Extensions

7.2.2. Included Query Extensions

7.2.3. Deprecated Query Extensions

7.2.4. Developing Custom Query Extensions

7.2.5. Configuring Query Extensions

7.3. Fetch Groups

7.3.1. Normal Default Fetch Group Behavior

7.3.2. Kodo JDO Fetch Group Behavior

7.3.3. Configuring a PersistenceManager to load Fetch Groups

7.4. XA Transactions

7.4.1. Overview of XA Distributed Transaction Processing

7.4.2. Requirements for using Kodo with XA transactions

7.4.3. Configuring Kodo to utilize XA transactions

7.5. Remote Commit Notification Framework

7.5.1. Kodo JDO RemoteCommitProvider Configuration

7.5.2. Event Notification Framework Customization

8. Additional Features

8.1. Custom data processing

8.2. Custom data requests

9. Third Party Integration Features

9.1. Overview of Third Party Integration features in Kodo

9.2. Apache Ant

9.2.1. Common Ant Configuration Options

9.2.2. JDOEnhancer Ant Task

9.2.3. SchemaTool Ant Task

9.3. XDoclet

9.4. Borland JBuilder

9.4.1. Installing Kodo into JBuilder

9.4.2. Kodo Configuration from JBuilder

9.4.3. Creating and building JDO projects in JBuilder

9.4.4. Editing JDO Metadata from JBuilder

9.4.5. Running the SchemaTool from JBuilder

9.4.6. JBuilder Project Sample

9.5. Sun ONE Studio / NetBeans IDE

9.5.1. Before Installing Kodo into the IDE

9.5.2. Installing Kodo into the IDE

9.5.3. Configuring the Kodo Module

9.5.4. Kodo Template Wizards

9.5.5. JDO DataObject

9.5.6. Kodo Integration into the Build Process

9.5.7. SunONE / NetBeans Sample

9.6. Eclipse / WebSphere Studio Integration

9.6.1. Installing the Kodo Eclipse Plugin

9.6.2. Configuring the Plugin

9.6.3. Using Kodo in Eclipse IDEs

9.6.4. Eclipse Sample

10. Enterprise Integration

10.1. Overview of Enterprise Integration features in Kodo

10.2. Using Kodo JDO via the Java Connector Architecture

10.2.1. Overview of the JCA

10.2.2. Deploying on JBoss 3.0

11. Kodo JDO Implementation Notes

11.1. PersistenceCapable.jdoFlags field and fields in the Default Fetch Group

11.2. Optimistic locking mechanism

12. Optimization Techniques

IV. Kodo JDO Tutorial

Introduction to the Kodo JDO Tutorial

1. Tutorial Requirements

1. The Pet Shop

1.1. Included Files

1.2. Important Utilities

2. Getting Started

3. Inventory Maintenance

4. Inventory Growth

5. Behavioral Analysis

6. Extra Features

V. Kodo J2EE Tutorial

Introduction to the J2EE Tutorial

1. Prerequisites for the Kodo J2EE Tutorial

1. J2EE Installation Types

2. Installing Kodo JCA

2.1. JBoss 3.0

2.2. JBoss 3.2

2.3. WebLogic Versions 6.2 to 7.x

2.4. WebLogic 8.1

2.5. WebSphere 5

2.6. SunONE Application Server

2.7. Borland Enterprise Server 5.2

3. Installing the J2EE Sample Application

3.1. Compiling and Building The Sample Application

3.2. Deploying Sample To JBoss

3.3. Deploying Sample To WebLogic 6.2 to 7.x

3.4. Deploying Sample To WebLogic 8.1

3.5. Deploying Sample To SunONE

3.6. Deploying Sample To WebSphere

3.7. Deploying Sample To Borland Enterprise Server 5.2

4. Using The Sample Application

5. Sample Architecture

6. Code Notes and J2EE Tips

VI. Reverse Mapping Tool Tutorial

Introduction to the Reverse Mapping Tool Tutorial

1. Reverse Mapping Tool Tutorial Requirements

1. Magazine Shop

2. Setup

2.1. Tutorial Files

2.2. Important Utilities

3. Generating Persistent Classes

4. Using the Finder

A. Development and Runtime Libraries

B. JDO Resources

C. Optional JDO Features

D. SQL Types

E. Release Notes

F. Known Bugs and Limitations

G. Supported Databases

G.1. Example properties for Pointbase

G.2. Example properties for IBM DB2

G.3. Example properties for Informix Dynamic Server

G.4. Example properties for Oracle

G.5. Example properties for PostgreSQL

G.6. Example properties for SQLServer

G.7. Example properties for Sybase

G.8. Example properties for Hypersonic

G.9. Example properties for MySQL

H. Common Database Errors