9.2. JPA Extensions

The following sections outline the runtime interfaces you can use
to access Kodo-specific functionality from JPA. Each
interface contains services and convenience methods missing from the
JPA specification. Kodo strives to use the same naming
conventions and API patterns as standard JPA methods in all
extensions, so that Kodo JDO APIs feel as much as possible like
standard JPA.

You may have noticed the examples throughout this document using the
KodoPersistence.cast methods to cast from
standard JPA interfaces to Kodo extended interfaces.
This is the recommended practice. Some application server vendors
may proxy Kodo's JPA implementation, preventing a straight
cast. KodoPersistence's cast
methods work around these proxies.

We provide additional information on the KodoPersistence
helper
below.

9.2.1. KodoEntityManagerFactory

The kodo.persistence.KodoEntityManagerFactory
interface extends the basic
javax.persistence.EntityManagerFactory with
Kodo-specific features. The KodoEntityManagerFactory
offers APIs to obtain
managed and unmanaged EntityManagers from
the same factory, to access the Kodo data and query caches, and to
perform other Kodo-specific operations. See the
interface Javadoc for details.

9.2.2. KodoEntityManager

All Kodo EntityManagers implement the
kodo.persistence.KodoEntityManager
interface. This interface extends the standard
javax.persistence.EntityManager. Just as the
standard EntityManager is the primary
window into JPA services, the
KodoEntityManager is the primary window from JPA
into Kodo-specific functionality. We strongly
encourage you to investigate the API extensions this interface
contains.

9.2.3. KodoQuery

Kodo extends JPA's standard query functionality with the
kodo.persistence.KodoQuery interface. See
its Javadoc
for details on the convenience methods it provides.

9.2.4. Extent

An Extent is a logical view of all persistent
instances of a given entity class, possibly including subclasses.
Kodo adds the kodo.persistence.Extent class
to the set of Java Persistence APIs. The following code illustrates
iterating over all instances of the Magazine
entity, without subclasses:

9.2.5. StoreCache

In addition to the EntityManager object
cache mandated by the JPA specification, Kodo includes
a flexible datastore-level cache. You can access this cache
from your JPA code using the
kodo.persistence.StoreCache facade.
Section 10.1, “Data Cache” has detailed information on
Kodo's data caching system, including the
StoreCache facade.

9.2.7. FetchPlan

Many of the aforementioned Kodo interfaces give you access to a
kodo.persistence.FetchPlan
instance. The FetchPlan allows you
to exercise some control over how objects are fetched from the
datastore, including large
result set support, custom
fetch groups, and lock
levels.

Fetch plans pass on from parent components to child
components. The EntityManagerFactory
settings (via your configuration properties) for things like the
fetch size, result set type, and custom fetch groups are passed on
to the fetch plan of the
EntityManagers it produces. The settings
of each EntityManager, in turn, are passed
on to each Query and Extent
it returns. Note that the opposite, however, is not
true. Modifying the fetch plan of a
Query or Extent does
not affect the EntityManager's configuration.
Likewise, modifying an EntityManager's
configuration does not affect the
EntityManagerFactory.