Configure Persistence Context

JBoss EJB 3.0 and Extensions

Introduction

To deploy the entity beans in an application, you can just package their class files in a JAR file. The EJB 3.0 specification also requires a persistence.xml file in the META-INF directory of the JAR file. The persistence.xml file defines which database is used with those entity beans and specifies the default behavior of the EntityManager. You can then deploy the JAR to the server's deploy directory or bundled in an EAR file.

The persistence.xml file

The persistence.xml file contains one or several persistence-unit element. Each persistence-unit defines the persistence context name, data source settings, and vendor specific properties. Below is a more typical persistence.xml file.


<persistence>
  <persistence-unit name="ejb3trail">
    <jta-data-source>java:/DefaultDS</jta-data-source>
    <properties>
      <property name="hibernate.hbm2ddl.auto"
                value="create-drop"/>
    </properties>
  </persistence-unit>
</persistence>

It specifies that the ejb3trail named EntityManager (see next section) should use the java:/DefaultDS datasource (i.e., the embedded HSQL database in JBoss AS) to persist the entity beans it manages. If you need to use a different database to map the entity beans in this persistence context, you can change the JNDI name of the data source to replace the java:/DefaultDS value (you have to define the alternative datasource in a *-ds.xml file, see the application server guide for more details). In addition, JBoss AS should create database tables for those entity beans when the application is deployed, and delete those tables when the application is un-deployed. Note that the application is deployed and un-deployed automatically at the server startup or shutdown.

The properties in the persistence.xml are application server specific. In JBoss AS, they are simply Hibernate properties since Hibernate is the underlying implementation framework for JBoss EJB 3.0. You can see a list of available properties and their default values in the [server_installation]/server/deploy/ejb3.deployer/META-INF/persistence.properties file.

Injecting an EntityManager from a specific context

As we can see, the persistence.xml file in the JAR file can define multiple persistence contexts with different names. To obtain an EntityManager from a named persistence context, you just need to specify the name in the unitName attribute of the @PersistenceContext annotation. The following example injects the ejb3trail persistence context to the EntityManager.


@PersistenceContext(unitName="ejb3trail")
EntityManager em;

You can omit the unitName attribute if the following conditions are met:

You only have one persistence context defined in the persistence.xml file in the entire application.
You are using a scoped classloader for the application.

The second item probably needs more explanation. In a web application deployed in an EAR file, that means you need a jboss-app.xml file in the EAR file's META-INF directory. The file can specify an arbitrary name for the classloader. Here is an example:


<jboss-app>
  <loader-repository>
    trailblazer:app=ejb3
  </loader-repository>
</jboss-app>

If you do not have a scoped classloader for the application, all the persistence contexts defined in the applications would be globally available in the entire server, and the @PersistenceContext injection look for an EntityManager in the global context as well. That allows you to use persistence context defined outside of your own application. But you also have to explicitly specify the persistence context name via the unitName attribute.

Summary
	In this trail, we discussed how to configure multiple persistence contexts for an application.