Introduction

The WildFly JPA subsystem implements the JPA 2.1 container-managed requirements. Deploys the persistence unit definitions, the persistence unit/context annotations and persistence unit/context references in the deployment descriptor. JPA Applications use the Hibernate (version 4) persistence provider, that is included with WildFly. The JPA subsystem uses the standard SPI (javax.persistence.spi.PersistenceProvider) to access the Hibernate persistence provider and some additional extensions as well.

During application deployment, JPA use is detected (e.g. persistence.xml or @PersistenceContext/Unit annotations) and injects Hibernate dependencies into the application deployment. This makes it easy to deploy JPA applications.

Update your Persistence.xml for Hibernate 4.3.0

The persistence provider class name in Hibernate 4.3.0 is org.hibernate.jpa.HibernatePersistenceProvider.

Instead of specifying:

<provider>org.hibernate.ejb.HibernatePersistence</provider>

Switch to*:*

<provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>

Or remove the persistence provider class name from your persistence.xml (so the default provider will be used).

Entity manager

The entity manager is similar to the Hibernate Session class; applications use it to create/read/update/delete data (and related operations). Applications can use application-managed or container-managed entity managers. Keep in mind that the entity manager is not expected to be thread safe (don't inject it into a servlet class variable which is visible to multiple threads).

Application-managed entity manager

Application-managed entity managers provide direct access to the underlying persistence provider (org.hibernate.ejb.HibernatePersistence). The scope of the application-managed entity manager is from when the application creates it and lasts until the app closes it. Use the @PersistenceUnit annotation to inject a persistence unit into a javax.persistence.EntityManagerFactory. The EntityManagerFactory can return an application-managed entity manager.

Container-managed entity manager

Container-managed entity managers auto-magically manage the underlying persistence provider for the application. Container-managed entity managers may use transaction-scoped persistence contexts or extended persistence contexts. The container-managed entity manager will create instances of the underlying persistence provider as needed. Every time that a new underlying persistence provider (org.hibernate.ejb.HibernatePersistence) instance is created, a new persistence context is also created (as an implementation detail of the underlying persistence provider).

Persistence Context

The JPA persistence context contains the entities managed by the persistence provider. The persistence context acts like a first level (transactional) cache for interacting with the datasource. Loaded entities are placed into the persistence context before being returned to the application. Entities changes are also placed into the persistence context (to be saved in the database when the transaction commits).

Transaction-scoped Persistence Context

The transaction-scoped persistence context coordinates with the (active) JTA transaction. When the transaction commits, the persistence context is flushed to the datasource (entity objects are detached but may still be referenced by application code). All entity changes that are expected to be saved to the datasource, must be made during a transaction. Entities read outside of a transaction will be detached when the entity manager invocation completes. Example transaction-scoped persistence context is below.

Extended Persistence Context

The (ee container managed) extended persistence context can span multiple transactions and allows data modifications to be queued up (like a shopping cart), without an active JTA transaction (to be applied during the next JTA TX). The Container-managed extended persistence context can only be injected into a stateful session bean.

Extended Persistence Context Inheritance

By default, the current stateful session bean being created, will (deeply) inherit the extended persistence context from any stateful session bean executing in the current Java thread. The deep inheritance of extended persistence context includes walking multiple levels up the stateful bean call stack (inheriting from parent beans). The deep inheritance of extended persistence context includes sibling beans. For example, parentA references child beans beanBwithXPC & beanCwithXPC. Even though parentA doesn't have an extended persistence context, beanBwithXPC & beanCwithXPC will share the same extended persistence context.

Some other EE application servers, use shallow inheritance, where stateful session bean only inherit from the parent stateful session bean (if there is a parent bean). Sibling beans do not share the same extended persistence context unless their (common) parent bean also has the same extended persistence context.

Applications can include a (top-level) jboss-all.xml deployment descriptor that specifies either the (default) DEEP extended persistence context inheritance or SHALLOW.

The AS/docs/schema/jboss-jpa_1_0.xsd describes the jboss-jpa deployment descriptor that may be included in the jboss-all.xml. Below is an example of using SHALLOW extended persistence context inheritance:

The AS console/cli can change the default extended persistence context setting (DEEP or SHALLOW). The following cli commands will read the current JPA settings and enable SHALLOW extended persistence context inheritance for applications that do not include the jboss-jpa deployment descriptor:

Entities

JPA 2.0 makes it easy to use your (pojo) plain old Java class to represent a database table row.

The entity lifecycle is managed by the underlying persistence provider.

New (transient): an entity is new if it has just been instantiated using the new operator, and it is not associated with a persistence context. It has no persistent representation in the database and no identifier value has been assigned.

Managed (persistent): a managed entity instance is an instance with a persistent identity that is currently associated with a persistence context.

Detached: the entity instance is an instance with a persistent identity that is no longer associated with a persistence context, usually because the persistence context was closed or the instance was evicted from the context.

Removed: a removed entity instance is an instance with a persistent identity, associated with a persistence context, but scheduled for removal from the database.

Deployment

The persistence.xml contains the persistence unit configuration (e.g. datasource name) and as described in the JPA 2.0 spec (section 8.2), the jar file or directory whose META-INF directory contains the persistence.xml file is termed the root of the persistence unit. In Java EE environments, the root of a persistence unit must be one of the following (quoted directly from the JPA 2.0 specification):

"

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 the EAR library directory

an application client jar file

The persistence.xml can specify either a JTA datasource or a non-JTA datasource. The JTA datasource is expected to be used within the EE environment (even when reading data without an active transaction). If a datasource is not specified, the default-datasource will instead be used (must be configured).

NOTE: Java Persistence 1.0 supported use of a jar file in the root of the EAR as the root of a persistence unit. This use is no longer supported. Portable applications should use the EAR library directory for this case instead.

"

Question: Can you have a EAR/META-INF/persistence.xml?

Answer: No, the above may deploy but it could include other archives also in the EAR, so you may have deployment issues for other reasons. Better to put the persistence.xml in an EAR/lib/somePuJar.jar.

Troubleshooting

The org.jboss.as.jpa logging can be enabled to get the following information:

INFO - when persistence.xml has been parsed, starting of persistence unit service (per deployed persistence.xml), stopping of persistence unit service

TRACE - shows how long each entity manager operation took in milliseconds, application searches for a persistence unit, parsing of persistence.xml

To enable TRACE, open the as/standalone/configuration/standalone.xml (or as/domain/configuration/domain.xml) file. Search for <subsystem xmlns="urn:jboss:domain:logging:1.0"> and add the org.jboss.as.jpa category. You need to change the console-handler level from INFO to TRACE.

To see what is going on at the JDBC level, enable jboss.jdbc.spy TRACE and add spy="true" to the datasource.

Background on the Jipijapa project

The Jipijapa project goal is to improve application platform integration with JPA persistence providers. Jipijapa provides additional integration that makes it easier to use various persistence providers. For example, look here at how the Hibernate environment is setup automatically (so that JPA deployments can just work). Also, application persistence unit definitions (persistence.xml) can override most settings.

Packaging persistence providers with your application and which Jipijapa artifacts to include

Applications that include a copy of a persistence provider, should include one of the following Jipijapa integration jars, so that WildFly can easily deploy your application. The alternative to including persistence providers with your application, is to instead use the persistence provider as a static module (each of the below providers already have a placeholder static module that you can copy provider jars into).

Persistence Provider

WildFly Version

Group ID

Artifact ID

Version

Hibernate ORM 4.3.x

8.1.0.Final

org.jipijapa

jipijapa-hibernate4-3

1.1.0.Final

Hibernate ORM 4.0.x, 4.1.x, 4.2.x

8.1.0.Final

org.jipijapa

jipijapa-hibernate4-1

1.1.0.Final

Hibernate ORM version 3.x

8.1.0.Final

org.jipijapa

jipijapa-hibernate3

1.1.0.Final

EclipseLink

8.1.0.Final

org.jipijapa

jipijapa-eclipselink

1.1.0.Final

OpenJPA

8.1.0.Final

org.jipijapa

jipijapa-openjpa

1.1.0.Final

Using the Hibernate 4.3.x JPA persistence provider

Hibernate 4.3.x is packaged with WildFly and is the default persistence provider.

Using the Infinispan second level cache

To enable the second level cache with Hibernate 4, just set the hibernate.cache.use_second_level_cache property to true, as is done in the following example (also set the shared-cache-mode accordingly). By default the application server uses Infinispan as the cache provider for JPA applications, so you don't need specify anything on top of that:

Here is an example of enabling the second level cache for a Hibernate native API hibernate.cfg.xml file:

The Hibernate native API application will also need a MANIFEST.MF:

Infinispan Hibernate/JPA second level cache provider documentation contains advanced configuration information but you should bear in mind that when Hibernate runs within WildFly 8, some of those configuration options, such as region factory, are not needed. Moreover, the application server providers you with option of selecting a different cache container for Infinispan via hibernate.cache.infinispan.container persistence property. To reiterate, this property is not mandatory and a default container is already deployed for by the application server to host the second level cache.

Replacing the current Hibernate 4.3.x jars with a newer version

Just update the current wildfly/modules/system/layers/base/org/hibernate/main folder to contain the newer version (after stopping your WildFly server instance).

WildFly 8 allows the packaging of Hibernate 3.5 (or greater) persistence provider jars with the application. The JPA deployer will detect the presence of a persistence provider in the application and jboss.as.jpa.providerModule needs to be set to hibernate3-bundled.

The WildFly testsuite contains a test that packages jars from the Hibernate 3.6.5.Final jars in the ear lib.

Update the module.xml file to name each jar you copied in as a "resource-root":

In your persistence.xml, you will refer to the Hibernate 3 persistence provider as follows:

Using OpenJPA

You need to copy the OpenJPA jars (e.g. openjpa-all.jar serp.jar) into the WildFly modules/system/layers/base/org/apache/openjpa/main folder and update modules/system/layers/base/org/apache/openjpa/main/module.xml to include the same jar file names that you copied in.

Using EclipseLink

You need to copy the EclipseLink jar (e.g. eclipselink-2.5.1.jar or eclipselink.jar as in the example below) into the WildFly modules/system/layers/base/org/eclipse/persistence/main folder and update modules/system/layers/base/org/eclipse/persistence/main/module.xml to include the EclipseLink jar (take care to use the jar name that you copied in). If you happen to leave the EclipseLink version number in the jar name, the module.xml should reflect that.

As a workaround for issueid=414974, set (WildFly) system property "eclipselink.archive.factory" to value "org.jipijapa.eclipselink.JBossArchiveFactoryImpl" via jboss-cli.sh command (WildFly server needs to be running when this command is issued):

. The following shows what the standalone.xml (or your WildFly configuration you are using) file might look like after updating the system properties:

You should then be able to deploy applications with persistence.xml that include;

Using Hibernate OGM

The AS7/modules/org/hibernate/ogm folder should contain the OGM jars and the following module.xml:

Native Hibernate use

Applications that use the Hibernate API directly, are referred to here as native Hibernate applications. Native Hibernate applications, can choose to use the Hibernate jars included with WildFly 8 or they can package their own copy of the Hibernate jars. Applications that utilize JPA will automatically have the JBoss AS Hibernate injected onto the application deployment classpath. Meaning that JPA applications, should expect to use the Hibernate jars included in WildFly.

Example MANIFEST.MF entry to add Hibernate dependency:

If you use the Hibernate native api in your application and also use the JPA api to access the same entities (from the same Hibernate session/EntityManager), you could get surprising results (e.g. HibernateSession.saveOrUpdate(entity) is different than EntityManager.merge(entity). Each entity should be managed by either Hibernate native API or JPA code.

Injection of Hibernate Session and SessionFactoryInjection of Hibernate Session and SessionFactory

You can inject a org.hibernate.Session and org.hibernate.SessionFactory directly, just as you can do with EntityManagers and EntityManagerFactorys.

Hibernate properties

WildFly automatically sets the following Hibernate (4.x) properties (if not already set in persistence unit definition):

Property

Purpose

hibernate.id.new_generator_mappings=true

New applications should let this default to true, older applications with existing data might need to set to false (see note below). It really depends on whether your application uses the @GeneratedValue(AUTO) which will generates new key values for newly created entities. The application can override this value (in the persistence.xml).

Persistence unit properties

The following properties are supported in the persistence unit definition (in the persistence.xml file):

Property

Purpose

jboss.as.jpa.providerModule

name of the persistence provider module (default is org.hibernate). Should be hibernate3-bundled if Hibernate 3 jars are in the application archive (adapterModule and adapterClass will automatically be set for hibernate3-bundled). Should be application, if a persistence provider is packaged with the application. See note below about some module names that are built in (based on the provider).

jboss.as.jpa.adapterModule

name of the integration classes that help WildFly to work with the persistence provider. Current valid values are org.jboss.as.jpa.hibernate:4 (Hibernate 4 integration classes) and org.jboss.as.jpa.hibernate:3 (Hibernate 3 integration classes). Other integration adapter modules are expected to be added.

jboss.as.jpa.adapterClass

class name of the integration adapter. Current valid values are org.jboss.as.jpa.hibernate3.HibernatePersistenceProviderAdaptor and org.jboss.as.jpa.hibernate4.HibernatePersistenceProviderAdaptor.

jboss.as.jpa.managed

set to false to disable container managed JPA access to the persistence unit. The default is true, which enables container managed JPA access to the persistence unit. This is typically set to false for Seam 2.x + Spring applications.

jboss.as.jpa.classtransformer

set to false to disable class transformers for the persistence unit. The default is true, which allows class enhancing/rewriting. Hibernate also needs persistence unit property hibernate.ejb.use_class_enhancer to be true, for class enhancing to be enabled.

wildfly.jpa.default-unit

set to true to choose the default persistence unit in an application. This is useful if you inject a persistence context without specifying the unitName (@PersistenceContext EntityManager em) but have multiple persistence units specified in your persistence.xml.

set to false to prevent persistence unit from using the default data source. Defaults to true. This is only important for persistence units that do not specify a datasource.

Determine the persistence provider module

As mentioned above, if the jboss.as.jpa.providerModule property is not specified, the provider module name is determined by the provider name specified in the persistence.xml. The mapping is:

Provider Name

Module name

blank

org.hibernate

org.hibernate.ejb.HibernatePersistence

org.hibernate

org.hibernate.ogm.jpa.HibernateOgmPersistence

org.hibernate:ogm

oracle.toplink.essentials.PersistenceProvider

oracle.toplink

oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider

oracle.toplink

org.eclipse.persistence.jpa.PersistenceProvider

org.eclipse.persistence

org.datanucleus.api.jpa.PersistenceProviderImpl

org.datanucleus

org.datanucleus.store.appengine.jpa.DatastorePersistenceProvider

org.datanucleus:appengine

org.apache.openjpa.persistence.PersistenceProviderImpl

org.apache.openjpa

Binding EntityManagerFactory/EntityManager to JNDI

By default WildFly does not bind the entity manager factory to JNDI. However, you can explicitly configure this in the persistence.xml of your application by setting the jboss.entity.manager.factory.jndi.namehint. The value of that property should be the JNDI name to which the entity manager factory should be bound.

You can also bind a container managed (transaction scoped) entity manager to JNDI as well, }}via hintjboss.entity.manager.jndi.name{}{{. As a reminder, a transaction scoped entity manager (persistence context), acts as a proxy that always gets an unique underlying entity manager (at the persistence provider level).

Here's an example:

persistence.xml

Community

Many thanks to the community, for reporting issues, solutions and code changes. A number of people have been answering Wildfly forum questions related to JPA usage. I would like to thank them for this, as well as those reporting issues. For those of you that haven't downloaded the AS source code and started hacking patches together. I would like to encourage you to start by reading Hacking on WildFly. You will find that it easy very easy to find your way around the WildFly/JPA/* source tree and make changes. Also, new for WildFly, is the JipiJapa project that contains additional integration code that makes EE JPA application deployments work better. The following list of contributors should grow over time, I hope to see more of you listed here.

If you are using EclipseLink with WildFly, please vote for issue https://bugs.eclipse.org/bugs/show_bug.cgi?id=414974 to be fixed. This will help EclipseLink integrate more easily with WildFly (so that system property "eclipselink.archive.factory" will not need to be set).