SolarMetric Kodo JDO 3.0.3 Developers Guide
		Next

SolarMetric Kodo™ JDO 3.0.3 Developers Guide

Table of Contents

I. Introduction

1. SolarMetric Kodo JDO

1.1. About This Document

2. SolarMetric Kodo JDO Installation

2.1. Overview
2.2. Updates
2.3. Key Files in the download
2.4. Quick Start
2.5. Upgrading from Kodo 2
2.6. Requirements
2.7. Terminology
2.8. Windows Installation (installer)
2.9. Windows Installation (no installer -- zip file)
2.10. POSIX (Linux, Solaris, Mac OS X, Windows with cygwin, etc.) Installation
2.11. Borland JBuilder
2.12. Installing Kodo into JBuilder
2.13. Common installation problems
2.14. Resources
2.15. Sales Inquiries

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. Default No-Arg Constructor
4.3.2. Inheritance
4.3.3. Persistent Fields
4.3.4. 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. PersistenceManager 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 to 7.x
4.3.4. WebLogic 8.1
4.3.5. WebSphere 5
4.3.6. SunONE Application Server
4.3.7. Macromedia JRun 4
4.3.8. Borland Enterprise Server 5.2

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 6.2 to 7.x
4.4.4. Deploying Sample To WebLogic 8.1
4.4.5. Deploying Sample To SunONE
4.4.6. Deploying Sample To JRun
4.4.7. Deploying Sample To WebSphere
4.4.8. Deploying Sample To Borland Enterprise Server 5.2

4.5. Using The Sample Application

4.6. Sample Architecture

4.7. Code Notes and J2EE Tips

IV. Kodo JDO Frequently Asked Questions

1. Kodo JDO Frequently Asked Questions

1.1. General
1.2. Database
1.3. Programming with Kodo
1.4. How do I ... ?
1.5. Common errors
1.6. Productivity tools
1.7. Performance
1.8. Scalability
1.9. Application servers
1.10. Locking
1.11. Transactions

V. 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.AggregateListeners
2.6.2. kodo.ClassResolver
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.CopyObjectIds
2.6.13. kodo.DataCache
2.6.14. kodo.DataCacheTimeout
2.6.15. kodo.EagerFetchMode
2.6.16. kodo.FetchBatchSize
2.6.17. kodo.FetchGroups
2.6.18. kodo.FilterListeners
2.6.19. kodo.FlushBeforeQueries
2.6.20. kodo.LicenseKey
2.6.21. kodo.ManagedRuntime
2.6.22. kodo.ManagementServer
2.6.23. kodo.ManagementUI
2.6.24. kodo.PersistenceManagerImpl
2.6.25. kodo.PersistentClasses
2.6.26. kodo.ProxyManager
2.6.27. kodo.QueryCache
2.6.28. kodo.QueryCompilationCache
2.6.29. kodo.RemoteCommitProvider
2.6.30. kodo.RestoreMutableValues
2.6.31. kodo.RetainValuesInOptimistic
2.6.32. kodo.TransactionMode
2.6.33. kodo.jdbc.AutoIncrementConstraints
2.6.34. kodo.jdbc.ClassIndicator
2.6.35. kodo.jdbc.ConnectionDecorators
2.6.36. kodo.jdbc.DataSourceMode
2.6.37. kodo.jdbc.DBDictionary
2.6.38. kodo.jdbc.FetchDirection
2.6.39. kodo.jdbc.ForeignKeyConstraints
2.6.40. kodo.jdbc.JDBCListeners
2.6.41. kodo.jdbc.LRSSize
2.6.42. kodo.jdbc.MappingFactory
2.6.43. kodo.jdbc.ResultSetType
2.6.44. kodo.jdbc.SchemaFactory
2.6.45. kodo.jdbc.Schemas
2.6.46. kodo.jdbc.SequenceFactory
2.6.47. kodo.jdbc.SubclassMapping
2.6.48. kodo.jdbc.TransactionIsolation
2.6.49. kodo.jdbc.UpdateManager
2.6.50. kodo.jdbc.VersionIndicator

3. Logging

3.1. Logging Channels
3.2. Disabling Logging
3.3. Log4J
3.4. JDK 1.4 java.util.logging
3.5. Simple Log
3.6. Custom Log

4. JDBC

4.1. Using the Kodo JDO DataSource

4.2. Using a Third-Party DataSource

4.2.1. Enlisted Data Sources

4.3. Database Support

4.3.1. MySQLDictionary parameters
4.3.2. OracleDictionary parameters

4.4. Configuing the DBDictionary

4.5. Accessing Multiple Databases

4.6. Setting the Transaction Isolation

