Migrate WebSphere JPA Persistence Providers to Red Hat JBoss Enterprise Application Platform

Updated -


IBM WebSphere Application Server V8.5.5 provides two persistence providers in the product. One is the Apache OpenJPA persistence provider, which is based on the Apache OpenJPA 2.x open source project. WebSphere also provides the JPA for WebSphere Application Server persistence provider. This is the default provider and adds extensions to Apache OpenJPA to provide additional features, functionality, and tools for WebSphere application development and deployment.

The default JPA persistence provider for Red Hat JBoss Enterprise Application Platform is Hibernate EntityManager. However, you can configure a JBoss module for the Apache OpenJPA persistence provider. WebSphere applications that use JPA for WebSphere Application Server require code changes for the IBM specific extensions.

Choose one of the following options to migrate these persistence providers to JBoss EAP 6.

Migrate Applications using Apache OpenJPA

Applications that use Apache OpenJPA should require minimal changes to run on JBoss EAP. You must define a module for Apache OpenJPA and tell JBoss EAP to use it.

  1. Create a directory structure under the EAP_HOME/module/system/layers/base/org/apache/ directory to contain the OpenJPA JARs and the module.xml file. For example:

    $ cd EAP_HOME/modules/system/layers/base/org/apache/
    $ mkdir -p openjpa/main/
  2. Copy the following JARs to the EAP_HOME/modules/system/layers/base/org/apache/openjpa/main/ directory.

    • openjpa-2.1.0.jar
    • serp-1.13.1.jar
  3. Create a module.xml file in the EAP_HOME/modules/system/layers/base/org/apache/openjpa/main/ directory directory containing the following XML:

    <module xmlns="urn:jboss:module:1.1" name="org.apache.openjpa">
            <resource-root path="openjpa-2.1.0.jar"/>
            <resource-root path="serp-1.13.1.jar"/>
            <!-- Insert resources here -->
            <module name="javax.persistence.api"/>
            <module name="javax.transaction.api"/>
            <module name="javax.validation.api"/>
            <module name="org.apache.commons.lang"/>
            <module name="org.apache.commons.collections"/>
            <module name="org.apache.log4j"/>       
  4. The jboss.as.jpa.providerModule property in the persistence.xml file specifies the name of the JPA persistence provider module. Add the following property to the persistence.xml file:

    <property name="jboss.as.jpa.providerModule" value="openjpa" />

Migrate Applications using JPA for WebSphere Application Server

Although JPA for WebSphere Application Server is built upon the Apache OpenJPA open source project, it contains extensions that are specific to WebSphere. For this reason, you cannot package this provider as a module in JBoss EAP. You must remove or replace any code using the extensions and configure the application to use the Apache OpenJPA persistence provider.

  1. Remove or replace any code that uses the JPA for WebSphere Application Server extensions. Examples of these extensions include:

    • Static SQL support using the DB2 pureQuery feature
    • Access intent support
    • Enhanced tracing support
    • Version ID generation
    • WebSphere product-specific commands and scripts
    • Translated message files
    • Check in-memory caches for lazily loaded many-to-one or one-to-one relationships.
  2. Some of the default configuration property values for the JPA for WebSphere Application Server persistence provider are different from the Apache OpenJPA provider. The following are examples of properties that have different default values.

    • openjpa.Compatibility:

      • Apache OpenJPA defaults to StrictIdentityValues=false.
      • JPA for WebSphere Application Server defaults to StrictIdentityValues=true.
    • openjpa.RuntimeUnenhancedClasses

      • Apache OpenJPA defaults to unsupported.
      • JPA for WebSphere Application Server defaults to warn.
    • openjpa.DynamicEnhancementAgent

      • Apache OpenJPA defaults to true.
      • JPA for WebSphere Application Server defaults to false.
    • openjpa.DriverDataSource

      • Apache OpenJPA defaults to auto.
      • JPA for WebSphere Application Server defaults to simple.
  3. Search for uses of the following JPA for WebSphere Application Server classes. These classes override the corresponding Apache OpenJPA classes. You must modify the code to use the Apache OpenJPA classes.

    • com.ibm.ws.persistence.jdbc.kernel.ConstraintUpdateManager;
    • com.ibm.ws.persistence.jdbc.kernel.ConstraintUpdateManager;
    • com.ibm.ws.persistence.jdbc.kernel.WsJpaJDBCBrokerFactory;
    • com.ibm.ws.persistence.jdbc.sql.DB2Dictionary;
    • com.ibm.ws.persistence.jdbc.sql.OracleDictionary;
    • com.ibm.ws.persistence.jdbc.sql.SQLFactoryImpl;
    • com.ibm.ws.persistence.jdbc.sql.SQLServerDictionary;
    • com.ibm.ws.persistence.kernel.WsJpaBrokerImpl;
    • com.ibm.ws.persistence.kernel.WsJpaFinalizingBrokerImpl;
  4. When you are sure your application uses only the Apache OpenJPA API, follow the instructions above to Migrate Applications using Apache OpenJPA.

Modify the Application Code to Use the Hibernate JPA API

Another option is to rewrite the application code to use Hibernate JPA. For more information about the JBoss EAP Hibernate JPA implementation, see Java Persistence API (JPA) in the Development Guide for JBoss Enterprise Application Platform.