Apache OpenJPA User's Guide

OpenJPA is Apache's implementation of Sun's Java Persistence API (JPA) specification for the transparent persistence of Java objects. This document provides an overview of the JPA standard and technical details on the use of OpenJPA.

1. About This Document

This document is intended for OpenJPA users. It is divided into several parts:

The JPA Overview describes the fundamentals of the JPA specification.
The OpenJPA Reference Guide contains detailed documentation on all aspects of OpenJPA. Browse through this guide to familiarize yourself with the many advanced features and customization opportunities OpenJPA provides. Later, you can use the guide when you need details on a specific aspect of OpenJPA.

Part 2. Java Persistence API

Table of Contents

1. Introduction

1. Intended Audience
2. Lightweight Persistence

2. Why JPA?

3. Java Persistence API Architecture

1. JPA Exceptions

4. Entity

1. Restrictions on Persistent Classes

1.1. Default or No-Arg Constructor
1.2. Final
1.3. Identity Fields
1.4. Version Field
1.5. Inheritance
1.6. Persistent Fields
1.7. Conclusions

2. Entity Identity

2.1. Identity Class

2.1.1. Identity Hierarchies

3. Lifecycle Callbacks

3.1. Callback Methods
3.2. Using Callback Methods
3.3. Using Entity Listeners
3.4. Entity Listeners Hierarchy

4. Conclusions

5. Metadata

1. Class Metadata

1.1. Entity
1.2. Id Class
1.3. Mapped Superclass
1.4. Embeddable
1.5. EntityListeners
1.6. Example

2. Field and Property Metadata

2.1. Transient

2.2. Id

2.3. Generated Value

2.4. Embedded Id

2.5. Version

2.6. Basic

2.6.1. Fetch Type

2.7. Embedded

2.8. Many To One

2.8.1. Cascade Type

2.9. One To Many

2.9.1. Bidirectional Relations

2.10. One To One

2.11. Many To Many

2.12. Order By

2.13. Map Key

2.14. Persistent Field Defaults

3. XML Schema

4. Conclusion

6. Persistence

1. persistence.xml
2. Non-EE Use

7. EntityManagerFactory

1. Obtaining an EntityManagerFactory

2. Obtaining EntityManagers

3. Persistence Context

3.1. Transaction Persistence Context
3.2. Extended Persistence Context

4. Closing the EntityManagerFactory

8. EntityManager

1. Transaction Association
2. Entity Lifecycle Management
3. Lifecycle Examples
4. Entity Identity Management
5. Cache Management
6. Query Factory
7. Closing

9. Transaction

1. Transaction Types
2. The EntityTransaction Interface

10. JPA Query

1. JPQL API

1.1. Query Basics

1.2. Relation Traversal

1.3. Fetch Joins

1.4. JPQL Functions

1.5. Polymorphic Queries

1.6. Query Parameters

1.7. Query Hints

1.7.1. Locking Hints
1.7.2. Result Set Size Hint
1.7.3. Isolation Level Hint
1.7.4. Other Fetchplan Hints
1.7.5. Oracle Query Hints
1.7.6. Named Query Hints

1.8. Ordering

1.9. Aggregates

1.10. Named Queries

1.11. Delete By Query

1.12. Update By Query

2. JPQL Language Reference

2.1. JPQL Statement Types

2.1.1. JPQL Select Statement
2.1.2. JPQL Update and Delete Statements

2.2. JPQL Abstract Schema Types and Query Domains

2.2.1. JPQL Entity Naming
2.2.2. JPQL Schema Example

2.3. JPQL FROM Clause and Navigational Declarations

2.3.1. JPQL FROM Identifiers

2.3.2. JPQL Identification Variables

2.3.3. JPQL Range Declarations

2.3.4. JPQL Path Expressions

2.3.5. JPQL Joins

2.3.5.1. JPQL Inner Joins (Relationship Joins)
2.3.5.2. JPQL Outer Joins
2.3.5.3. JPQL Fetch Joins

2.3.6. JPQL Collection Member Declarations

2.3.7. JPQL Polymorphism

2.4. JPQL WHERE Clause

2.5. JPQL Conditional Expressions

2.5.1. JPQL Literals

2.5.2. JPQL Identification Variables

2.5.3. JPQL Path Expressions

2.5.4. JPQL Input Parameters

2.5.4.1. JPQL Positional Parameters
2.5.4.2. JPQL Named Parameters

2.5.5. JPQL Conditional Expression Composition

2.5.6. JPQL Operators and Operator Precedence

2.5.7. JPQL Between Expressions

2.5.8. JPQL In Expressions