4.7. Setting the SQL Join Syntax

4.8. Configuring the Use of JDBC Connections

4.9. Runtime Access to JDBC Connections

4.10. Large Result Sets

4.11. 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. Mutable Second Class Object Fields

5.3.1. Restoring Mutable Fields

5.3.2. Typing and Ordering

5.3.3. Proxies

5.3.3.1. Smart Proxies
5.3.3.2. Large Result Set Proxies
5.3.3.3. Custom Proxies

5.4. Enhancement

5.5. Auto-Generating Classes from a Schema

5.5.1. Customizing Reverse Mapping

5.6. Persistent Class List

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. type
6.2.1.7. element-type
6.2.1.8. value-type
6.2.1.9. key-type
6.2.1.10. lrs
6.2.1.11. 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-version-ind-indexed
6.2.2.11. jdbc-class-ind-indexed
6.2.2.12. jdbc-delete-action
6.2.2.13. jdbc-element-delete-action
6.2.2.14. jdbc-value-delete-action
6.2.2.15. jdbc-key-delete-action
6.2.2.16. jdbc-ref-delete-action
6.2.2.17. Example

6.2.3. Object-Relational Mapping Extensions

6.2.3.1. jdbc-class-map-name
6.2.3.2. jdbc-version-ind-name
6.2.3.3. jdbc-class-ind-name
6.2.3.4. jdbc-field-map-name
6.2.3.5. jdbc-ordered
6.2.3.6. jdbc-container-meta
6.2.3.7. jdbc-null-ind
6.2.3.8. externalizer
6.2.3.9. 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
6.2.4.3. data-cache-timeout
6.2.4.4. jdbc-sequence-factory
6.2.4.5. jdbc-sequence-name
6.2.4.6. jdbc-auto-increment
6.2.4.7. 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. Byte Array 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
7.8.22. Externalization

8. Schema Information

8.1. Schema Reflection

8.1.1. Schemas List
8.1.2. Schema Factory
8.1.3. Schema Generator

8.2. Schema Tool

8.3. XML Schema Format

8.4. The SQLLine Utility

9. Runtime Deployment

9.1. JDOHelper

9.2. KodoHelper

9.3. J2EE Deployment

9.4. Using Kodo JDO via the Java Connector Architecture

9.4.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. KodoHelper

10.7. Query Extensions

10.7.1. JDOQL Extensions

10.7.1.1. Included Query Extensions
10.7.1.2. Developing Custom Query Extensions
10.7.1.3. Configuring JDOQL Extensions

10.8. Query Aggregates and Projections

10.8.1. Query Aggregates

10.8.1.1. Using Query Aggregates

10.8.1.2. Included Query Aggregates

10.8.1.2.1. count
10.8.1.2.2. sum
10.8.1.2.3. min
10.8.1.2.4. max
10.8.1.2.5. avg

10.8.1.3. Developing Custom Query Aggregates

10.8.1.4. Configuring Query Aggregates

10.8.2. Query Projections

10.8.2.1. Using Query Projections

10.8.3. JDOQL Variables in Aggregates and Projections

10.8.4. Custom Query Result Class

10.8.4.1. Using a Bean Query Result Class
10.8.4.2. Using a Generic Query Result Class
10.8.4.3. Using a Result Alias

11. Detach and Attach

11.1. Configuring detachability
11.2. Detachable behavior
11.3. Detach and Attach Callbacks

12. Management and Monitoring

12.1. Configuring Local Management / Monitoring
12.2. Configuring Remote Management / Monitoring
12.3. Configuring Logging for Management / Monitoring

13. Enterprise Edition

13.1. Integrating with the Transaction Manager

13.2. XA Transactions

13.2.1. Requirements for Using Kodo with XA Transactions
13.2.2. Configuring Kodo to Utilize XA Transactions

13.3. Direct SQL Execution

13.4. MethodQL

14. Performance Pack

14.1. SQL Batching

14.2. Eager Fetching

14.2.1. Configuring Eager Fetching
14.2.2. Eager Fetching Considerations

14.3. Datastore Cache

14.3.1. Overview of Kodo JDO Datastore Caching
14.3.2. Kodo JDO Cache Usage
14.3.3. Query Caching
14.3.4. Tangosol Integration
14.3.5. Cache Extension
14.3.6. Important Notes
14.3.7. Known Issues and Limitations

14.4. Remote Event Notification Framework

14.4.1. Remote Commit Provider Configuration
14.4.2. Customization

14.5. Fetch Groups

14.5.1. Normal Default Fetch Group Behavior
14.5.2. Kodo JDO Fetch Group Behavior
14.5.3. Custom Fetch Group Configuration

