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:


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 ...

Get Enterprise JavaBeans 3.1, 6th Edition now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.