2.5.9. JPQL Like Expressions

2.5.10. JPQL Null Comparison Expressions

2.5.11. JPQL Empty Collection Comparison Expressions

2.5.12. JPQL Collection Member Expressions

2.5.13. JPQL Exists Expressions

2.5.14. JPQL All or Any Expressions

2.5.15. JPQL Subqueries

2.5.16. JPQL Functional Expressions

2.5.16.1. JPQL String Functions
2.5.16.2. JPQL Arithmetic Functions
2.5.16.3. JPQL Datetime Functions

2.6. JPQL GROUP BY, HAVING

2.7. JPQL SELECT Clause

2.7.1. JPQL Result Type of the SELECT Clause

2.7.2. JPQL Constructor Expressions

2.7.3. JPQL Null Values in the Query Result

2.7.4. JPQL Aggregate Functions

2.7.4.1. JPQL Aggregate Examples

2.8. JPQL ORDER BY Clause

2.9. JPQL Bulk Update and Delete

2.10. JPQL Null Values

2.11. JPQL Equality and Comparison Semantics

2.12. JPQL BNF

11. SQL Queries

1. Creating SQL Queries
2. Retrieving Persistent Objects with SQL

12. Mapping Metadata

1. Table

2. Unique Constraints

3. Column

4. Identity Mapping

5. Generators

5.1. Sequence Generator
5.2. TableGenerator
5.3. Example

6. Inheritance

6.1. Single Table

6.1.1. Advantages
6.1.2. Disadvantages

6.2. Joined

6.2.1. Advantages
6.2.2. Disadvantages

6.3. Table Per Class

6.3.1. Advantages
6.3.2. Disadvantages

6.4. Putting it All Together

7. Discriminator

8. Field Mapping

8.1. Basic Mapping

8.1.1. LOBs
8.1.2. Enumerated
8.1.3. Temporal Types
8.1.4. The Updated Mappings

8.2. Secondary Tables

8.3. Embedded Mapping

8.4. Direct Relations

8.5. Join Table

8.6. Bidirectional Mapping

8.7. Map Mapping

9. The Complete Mappings

13. Conclusion

Chapter 1. Introduction

Table of Contents

1. Intended Audience
2. Lightweight Persistence

The Java Persistence API (JPA) is a specification from Sun Microsystems for the persistence of Java objects to any relational datastore. JPA requires J2SE 1.5 (also referred to as "Java 5") or higher, as it makes heavy use of new Java language features such as annotations and generics. This document provides an overview of JPA. Unless otherwise noted, the information presented applies to all JPA implementations.

Note

For coverage of OpenJPA's many extensions to the JPA specification, see the Reference Guide.

1. Intended Audience

This document is intended for developers who want to learn about JPA in order to use it in their applications. It assumes that you have a strong knowledge of object-oriented concepts and Java, including Java 5 annotations and generics. It also assumes some experience with relational databases and the Structured Query Language (SQL).

2. Lightweight Persistence

Persistent data is information that can outlive the program that creates it. The majority of complex programs use persistent data: GUI applications need to store user preferences across program invocations, web applications track user movements and orders over long periods of time, etc.

Lightweight persistence is the storage and retrieval of persistent data with little or no work from you, the developer. For example, Java serialization is a form of lightweight persistence because it can be used to persist Java objects directly to a file with very little effort. Serialization's capabilities as a lightweight persistence mechanism pale in comparison to those provided by JPA, however. The next chapter compares JPA to serialization and other available persistence mechanisms.

Chapter 2. Why JPA?

Java developers who need to store and retrieve persistent data already have several options available to them: serialization, JDBC, JDO, proprietary object-relational mapping tools, object databases, and EJB 2 entity beans. Why introduce yet another persistence framework? The answer to this question is that with the exception of JDO, each of the aforementioned persistence solutions has severe limitations. JPA attempts to overcome these limitations, as illustrated by the table below.

Table 2.1. Persistence Mechanisms

Supports:	Serialization	JDBC	ORM	ODB	EJB 2	JDO	JPA
Java Objects	Yes	No	Yes	Yes	Yes	Yes	Yes
Advanced OO Concepts	Yes	No	Yes	Yes	No	Yes	Yes
Transactional Integrity	No	Yes	Yes	Yes	Yes	Yes	Yes
Concurrency	No	Yes	Yes	Yes	Yes	Yes	Yes
Large Data Sets	No	Yes	Yes	Yes	Yes	Yes	Yes
Existing Schema	No	Yes	Yes	No	Yes	Yes	Yes
Relational and Non-Relational Stores	No	No	No	No	Yes	Yes	No