15. Third Party Integration

15.1. Overview of Third Party Integration features in Kodo

15.2. Apache Ant

15.2.1. Common Ant Configuration Options
15.2.2. JDO Enhancer Ant Task
15.2.3. Application Identity Tool Ant Task
15.2.4. JDO Metadata Tool Ant Task
15.2.5. Mapping Tool Ant Task
15.2.6. Reverse Mapping Tool Ant Task
15.2.7. Schema Tool Ant Task
15.2.8. Schema Generator Ant Task

15.3. XDoclet

15.4. Borland JBuilder

15.4.1. Installing Kodo Into JBuilder
15.4.2. Kodo Configuration from JBuilder
15.4.3. Creating and building JDO projects in JBuilder
15.4.4. Editing JDO Metadata from JBuilder
15.4.5. Editing Mapping Info from JBuilder
15.4.6. JBuilder Project Sample

15.5. Sun ONE Studio / NetBeans IDE

15.5.1. Before Installing Kodo into the IDE
15.5.2. Installing Kodo into the IDE
15.5.3. Configuring the Kodo Module
15.5.4. Kodo Template Wizards
15.5.5. JDO DataObject
15.5.6. Mapping DataObject
15.5.7. Kodo Integration into the Build Process
15.5.8. SunONE / NetBeans Sample

15.6. Eclipse / WebSphere Studio Integration

15.6.1. Installing the Kodo Eclipse Plugin
15.6.2. Configuring the Plugin
15.6.3. Using Kodo in Eclipse IDEs
15.6.4. Eclipse Sample

16. Optimization Techniques

VI. Kodo JDO Examples

1. Kodo Sample Code

1.1. Using Application Identity
1.2. Using JDO with Java Server Pages (jsp)
1.3. Custom Proxies
1.4. JDO Enterprise Java Beans Facade
1.5. Customizing Logging
1.6. Custom Sequence Factory
1.7. Using Externalization to Persist Second Class Objects
1.8. Using Persistent Classes Without Enhancement
1.9. XDoclet Integration
1.10. Custom Mappings
1.11. Example of full-text searching in JDO
1.12. Management / Monitoring

VII. Kodo Development Workbench Guide

Introduction to the Kodo Development Workbench

1. Kodo Development Workbench Requirements

1. Running and Configuring Kodo Development Workbench

1.1. Starting Kodo Development Workbench From the Command Line
1.2. Configuring Kodo Development Workbench
1.3. Standalone Configuration Tool

2. Getting Started with Kodo Development Workbench

2.1. Beginning The Kodo Development Workbench Tutorial
2.2. Getting Familiar with Kodo Development Workbench
2.3. The MetaData Explorer
2.4. The Schema Explorer
2.5. Kodo Development Workbench Logging
2.6. The Editor
2.7. Running The Tutorial

3. Root MetaData Actions

3.1. Mount JDO File
3.2. Unmount Files...
3.3. Create MetaData
3.4. Import Mapping Info

4. MetaData Actions

4.1. Enhance
4.2. Edit MetaData
4.3. Add - Recreate Mapping Info
4.4. Export Mapping Info
4.5. Drop Mapping Info
4.6. Remove MetaData
4.7. Build Schema From Mapping
4.8. Visualize Mapping

5. Root Schema Actions

5.1. Run SchemaTool
5.2. Refresh Schema From DB
5.3. Create DB Script
5.4. Create Change Script
5.5. Reverse Map Schema
5.6. Import .schema file
5.7. Export to .schema file

6. Schema Actions

6.1. Drop Schema Object
6.2. Edit Table
6.3. Add

7. The Editors

7.1. MetaData Editor
7.2. The Mapping Editor
7.3. The Table Editor

A. JDO Resources

B. Supported Databases

B.1. JDataStore

B.2. IBM DB2

B.2.1. Known issues with DB2

B.3. Hypersonic

B.3.1. Known issues with Hypersonic

B.4. Informix

B.4.1. Known issues with Informix

B.5. Microsoft Access

B.5.1. Known issues with Microsoft Access

B.6. Microsoft SQL Server

B.6.1. Known issues with SQL Server

B.7. Microsoft FoxPro

B.7.1. Known issues with Microsoft FoxPro

B.8. MySQL

B.8.1. Known issues with MySQL

B.9. Oracle

B.9.1. Known issues with Oracle

B.10. Pointbase

B.10.1. Known issues with Pointbase

B.11. PostgreSQL

B.11.1. Known issues with PostgreSQL

B.12. Sybase Adaptive Server

B.12.1. Known issues with 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

		Next
		Part I. Introduction