Skip to end of metadata
Go to start of metadata

Introduction

The JBoss Application Server JPA subsystem implements the JPA 2.0 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 (core) 4.0 persistence provider, that is included with JBoss AS. 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.

In the remainder of this documentation, ”entity manager” refers to an instance of the javax.persistence.EntityManager class. Javadoc for the JPA interfaces http://download.oracle.com/javaee/6/api/javax/persistence/package-summary.html and JPA 2.0 specification. The index of Hibernate documentationis here.

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.

Container-managed Extended Persistence context

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

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.

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
  • DEBUG - informs about entity managers being injected, creating/reusing transaction scoped entity manager for active transaction
  • 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 troubleshoot issues with the Hibernate second level cache, try enabling trace for org.hibernate.SQL + org.hibernate.cache.infinispan + org.infinispan:

Using the Hibernate 4 JPA persistence provider

Hibernate 4 is packaged with the AS 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 cache provider, 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 JBoss Application Server 7, 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.0.x jars with a newer version

Just update the current as7/modules/org/hibernate/main folder to contain the newer version (after stopping your AS7 server instance).  The following instructions assume you are bringing in Hibernate ORM 4.1.1 jars.

  1. Delete *.index files in as7/modules/org/hibernate/main and as7/modules/org/hibernate/envers/main folders.
  2. Backup the current contents of as7/modules/org/hibernate in case you make a mistake.
  3. Remove the older jars and copy new Hibernate jars into as7/modules/org/hibernate/main + as7/modules/org/hibernate/envers/main.
  4. Update the as7/modules/org/hibernate/main/module.xml + as7/modules/org/hibernate/envers/main/module.xml to name the jars that you copied in.

