Chapter 5. Persistent Classes

5.1. Persistent Class List
5.2. Enhancement
5.2.1. Enhancing at Build Time
5.2.2. Enhancing JPA Entities on Deployment
5.2.3. Enhancing at Runtime
5.2.4. Serializing Enhanced Types
5.3. Object Identity
5.3.1. Datastore Identity Objects
5.3.2. Application Identity Tool
5.3.3. Autoassign / Identity Strategy Caveats
5.4. Managed Inverses
5.5. Persistent Fields
5.5.1. Restoring State
5.5.2. Typing and Ordering
5.5.3. Calendar Fields and TimeZones
5.5.4. Proxies Smart Proxies Large Result Set Proxies Custom Proxies
5.5.5. Externalization External Values
5.6. Fetch Groups
5.6.1. Custom Fetch Groups
5.6.2. Custom Fetch Group Configuration
5.6.3. Per-field Fetch Configuration
5.6.4. Implementation Notes
5.7. Eager Fetching
5.7.1. Configuring Eager Fetching
5.7.2. Eager Fetching Considerations and Limitations
5.8. Lock Groups
5.8.1. Lock Groups and Subclasses
5.8.2. Lock Group Mapping

Chapter 4, Entity of the JPA Overview discusses persistent class basics in JPA. Chapter 4, PersistenceCapable of the JDO Overview does the same for JDO. This chapter details the persistent class features Kodo offers beyond the core JPA and JDO specifications.

5.1. Persistent Class List

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

  • Kodo must be able to match entity names in JPQL queries to persistent classes. Kodo 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.

  • Under JDO's application identity, Kodo must be able to match an identity object passed to the PersistenceManager to the corresponding persistent class. If the persistent class hasn't been loaded into the JVM yet, Kodo will not be able to find it. One workaround for this is to load your persistent class within your identity class' static initializer, as demonstrated in Example 4.5, “Application Identity Class” of the JDO Overview.

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

    If you use JDO's class-name discriminator strategy, Kodo will discover all persistent classes in the hierarchy on its own by issuing a SELECT DISTINCT against the database discriminator column; however, this can be inefficient for a large table. Thus it may still be preferable to provide a persistent types list, as described below.

  • If you configure Kodo to create the needed database schema on startup (see Section 7.1.4, “Runtime Forward Mapping”), Kodo 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 6.1, “persistence.xml” for details.

Under JDO, Kodo allows you to explicitly specify all of your persistent classes in the various attributes of the kodo.MetaDataFactory configuration property. See Section 6.2, “Metadata Factory” 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, Kodo will assume that any unlisted class is not persistent.