Migration and integration - Enterprise OSGi in Action - page 280

11.2.2 Using persistence bundles

JPA is a popular persistence model, and is the Java EE standard for Object-Relational
Mapping. As a result, JPA is tightly integrated with other Java EE specifications.
Although JPA does fit nicely with other Java EE technologies, it's also possible to use it
in Java SE , as this is a common pattern, even inside enterprise web applications. Let's
start by looking at how to get a standard JPA bundle working in OSG i.

PACKAGING PERSISTENCE UNITS
As you saw in chapter 3, it's easy to make use of JPA in OSG i, but there are some important
differences. In Java SE you can package a persistence descriptor called persistence.xml
in the META-INF folder of a JAR to define persistence units. This descriptor can then be
located on the classpath by a JPA provider and used to build the required object models,
table descriptions, and database connections. In OSG i , t h i n g s h a v e t o b e a l i t t l e d i f f e r e n t .
The persistence descriptor and the JPA provider shouldn't be part of the same bundle,
but if they aren't then the JPA provider won't be able to see persistence descriptors that
are hidden away in other bundles. This is a specific example of a more general problem
that affects Java SE programs in OSG i, one that we'll cover more in section 12.2.1.
To get around this issue, OSG i persistence bundles add one important piece of infor-
mation to their manifests. This is the Meta-Persistence header. This header is used to
identify and advertise the locations of the JPA persistence descriptors in the bundle, and
has a default value of META-INF /persistence.xml, like Java SE . Unlike Java SE , the
header can also point to persistence descriptors in other parts of the bundle, even ones
that aren't named persistence.xml. A big advantage of this header is that it can be used
to provide different persistence descriptors in Java SE and OSG i. Java SE will always use
META-INF /persistence.xml, but OSG i can be told to use a different descriptor, poten-
tially with different properties, that's better suited to the OSG i environment.
In JPA the persistence descriptor isn't the only important resource; there are also
the managed classes , which are the classes that can be mapped into the database by the
JPA provider. These are sometimes called the entity classes , but strictly speaking that
term only refers to a subset of persistent classes. Because these classes are so closely
related to the persistence descriptor, it's important that they get packaged into the
same bundle (which is almost always the case in Java SE JAR s).

OTHER TYPES OF PERSISTENCE BUNDLE
We're focusing on Java SE JPA usage, but it's worth briefly mentioning that Java EE
defines persistence behavior for both EJB JAR s and WAR files. If a bundle is an EJB
JAR or WAR , then it's automatically searched for persistence descriptors and man-
aged classes. To help developers working with these module types in OSG i, the Aries
JPA container has semantic understanding of the headers that define both WAB s and
EJB bundles. As a result, you don't need to specify a Meta-Persistence header
as well as a Web-ContextPath header, unless you wish to override the default
WAB search locations of WEB-INF /classes/ META-INF /persistence.xml and WEB-INF /
lib/<library.jar>!/ META-INF /persistence.xml. Like WAB s, EJB bundles will also be