Deploying a JPA application to Liberty

To enable Liberty to support an application that uses the Java™ Persistence API (JPA), you add the jpa-2.0, jpa-2.1, or jpaContainer-2.1 feature to the server.xml file, depending on which specification level you need. You also need to define persistence contexts and persistence units, and configure access to the entity manager and entity manager factory.

Stabilized feature: The jpa-2.0 feature is stabilized. You can continue to use the jpa-2.0 feature. However, consider using a later JPA feature.

Before you begin

This task assumes that you created a Liberty server, on which you want to deploy an application that uses JPA.

About this task

The following JPA features are available in Liberty:

The jpa-2.0 feature supports applications that use application-managed and container-managed JPA written to the JPA 2.0 specification. The support is built on Apache OpenJPA with extensions to support the container-managed programming model.
The jpa-2.1 feature supports applications that use application-managed and container-managed JPA written to the JPA 2.1 specification. The support is built on EclipseLink. If the built-in EclipseLink JPA privier is not being utilized, you may want to use the jpaContainer-2.1 feature instead in order to minimize the server runtime image.
The jpaContainer-2.1 feature supports applications that use application-managed and container-managed JPA written to the JPA 2.1 specification. This feature does not include a built-in JPA provider. The user must supply a JPA provider through a shared library, the global library, or embedded in the application.

For information about developing JPA applications with WebSphere® Developer Tools, see Developing JPA applications.

Procedure

Add the jpa-2.0, jpa-2.1, or jpaContainer-2.1 feature to the server.xml file.

Add persistence context and persistence unit definitions to the web.xml file.

For example:

<persistence-context-ref>
    <persistence-context-ref-name>example/em</persistence-context-ref-name>
    <persistence-unit-name>ExamplePersistenceUnit</persistence-unit-name>
</persistence-context-ref> 

<persistence-unit-ref>
    <persistence-unit-ref-name>example/emf</persistence-unit-ref-name>
    <persistence-unit-name>ExamplePersistenceUnit</persistence-unit-name>
</persistence-unit-ref>

Configure access to the entity manager.

For example:

Context ctx = new InitialContext();
UserTransaction tran = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
tran.begin();
EntityManager em = (EntityManager) ctx.lookup("java:comp/env/example/em");
Thing thing = new Thing();
em.persist(thing);
tran.commit();

Configure access to the entity manager factory.

For example:

Context ctx = new InitialContext();
EntityManagerFactory emf = (EntityManagerFactory) ctx.lookup("java:comp/env/example/emf");
EntityManager em = emf.createEntityManager();
EntityTransaction tx = em.getTransaction();
tx.begin();
Thing thing = new Thing();
em.persist(thing);
tx.commit();
int id = thing.getId();
em.close();

If you use the jpaContainer-2.1 feature, make the JPA provider JAR files available.
Choose one of the following options:
- Put the JPA provider JAR files in the global library location to make them available to all applications.
- Update the server configuration to supply the JPA provider JAR files as a shared library to the application.
  For example, complete the following steps:
  
  In your server configuration file, configure a shared library for the necessary JPA persistence provider. Make the library available to the applications that use it. The following example illustrates the minimum required set of jar files to use EclipseLink as a JPA 2.1 provider, with no extension. The following jars may also be included to take advantage of EclipseLink extensions:
  
  org.eclipse.persistence.dbws.jar
  
  org.eclipse.persistence.moxy.jar
  
  <library id="eclipselink"> <file name="${server.config.dir}/jpa/org.eclipse.persistence.asm.jar/> <file name="${server.config.dir}/jpa/org.eclipse.persistence.core.jar"/> <file name="${server.config.dir}/jpa/org.eclipse.persistence.jpa.jar"/> <file name="${server.config.dir}/jpa/org.eclipse.persistence.antlr.jar"/> <file name="${server.config.dir}/jpa/org.eclipse.persistence.jpa.jpql.jar"/> <file name="${server.config.dir}/jpa/org.eclipse.persistence.jpa.modelgen.jar"/> </library> <application location="myApp.war"> <classloader commonLibraryRef="eclipselink"/> </application>
  To use hibernate as a JPA provider, include the following set of jar files in the <library> configuration instead.
  
  <library id="hibernate"> <file name="${server.config.dir}/hibernate/antlr-2.7.7.jar"/> <file name="${server.config.dir}/hibernate/classmate-1.3.0.jar"/> <file name="${server.config.dir}/hibernate/dom4j-1.6.1.jar"/> <file name="${server.config.dir}/hibernate/hibernate-commons-annotations-5.0.1.Final.jar"/> <file name="${server.config.dir}/hibernate/hibernate-core-5.2.6.Final.jar"/> <file name="${server.config.dir}/hibernate/javassist-3.20.0-GA.jar"/> <file name="${server.config.dir}/hibernate/jboss-logging-3.3.0.Final.jar"/> </library>
  
  Choose one of the following ways to identify the JPA provider class:
  
  Configure the default persistence provider on the JPA element in the server configuration. This configuration overrides any PersistenceProvider services that are discovered by <bell> elements:
  <jpa defaultPersistenceProvider="org.eclipse.persistence.jpa.PersistenceProvider"/>
  For Hibernate, use:
  <jpa defaultPersistenceProvider="org.hibernate.jpa.HibernatePersistenceProvider"/>
  
  If the jpaContainer-2.1 feature is being used, configure the bells-1.0 feature in the server configuration and add a bell for the shared library.
  The shared library locates the JPA provider class automatically and makes it the default JPA persistence provider. This configuration overrides the defaultPersistenceProvider attribute that is configured on the JPA element.
  
  <featureManager> <feature>jpaContainer-2.1</feature> <feature>bells-1.0</feature> ... </featureManager> <bell libraryRef="eclipselink"/>
  
  Specify the JPA persistence provider class in the persistence.xml file. This class takes precedence over the server.xml configuration (either the <jpa> element or the <bell> elements) for the persistence unit.
  <persistence-unit name="MY_PERSISTENCE_UNIT"> <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider> ... </persistence-unit>