Using third-party persistence providers

Java™ Persistence API (JPA) for WebSphere® Application Server supports third-party persistence providers in their application server environment.

About this task

Java EE applications that use JPA functions can employ third-party persistence providers other than the providers that are included with the application server. Applications can also specify an Apache OpenJPA provider that is a different version than what is included with the application server, as long as the same version of the JPA specification is supported.

There are two basic means to incorporate third-party providers into an application:
  • Embedding the persistence provider inside an application
  • Using shared libraries
Depending on your requirements, you can embed a persistence provider inside an application, or place the persistence provider into a shared library.
Note: Enablement of third-party JPA run times and the deployment of their applications are supported on WebSphere Application Server. However, no support is provided for resolving JAR file conflict problems or problems that a stack trace indicates are in the third-party code.

Procedure

  • Embedding a third-party persistence provider within an application
    Sometimes an application design must rely on the implementation of a specific persistence provider. The JPA specification permits embedding of a specific JPA provider within a persistence archive. When building the application, you can assemble a specific version of a provider implementation in the application enterprise archive (EAR) file or in a web application (WAR) file. To embed a third-party persistence provider into an application, you must inspect the application design and all dependent prerequisites. Use the following steps to embed a persistence provider inside an application:
    1. Modify the <provider> element to specify explicitly which persistence provider to use to access the persistence entity.
    2. Build the specific version of the third-party persistence provider into the application.
      To manage the persistence correctly, verify that the EntityManagerFactory and the EntityManager are calling the correct provider. Many providers write startup and version information to standard output, which gets included in the SystemOut.log of the application server. This information can be helpful to determine if a third-party provider is being used by your application.
      Note: This topic references one or more of the application server log files. As a recommended alternative, you can configure the server to use the High Performance Extensible Logging (HPEL) log and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM® i systems. You can also use HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access all of your log and trace information using the LogViewer command-line tool from your server profile bin directory. See the information about using HPEL to troubleshoot applications for more information on using HPEL.
    3. To use a third-party JPA provider that was not bundled with the application server, configure the class loader order for your application to load the classes with the application class loader first. This is also required if the third-party JPA provider is defined in a shared library that is assigned to a user-defined class loader on the server. If the class loader is not configured properly, the third-party JPA provider that is included with the application server is not loaded and used by your application.
    4. Depending on how you packaged the provider, perform one of the following steps:
      • If you packaged the provider in an EAR file, specify the third-party persistence provider binaries in the Manifest.mf class path in those application modules that needs JPA access.
      • If the provider was bundled in a WAR file, include the necessary provider binaries in the WEB-INF/lib directory of the web application.
    5. Install your application normally.
    This configuration localizes the availability of the provider and limiting it to the application alone. While sometimes necessary, embedding persistence providers increases the application memory footprint accordingly.
  • Using shared libraries to implement a third-party persistence provider
    Persistence providers accessed by applications in a global environment can be installed as a shared library for the application server. Depending on your requirements, you can share the library to the server and application. Use the following steps to implement a third-party persistence provider using shared libraries:
    1. Modify the <provider> element to specify explicitly which persistence provider to use to access the persistence entity.
    2. Define the persistence provider in a shared library. See the topic on creating shared libraries for more information.
    3. Associate the shared library with the application class loader, or associate the shared library with the server class loader if the library is accessed by many applications.
    4. Configure the class loader order for your application to load the classes with the application class loader first. This is required if the third-party JPA provider is included in the application or if it is defined in a shared library. If the class loader is not configured properly, the JPA provider that is included with the application server is used by your application instead of the third-party JPA provider.
    When the application starts, the specified persistence provider is resolved. From this point on, all persistence requests are handled by this provider.
  • A shared library persistence provider can override an existing persistence provider that is the same type and exists in your application class loader hierarchy. If a shared library persistence provider overrides the persistence provider that is shipped with the product, it is recommended that you use an isolated class loader for the shared library. See the topic, Creating shared libraries, for more information.