Enterprise JavaBeans 3.1, 6th Edition

Packaging a Persistence Unit

An EntityManager maps a fixed set of classes to a particular database. This set of classes is called a persistence unit. Before you can even think about creating or querying entities with an entity manager, you must learn how to package a persistence unit for use within a Java SE (regular Java application) or Java EE (application server) environment. A persistence unit is defined in a persistence.xml file, which is described by the JPA2 specification in section 8.2.1. This file is a required deployment descriptor for the Java Persistence specification. A persistence.xml file can define one or more persistence units. The JAR file or directory that contains a META-INF/persistence.xml file is called the “root” of the persistence unit, and this may be:

• An EJB JAR file

• The WEB-INF/classes directory of a WAR file

• A JAR file in the WEB-INF/lib directory of a WAR file

• A JAR file in an EAR library directory

• An application client JAR file

The structure of one of these JAR files may look like the following:

/META-INF/
/META-INF/persistence.xml
/org/
/org/example/
/org/example/entity/
/org/example/entity/Employee.class

The persistence.xml deployment descriptor defines the identities and configuration properties of each persistence unit described within it. Each persistence unit must have an identity, although the empty string is a valid name.

The set of classes that belong to the persistence unit can be specified, or you can opt for the persistence provider to scan the JAR ...