Apache OpenJPA 2.0 User's Guide


Table of Contents

I. Introduction
1. About
2. Legal
License
Notice
Copyrights
Apache
Serp
Sun
Other
II. Java Persistence API
3. Introduction
Intended Audience
Lightweight Persistence
4. Why JPA?
5. Java Persistence API Architecture
JPA Exceptions
6. Entity
Restrictions on Persistent Classes
Default or No-Arg Constructor
Final
Identity Fields
Version Field
Inheritance
Persistent Fields
Conclusions
Entity Identity
Identity Class
Lifecycle Callbacks
Callback Methods
Using Callback Methods
Using Entity Listeners
Entity Listeners Hierarchy
Conclusions
7. Metadata
Class Metadata
Entity
Id Class
Mapped Superclass
Embeddable
EntityListeners
Example
Field and Property Metadata
Explicit Access
Transient
Id
Generated Value
Embedded Id
Version
Basic
Embedded
Many To One
One To Many
One To One
Many To Many
Order By
Map Key
Persistent Field Defaults
XML Schema
Conclusion
8. Persistence
persistence.xml
Non-EE Use
9. EntityManagerFactory
Obtaining an EntityManagerFactory
Obtaining EntityManagers
Persistence Context
Transaction Persistence Context
Extended Persistence Context
Retrieving Properties Information
Closing the EntityManagerFactory
PersistenceUnitUtil
10. EntityManager
Transaction Association
Entity Lifecycle Management
Lifecycle Examples
Entity Identity Management
Cache Management
Query Factory
Retrieving Properties Information
Closing
11. Transaction
Transaction Types
The EntityTransaction Interface
12. JPA Query
JPQL API
Query Basics
Relation Traversal
Embeddable Traversal
Fetch Joins
JPQL Functions
Polymorphic Queries
Query Parameters
Query Hints
Ordering
Aggregates
Named Queries
Delete By Query
Update By Query
JPQL Language Reference
JPQL Statement Types
JPQL Abstract Schema Types and Query Domains
JPQL FROM Clause and Navigational Declarations
JPQL WHERE Clause
JPQL Conditional Expressions
JPQL Scalar Expressions
JPQL GROUP BY, HAVING
JPQL SELECT Clause
JPQL ORDER BY Clause
JPQL Bulk Update and Delete
JPQL Null Values
JPQL Equality and Comparison Semantics
JPQL BNF
13. JPA Criteria
Constructing a CriteriaQuery
Executing a CriteriaQuery
Extension to Criteria API
Generation of Canonical MetaModel classes
14. SQL Queries
Creating SQL Queries
Retrieving Persistent Objects with SQL
15. Mapping Metadata
Table
Unique Constraints
Column
Identity Mapping
Generators
Sequence Generator
TableGenerator
Example
Inheritance
Single Table
Joined
Table Per Class
Putting it All Together
Discriminator
Field Mapping
Basic Mapping
Secondary Tables
Embedded Mapping
Direct Relations
Join Table
Bidirectional Mapping
Map Mapping
The Complete Mappings
16. Conclusion
III. Reference Guide
17. Introduction
Intended Audience
18. Configuration
Introduction
Runtime Configuration
Command Line Configuration
Code Formatting
Plugin Configuration
OpenJPA Properties
openjpa.AutoClear
openjpa.AutoDetach
openjpa.BrokerFactory
openjpa.BrokerImpl
openjpa.Callbacks
openjpa.ClassResolver
openjpa.Compatibility
openjpa.ConnectionDriverName
openjpa.Connection2DriverName
openjpa.ConnectionFactory
openjpa.ConnectionFactory2
openjpa.ConnectionFactoryName
openjpa.ConnectionFactory2Name
openjpa.ConnectionFactoryMode
openjpa.ConnectionFactoryProperties
openjpa.ConnectionFactory2Properties
openjpa.ConnectionPassword
openjpa.Connection2Password
openjpa.ConnectionProperties
openjpa.Connection2Properties
openjpa.ConnectionURL
openjpa.Connection2URL
openjpa.ConnectionUserName
openjpa.Connection2UserName
openjpa.ConnectionRetainMode
openjpa.DataCache
openjpa.DataCacheManager
openjpa.DataCacheMode
openjpa.DataCacheTimeout
openjpa.DetachState
openjpa.DynamicDataStructs
openjpa.FetchBatchSize
openjpa.EncryptionProvider
openjpa.FetchGroups
openjpa.FlushBeforeQueries
openjpa.IgnoreChanges
openjpa.Id
openjpa.InitializeEagerly
openjpa.InverseManager
openjpa.LockManager
openjpa.LockTimeout
openjpa.Log
openjpa.ManagedRuntime
openjpa.Mapping
openjpa.MaxFetchDepth
openjpa.MetaDataFactory
openjpa.MetaDataRepository
openjpa.Multithreaded
openjpa.Optimistic
openjpa.OrphanedKeyAction
openjpa.NontransactionalRead
openjpa.NontransactionalWrite
openjpa.ProxyManager
openjpa.QueryCache
openjpa.QueryCompilationCache
openjpa.ReadLockLevel
openjpa.RemoteCommitProvider
openjpa.RestoreState
openjpa.RetainState
openjpa.RetryClassRegistration
openjpa.RuntimeUnenhancedClasses
openjpa.DynamicEnhancementAgent
openjpa.SavepointManager
openjpa.Sequence
openjpa.Specification
openjpa.TransactionMode
openjpa.WriteLockLevel
OpenJPA JDBC Properties
openjpa.jdbc.ConnectionDecorators
openjpa.jdbc.DBDictionary
openjpa.jdbc.DriverDataSource
openjpa.jdbc.EagerFetchMode
openjpa.jdbc.FetchDirection
openjpa.jdbc.JDBCListeners
openjpa.jdbc.LRSSize
openjpa.jdbc.MappingDefaults
openjpa.jdbc.MappingFactory
openjpa.jdbc.QuerySQLCache
openjpa.jdbc.ResultSetType
openjpa.jdbc.Schema
openjpa.jdbc.SchemaFactory
openjpa.jdbc.Schemas
openjpa.jdbc.SQLFactory
openjpa.jdbc.SubclassFetchMode
openjpa.jdbc.SynchronizeMappings
openjpa.jdbc.TransactionIsolation
openjpa.jdbc.UpdateManager
Compatibility with Specification
19. Logging
Logging Channels
OpenJPA Logging
Disabling Logging
Log4J
Apache Commons Logging
JDK java.util.logging
Custom Log
20. JDBC
Using the OpenJPA DataSource
Using a Third-Party DataSource
Managed and XA DataSources
Setting the DataSource at runtime
Runtime Access to DataSource
Database Support
DBDictionary Properties
FirebirdDictionary Properties
MySQLDictionary Properties
OracleDictionary Properties
SybaseDictionary Properties
Delimited Identifiers Support
Setting the Transaction Isolation
Setting the SQL Join Syntax
Accessing Multiple Databases
Configuring the Use of JDBC Connections
Statement Batching
Large Result Sets
Default Schema
Schema Reflection
Schemas List
Schema Factory
Schema Tool
XML Schema Format
21. Persistent Classes
Persistent Class List
Enhancement
Enhancing at Build Time
Enhancing JPA Entities on Deployment
Enhancing at Runtime
Enhancing Dynamically at Runtime
Omitting the OpenJPA enhancer
Managed Interfaces
Object Identity
Datastore Identity
Entities as Identity Fields
Application Identity Tool
Autoassign / Identity Strategy Caveats
Managed Inverses
Persistent Fields
Restoring State
Typing and Ordering
Calendar Fields and TimeZones
Proxies
Externalization
Fetch Groups
Custom Fetch Groups
Custom Fetch Group Configuration
Per-field Fetch Configuration
Implementation Notes
Eager Fetching
Configuring Eager Fetching
Eager Fetching Considerations and Limitations
22. Metadata
Metadata Factory
Metadata Repository
Additional JPA Metadata
Datastore Identity
Surrogate Version
Persistent Field Values
Persistent Collection Fields
Persistent Map Fields
Metadata Extensions
Class Extensions
Field Extensions
Example
23. Mapping
Forward Mapping
Using the Mapping Tool
Generating DDL SQL
Runtime Forward Mapping
Reverse Mapping
Customizing Reverse Mapping
Meet-in-the-Middle Mapping
Mapping Defaults
Mapping Factory
Non-Standard Joins
Additional JPA Mappings
Datastore Identity Mapping
Surrogate Version Mapping
Multi-Column Mappings
Join Column Attribute Targets
Embedded Mapping
Collections
One-Sided One-Many Mapping
Maps
Indexes and Constraints
XML Column Mapping
LOB Streaming
Mapping Limitations
Table Per Class
Mapping Extensions
Class Extensions
Field Extensions
Custom Mappings
Custom Class Mapping
Custom Discriminator and Version Strategies
Custom Field Mapping
Orphaned Keys
24. Deployment
Factory Deployment
Standalone Deployment
EntityManager Injection
Integrating with the Transaction Manager
XA Transactions
Using OpenJPA with XA Transactions
25. Runtime Extensions
Architecture
Broker Finalization
Broker Customization and Eviction
JPA Extensions
OpenJPAEntityManagerFactory
OpenJPAEntityManager
OpenJPAQuery
Extent
StoreCache
QueryResultCache
FetchPlan
OpenJPAEntityTransaction
OpenJPAPersistence
Object Locking
Configuring Default Locking
Configuring Lock Levels at Runtime
Object Locking APIs
Lock Manager
Rules for Locking Behavior
Known Issues and Limitations
Savepoints
Using Savepoints
Configuring Savepoints
MethodQL
Generators
Runtime Access
Transaction Events
Non-Relational Stores
26. Caching
Data Cache
Data Cache Configuration
Data Cache Usage
Cache Statistics
Query Cache
Cache Extension
Important Notes
Known Issues and Limitations
Query Compilation Cache
Prepared SQL Cache
27. Encryption Provider
28. Remote and Offline Operation
Detach and Attach
Detach Behavior
Attach Behavior
Defining the Detached Object Graph
Remote Event Notification Framework
Remote Commit Provider Configuration
Customization
29. Distributed Persistence
Overview
Salient Features
Transparency
Scaling
Distributed Query
Data Distribution
Data Replication
Heterogeneous Database
Distributed Transaction
Collocation Constraint
Usage
How to activate Slice Runtime?
How to configure each database slice?
Implement DistributionPolicy interface
Implement ReplicationPolicy interface
Configuration Properties
Global Properties
Per-Slice Properties
30. Third Party Integration
Apache Ant
Common Ant Configuration Options
Enhancer Ant Task
Application Identity Tool Ant Task
Mapping Tool Ant Task
Reverse Mapping Tool Ant Task
Schema Tool Ant Task
31. Optimization Guidelines
IV. Appendices
A. JPA Resources
B. Supported Databases
Overview
Verified Database Matrix
Compatible Database Matrix
Apache Derby
Borland Interbase
Known issues with Interbase
JDataStore
IBM DB2
Known issues with DB2
Empress
Known issues with Empress
H2 Database Engine
Known issues with H2 Database Engine
Hypersonic
Known issues with Hypersonic
Firebird
Known issues with Firebird
Informix
Known issues with Informix
Ingres Database
Known issues with Ingres
InterSystems Cache
Known issues with InterSystems Cache
Microsoft Access
Known issues with Microsoft Access
Microsoft SQL Server
Known issues with SQL Server
Microsoft FoxPro
Known issues with Microsoft FoxPro
MySQL
Using Query Hints with MySQL
Known issues with MySQL
Oracle
Using Query Hints with Oracle
Known issues with Oracle
Pointbase
Known issues with Pointbase
PostgreSQL
Known issues with PostgreSQL
Sybase Adaptive Server
Known issues with Sybase
C. Migration Considerations
JPA 2.0
Incompatibilities
Disabling AutoOff Collection Tracking
Internal Behavioral Differences

