Deploy a JPA application to Liberty

To enable Liberty to support an application that uses the Java Persistence API (JPA), we add the jpa-2.0, jpa-2.1, or jpaContainer-2.1 feature to the server.xml file, depending on which specification level we need. We 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. We can continue to use the jpa-2.0 feature. However, consider using a later JPA feature.

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

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 Develop JPA applications.

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

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

      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 we 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 the 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

        To use hibernate as a JPA provider, include the following set of jar files in the <library> configuration instead.

      • 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 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>