Updated as7/modules/org/hibernate/main/module.xml will look like (note that dependencies won't change):

Updated as7/modules/org/hibernate/envers/module.xml will look like (note that dependencies won't change):

Packaging the Hibernate 3.5 or greater 3.x JPA persistence provider with your application

AS7 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 AS7 testsuite contains a test that packages jars from the Hibernate 3.6.5.Final jars in the ear lib.

Sharing the Hibernate 3.5 or greater JPA persistence provider between multiple applications

Applications can share the same Hibernate3 (for Hibernate 3.5 or greater) persistence provider by manually creating an org.hibernate:3 module (in the AS/modules folder). Steps to create the Hibernate3 module:

  1. In a command shell, go to the AS installation and change into the modules/org folder.
    cd AS/modules/org or cd AS\modules\org\hibernate
  2. Create folder for slot 3 to hold Hibernate 3
    mkdir 3
    cd 3
  3. Copy the Hibernate3 jars into this new AS/modules/org/hibernate/3 folder
    (hibernate3-core.jar, hibernate3-commons-annotations.jar, hibernate3-entitymanager.jar, dom4j.jar, slf4j.jar, slf4j-api.jar, commons-collections.jar, antlr.jar, slf4j-api.jar, commons-collections.jar, antlr.jar and any other jar needed for Hibernate 3).
  4. Create the AS/modules/org/hibernate/3/module.xml file with contents:

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

Using EclipseLink

Read the How to use EclipseLink with AS7 guide here.

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

Example MANIFEST.MF entry to add Hibernate dependency:

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.

Persistence unit properties

AS7 automatically sets the following Hibernate (4.x) properties:

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).
hibernate.transaction.jta.platform= instance of org.hibernate.service.jta.platform.spi.JtaPlatform interface The transaction manager, user transaction and transaction synchronization registry is passed into Hibernate via this class.
hibernate.ejb.resource_scanner = instance of org.hibernate.ejb.packaging.Scanner interface Instance of entity scanning class is passed in that knows how to use the AS annotation indexer (for faster deployment).
hibernate.transaction.manager_lookup_class This property is removed if found in the persistence.xml (could conflict with JtaPlatform)
hibernate.session_factory_name = qualified persistence unit name
Is set to the application name + persistence unit name (application can specify a different value but it needs to be unique across all application deployments on the AS instance).
hibernate.session_factory_name_is_jndi = false
only set if the application didn't specify a value for hibernate.session_factory_name.
hibernate.ejb.entitymanager_factory_name =  qualified persistence unit name Is set to the application name + persistence unit name (application can specify a different value but it needs to be unique across all application deployments on the AS instance).

In Hibernate 4.x, if new_generator_mappings is true:

  • @GeneratedValue(AUTO) maps to org.hibernate.id.enhanced.SequenceStyleGenerator
  • @GeneratedValue(TABLE) maps to org.hibernate.id.enhanced.TableGenerator
  • @GeneratedValue(SEQUENCE) maps to org.hibernate.id.enhanced.SequenceStyleGenerator

In Hibernate 4.x, if new_generator_mappings is false:

  • @GeneratedValue(AUTO) maps to Hibernate "native"
  • @GeneratedValue(TABLE) maps to org.hibernate.id.MultipleHiLoPerTableGenerator
  • @GeneratedValue(SEQUENCE) to Hibernate "seqhilo"

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

Property
Purpose
jboss.as.jpa.providerModule is the 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.
jboss.as.jpa.adapterModule is the name of the integration classes that help the AS 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 is the 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 can be 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.

Binding EntityManagerFactory to JNDI

By default JBoss AS7 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.name property. The value of that property should be the JNDI name to which the entity manager factory should be bound. 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 AS7 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 AS7. You will find that it easy very easy to find your way around the AS7/JPA/* source tree and make changes. The following list of contributors should grow over time, I hope to see more of you listed here.

People who have contributed to the AS7 JPA layer:

Hall of fame

For answering JPA related AS questions in the forums:

  • Prasad Deshpande has reported issues but more importantly, has been answering others JPA related questions as well.

If you see someone answering JPA related questions in the forums,or if I left you out (and you have been answering JPA questions), add the name to the above list.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Aug 03, 2012

    How does "Binding EntityManager to JNDI" work.

    The line

    <property name="jboss.entity.manager.jndi.name" value="java:jboss/myEntityManager"/>

    seems not to work any more;-(

    Is only the EntityManagerFactory supported in JBoss 7 and not the EntityManager itself?

    1. Aug 03, 2012

      Yes, currently only the jboss.entity.manager.factory.jndi.name property is supported in JBoss 7. 

      The @PersistenceContext annotation can also help you (just specify the jndi name via "name"):

  2. Sep 30, 2012

    If you are using Spring framework for DI, you may also need to do something like this in your Spring application context configuration file:

  3. Sep 17, 2013

    The document is very well written so thanks for that. I'm using @PersistenceContext for injecting an EntityManager into a SLSB. But for some reason an EntityManager is not injected which further results in causing NullPointerException during query creation. The reason behind using @PersistenceContext is to use container-managed persistence context. Now if I run Persistence.createEntityManagerFactory("unitName") in the debug window it returns a valid EntityManager. I believe that is because Seam is responsible for creating that EntityManager. The application I have is a seam based application and uses Hibernate 3 and I plan to run this app on JBOSS 7.1.1.Final.

    Any idea why @PersistenceContext is not injecting an EntityManager?

    My environment:* JBOSS 7.1.1.FINAL

    • Uses seam framework: jboss-seam-2.2.1.CR2.jar
    • Uses Hibernate 3.4.0.GA

    main-ear.ear

    __META-INF
      ____jboss-deployment-structure.xml
      ____application.xml
      ____jboss-app.xml
      ____MANIFEST.MF
    __lib
      ____somejar.jar
      ____somejar.jar
    __ejb-jar-1.jar
      ____META-INF
      ____persistence.xml
    __ejb-jar-2.jar
    __jboss-seam-2.2.1.CR2.jar
    __commons-lang-2.4.jar
    __commons-codec-1.1.jar
    __jasypt-1.6.jar
    __app-war.war
    ____components.xml