Packaging a JPA Entity Application

When you package an application that uses EJB 3.0 entities, consider the following:

• Packaging a Persistence Unit

• Packaging Mapping Metadata

Packaging a Persistence Unit

Recall that an EJB 3.0 JPA persistence unit is composed of a persistence.xml file, one or more optional orm.xml files, and the managed entity classes that belong to the persistence unit.

You can package a persistence unit in its own persistence archive and include that archive in whatever Java EE modules require access to it (see "Creating a Persistence Archive"). Alternatively, you can package persistence unit files directly in various Java EE modules (see "Packaging Persistence Unit Files Directly in Java EE Modules").

The JAR file or directory, whose META-INF directory contains the persistence.xml file, is called the root of the persistence unit. An EJB 3.0 application that uses entities must define at least one persistence unit root.

The scope of a persistence unit is determined by where you define its persistence unit root.

For more information, see the following:

• "What is the persistence.xml File?"

• "Configuring the persistence.xml File"

Creating a Persistence Archive

A persistence archive is simply a JAR file that contains a persistence.xml file, one or more optional orm.xml files, and the managed entity classes that belong to the persistence unit, as Persistence ArchiveExample 27-1 shows.

Example 27-1 Persistence Archive

employee-persistence.jar
    META-INF/persistence.xml
    META-INF/orm.xml
    com/acme/model/Employee.class
    com/acme/model/Address.class
    ...

You package a persistence archive in any of the following:

• WAR: WEB-INF/lib directory. The persistence unit is accessible only to the classes within this WAR.

• EAR: the root or application library directory. The persistence unit is accessible to all application components.

Using a persistence archive, you can easily share a persistence unit with multiple Java EE modules.

Packaging Persistence Unit Files Directly in Java EE Modules

You can package persistence unit files in any of the following Java EE modules:

• EJB-JAR file

• WAR file

  • WEB-INF/classes directory

  • WEB-INF/lib (in this case, persistence.xml file must be in a JAR)

• EAR

  • persistence.xml file in a JAR in root of EAR

  • persistence.xml file in a JAR in the EAR library directory

• Application client JAR

Table 27-1 How OC4J Handles persistence.xml in META-INF and WEB-INF

WEB-INF/classes/META-INF	WEB-INF	OC4J uses persistence.xml in
persistence.xml	persistence.xml	META-INF (ignores file in WEB-INF)
	persistence.xml	META-INF
persistence.xml		WEB-INF

To decouple persistence unit files from Java EE modules and make it easier to share persistence units with multiple Java EE modules, consider packaging your persistence unit in a persistence archive (see "Creating a Persistence Archive").

Packaging Mapping Metadata

Recall that you can specify EJB 3.0 JPA mapping metadata using annotations, one or more optional orm.xml files, or both. You can package an orm.xml file in any of the following:

• META-INF directory of the persistence unit root (the JAR file or directory, whose META-INF directory contains the persistence.xml file);

• META-INF directory of any JAR file referenced by the persistence.xml file;

• persistence.xml file <persistence-unit> element <mapping-file> subelement;

• persistence archive;

For more information, see the following:

• "What is the orm.xml File?"

• "Packaging a Persistence Unit"

• "Creating a Persistence Archive"