Chapter 5.  Persistent Classes

Table of Contents

1. Persistent Class List
2. Enhancement
2.1. Enhancing at Build Time
2.2. Enhancing JPA Entities on Deployment
2.3. Enhancing at Runtime
2.4. Omitting the OpenJPA enhancer
3. Object Identity
3.1. Datastore Identity
3.2. Entities as Identity Fields
3.3. Application Identity Tool
3.4. Autoassign / Identity Strategy Caveats
4. Managed Inverses
5. Persistent Fields
5.1. Restoring State
5.2. Typing and Ordering
5.3. Calendar Fields and TimeZones
5.4. Proxies
5.4.1. Smart Proxies
5.4.2. Large Result Set Proxies
5.4.3. Custom Proxies
5.5. Externalization
5.5.1. External Values
6. Fetch Groups
6.1. Custom Fetch Groups
6.2. Custom Fetch Group Configuration
6.3. Per-field Fetch Configuration
6.4. Implementation Notes
7. Eager Fetching
7.1. Configuring Eager Fetching
7.2. Eager Fetching Considerations and Limitations

Persistent class basics are covered in Chapter 4, Entity of the JPA Overview. This chapter details the persistent class features OpenJPA offers beyond the core JPA specification.

1.  Persistent Class List

Unlike many ORM products, OpenJPA does not need to know about all of your persistent classes at startup. OpenJPA discovers new persistent classes automatically as they are loaded into the JVM; in fact you can introduce new persistent classes into running applications under OpenJPA. However, there are certain situations in which providing OpenJPA with a persistent class list is helpful:

  • OpenJPA must be able to match entity names in JPQL queries to persistent classes. OpenJPA automatically knows the entity names of any persistent classes already loaded into the JVM. To match entity names to classes that have not been loaded, however, you must supply a persistent class list.

  • When OpenJPA manipulates classes in a persistent inheritance hierarchy, OpenJPA must be aware of all the classes in the hierarchy. If some of the classes have not been loaded into the JVM yet, OpenJPA may not know about them, and queries may return incorrect results.

  • If you configure OpenJPA to create the needed database schema on startup (see Section 1.3, “ Runtime Forward Mapping ”), OpenJPA must know all of your persistent classes up-front.

When any of these conditions are a factor in your JPA application, use the class, mapping-file, and jar-file elements of JPA's standard XML format to list your persistent classes. See Section 1, “ persistence.xml ” for details.


Listing persistent classes (or their metadata or jar files) is an all-or-nothing endeavor. If your persistent class list is non-empty, OpenJPA will assume that any unlisted class is not persistent.