Use third-party persistence providers

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

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

• Use shared libraries

Depending on the requirements, we can embed a persistence provider inside an application, or place the persistence provider into a shared library.

• 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, we can assemble a specific version of a provider implementation in the application 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 the application.

     This topic references one or more of the application server log files. As a recommended alternative, we 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. We can also use HPEL in conjunction with the native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the 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 the 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 assigned to a user-defined class loader on the server. If the class loader is not configured properly, the third-party JPA provider included with the application server is not loaded and used by the application.

  4. Depending on how you packaged the provider, perform one of the following steps:

     • If we 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 the 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.

• Use 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 the requirements, we 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 the 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 included with the application server is used by the 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 the application class loader hierarchy. If a shared library persistence provider overrides the persistence provider that is shipped with the product, IBM recommends that you use an isolated class loader for the shared library. See the topic, Creating shared libraries, for more information.

Related tasks

Configure the JPA default persistence provider

Create shared libraries

Configure class loaders of a server

Use High Performance Extensible Logging to troubleshoot applications