List of Tables

4.1. Persistence Mechanisms
12.1. Interaction of ReadLockMode hint and LockManager
18.1. Standard JPA Properties and OpenJPA equivalents
20.1. Default delimiters for delimited identifiers
20.2. OpenJPA Automatic Flush Behavior
21.1. Externalizer Options
21.2. Factory Options
26.1. Data access methods
26.2. Pre-defined aliases
26.3. Pre-defined aliases
31.1. Optimization Guidelines
B.1. Supported Databases and JDBC Drivers
B.2. Compatible Databases and JDBC Drivers

List of Examples

5.1. Interaction of Interfaces Outside Container
5.2. Interaction of Interfaces Inside Container
6.1. Persistent Class
6.2. Identity Class
7.1. Class Metadata
7.2. Complete Metadata
8.1. persistence.xml
8.2. Obtaining an EntityManagerFactory
9.1. Behavior of Transaction Persistence Context
9.2. Behavior of Extended Persistence Context
10.1. Persisting Objects
10.2. Updating Objects
10.3. Removing Objects
10.4. Detaching and Merging
11.1. Grouping Operations with Transactions
12.1. Query Hints
12.2. Named Query using Hints
12.3.
12.4. Delete by Query
12.5. Update by Query
14.1. Creating a SQL Query
14.2. Retrieving Persistent Objects
14.3. SQL Query Parameters
15.1. Mapping Classes
15.2. Defining a Unique Constraint
15.3. Identity Mapping
15.4. Generator Mapping
15.5. Single Table Mapping
15.6. Joined Subclass Tables
15.7. Table Per Class Mapping
15.8. Inheritance Mapping
15.9. Discriminator Mapping
15.10. Basic Field Mapping
15.11. Secondary Table Field Mapping
15.12. Embedded Field Mapping
15.13. Mapping Mapped Superclass Field
15.14. Direct Relation Field Mapping
15.15. Join Table Mapping
15.16. Join Table Map Mapping
15.17. Full Entity Mappings
18.1. Code Formatting with the Application Id Tool
19.1. Standard OpenJPA Log Configuration
19.2. Standard OpenJPA Log Configuration + All SQL Statements
19.3. Logging to a File
19.4. Standard Log4J Logging
19.5. JDK Log Properties
19.6. Custom Logging Class
20.1. Properties for the OpenJPA DataSource
20.2. Properties File for a Third-Party DataSource
20.3. Managed DataSource Configuration
20.4.
20.5. Using the EntityManager's Connection
20.6. Using the EntityManagerFactory's DataSource
20.7. Specifying a DBDictionary
20.8. Specifying a Transaction Isolation
20.9. Specifying the Join Syntax Default
20.10. Specifying the Join Syntax at Runtime
20.11. Specifying Connection Usage Defaults
20.12. Specifying Connection Usage at Runtime
20.13. Enable SQL statement batching
20.14. Disable SQL statement batching
20.15. Plug-in custom statement batching implementation
20.16. Specifying Result Set Defaults
20.17. Specifying Result Set Behavior at Runtime
20.18. Schema Creation
20.19. SQL Scripting
20.20. Table Cleanup
20.21. Schema Drop
20.22. Schema Reflection
20.23. Basic Schema
20.24. Full Schema
21.1. Using the OpenJPA Enhancer
21.2. Using the OpenJPA Agent for Runtime Enhancement
21.3. Passing Options to the OpenJPA Agent
21.4. JPA Datastore Identity Metadata
21.5. Finding an Entity with an Entity Identity Field
21.6. Id Class for Entity Identity Fields
21.7. Embedded Id for Entity Identity Fields
21.8. Using the Application Identity Tool
21.9. Specifying Logical Inverses
21.10. Enabling Managed Inverses
21.11. Log Inconsistencies
21.12. Using Initial Field Values
21.13. Using a Large Result Set Iterator
21.14. Marking a Large Result Set Field
21.15. Configuring the Proxy Manager
21.16. Using Externalization
21.17. Querying Externalization Fields
21.18. Using External Values
21.19. Custom Fetch Group Metadata
21.20. Load Fetch Group Metadata
21.21. Using the FetchPlan
21.22. Adding an Eager Field
21.23. Setting the Default Eager Fetch Mode
21.24. Setting the Eager Fetch Mode at Runtime
22.1. Setting a Standard Metadata Factory
22.2. Setting a Custom Metadata Factory
22.3.
22.4. OpenJPA Metadata Extensions
23.1. Using the Mapping Tool
23.2. Creating the Relational Schema from Mappings
23.3. Refreshing entire schema and cleaning out tables
23.4. Dropping Mappings and Association Schema
23.5. Create DDL for Current Mappings
23.6. Create DDL to Update Database for Current Mappings
23.7. Configuring Runtime Forward Mapping
23.8. Reflection with the Schema Tool
23.9. Using the Reverse Mapping Tool
23.10. Customizing Reverse Mapping with Properties
23.11. Validating Mappings
23.12. Configuring Mapping Defaults
23.13. Standard JPA Configuration
23.14. Datastore Identity Mapping
23.15. Overriding Complex Mappings
23.16. One-Sided One-Many Mapping
23.17. String Key, Entity Value Map Mapping
23.18. myaddress.xsd
23.19. Address.java
23.20. USAAddress.java
23.21. CANAddress.java
23.22. Showing annotated Order entity with XML mapping strategy
23.23. Showing creation of Order entity having shipAddress mapped to XML column
23.24. Sample JPQL queries for XML column mapping
23.25. Annotated InputStream and Reader
23.26. Custom Logging Orphaned Keys
24.1. Configuring Transaction Manager Integration
25.1. Evict from Data Cache
25.2. Using a JPA Extent
25.3. Setting Default Lock Levels
25.4. Setting Runtime Lock Levels
25.5. Locking APIs
25.6. Disabling Locking
25.7. Using Savepoints
25.8. Named Seq Sequence
25.9. System Sequence Configuration
26.1. Single-JVM Data Cache
26.2. Data Cache Size
26.3. Data Cache Timeout
26.4. Excluding entities
26.5. Including entities
26.6. Partitioned Data Cache
26.7. Accessing the Cache
26.8. Using the javax.persistence.Cache interface
26.9. Accessing the StoreCache
26.10. StoreCache Usage
26.11. Automatic Data Cache Eviction
26.12. Configuring CacheStatistics
26.13. Accessing the QueryResultCache
26.14. Query Cache Size
26.15. Disabling the Query Cache
26.16. Query Cache Eviction Policy
26.17. Evicting Queries
26.18. Pinning, and Unpinning Query Results
26.19. Disabling and Enabling Query Caching
26.20. Query Replaces Extent
26.21. Hardcoded Selection Value in JPQL Query
26.22. Parameterized Selection Value in JPQL Query
28.1. Configuring Detached State
28.2. JMS Remote Commit Provider Configuration
28.3. TCP Remote Commit Provider Configuration
28.4. JMS Remote Commit Provider transmitting Persisted Object Ids
30.1. Using the <config> Ant Tag
30.2. Using the Properties Attribute of the <config> Tag
30.3. Using the PropertiesFile Attribute of the <config> Tag
30.4. Using the <classpath> Ant Tag
30.5. Using the <codeformat> Ant Tag
30.6. Invoking the Enhancer from Ant
30.7. Invoking the Application Identity Tool from Ant
30.8. Invoking the Mapping Tool from Ant
30.9. Invoking the Reverse Mapping Tool from Ant
30.10. Invoking the Schema Tool from Ant
B.1. Example properties for Derby
B.2. Example properties for Interbase
B.3. Example properties for JDataStore
B.4. Example properties for IBM DB2
B.5. Example properties for Empress
B.6. Example properties for H2 Database Engine
B.7. Example properties for Hypersonic
B.8. Example properties for Firebird
B.9. Example properties for Informix Dynamic Server
B.10. Example properties for Ingres
B.11. Example properties for InterSystems Cache
B.12. Example properties for Microsoft Access
B.13. Example properties for Microsoft SQL Server
B.14. Example properties for Microsoft FoxPro
B.15. Example properties for MySQL
B.16. Using MySQL Hints
B.17. Example properties for Oracle
B.18. Using Oracle Hints
B.19. Property to disable statement batching for Oracle
B.20. Property to retain connection over the lifetime of the entity manager
B.21. Example properties for Pointbase
B.22. Example properties for PostgreSQL
B.23. Example properties for Sybase