EclipseLink Solutions Guide for EclipseLink
Release 2.5
  Go To Table Of Contents
 Search
 PDF

Implementing the Solution

To develop, deploy, and run EclipseLink applications in IBM WebSphere, you must add various modules including EclipseLink to WebSphere, and you must configure various aspects of WebSphere to support EclipseLink.

This section contains the following tasks for using EclipseLink with IBM WebSphere, Version 7 or later:

Task 1: Prerequisites

Ensure that you have installed the following components:

Task 2: Configure Persistence Units

Configure persistence units to use EclipseLink as the persistence provider and to use WebSphere as the target server.

Example 6-1 shows a sample configuration for a container-managed persistence unit.

Example 6-1 Sample persistence.xml for a container-managed persistence unit

<persistence xmlns="http://java.sun.com/xml/ns/persistence" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
      xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_1_0.xsd"
      version="1.0">
    <persistence-unit name="default" transaction-type="JTA">
        <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <jta-data-source>jdbc/EclipseLinkDS</jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.target-server" value="WebSphere_7"/>
            <property name="eclipselink.target-database"
                value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
            <property name="eclipselink.validate-existence" value="true"/>
            <property name="eclipselink.weaving" value="true"/>
            <property name="eclipselink.logging.level" value="FINEST"/>
        </properties>
    </persistence-unit>
</persistence>

Example 6-2 shows a sample configuration for an application-managed persistence unit.

Example 6-2 Sample persistence.xml for an application-managed persistence unit

<persistence xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence persistence_1_0.xsd" version="1.0">
    <persistence-unit name="default" transaction-type="RESOURCE_LOCAL">
        <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <non-jta-data-source>jdbc/ELNonJTADS</non-jta-data-source>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="eclipselink.target-server" value="WebSphere_7"/>
            <property name="eclipselink.target-database" 
                  value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/>
            <property name="eclipselink.validate-existence" value="true"/>
            <property name="eclipselink.weaving" value="true"/>
            <property name="eclipselink.logging.level" value="FINEST"/>
        </properties>
    </persistence-unit>
</persistence>

Note the following about the two examples above:

  • The eclipselink.target-server value WebSphere_7 is used for WebSphere Application Server version 7 and later.

  • Specifying persistence_1_0.xsd" version="1.0" for the persistence schema version works with both JPA 1 and JPA 2. For a JPA 2.n -only application, you can change the version to persistence_2_0.xsd" version="2.n" (WebSphere's support for JPA 2 began in WebSphere Application Server 7.0.0.9.

Task 3: Configure the Server and the Application to Use EclipseLink

The following are typical scenarios for using EclipseLink with the application server:

Modify Server to Make EclipseLink Available Globally

You can make EclipseLink available globally for both container-managed and application-managed persistence units in either of the following ways:

Option 1: Create a Global Shared Library (Recommended)

  1. Create a global shared library containing the following files:

    • eclipselink.jar

      Find this file in the TOPLINK_INSTALLATION\oracle_common\modules\oracle.toplink_ver_no directory created by the EclipseLink quick installer.

    • xmlparserv2.jar

      Find this file in the TOPLINK_INSTALLATION\toplink\modules directory created by the s quick installer.

    • If you use Oracle Database features such as NCHAR, XMLTYPE, and MDSYS.SDO_GEOMETRY with JPA, you must also include xdb.jar and sdoapi.jar in the shared library. Those files are available in your Oracle Database distribution.

    See the WebSphere documentation for instructions on how to use WebSphere to facilitate the creation of shared libraries.

  2. Associate the shared library with the application.

    See the WebSphere documentation for instructions on how to use WebSphere to associate the shared library with an application.

Option 2: Add EclipseLink as a Server Library Extension

To add EclipseLink as a server library extension, copy eclipselink.jar and the other JAR file(s) listed in Option 1, above, to the WAS_HOME\lib\ext directory.

Package EclipseLink in the Application EAR

You can also implement container-managed persistence by adding eclipselink.jar in the application EAR, without making any modifications to the server configuration. In this case, the persistence unit is managed by @PersistenceContext entity manager proxy injection on a stateless session bean. The following instructions show a example of this approach.

  1. Add eclipselink.jar to the application EAR in the following location:

    EAR_archive/APP-INF/lib/

  2. Add the path to the eclipselink.jar to the ejbModule/META-INF/MANIFEST.MF file(s) in your EJB JAR(s), as shown below:

    Manifest-Version: 1.0
    Class-Path: APP-INF/lib/eclipselink.jar
    

    This is the manifest at the root of the entities' location, in this case as part of the ejb.jar.

  3. Configure the class loader to load the classes with the application class loader first.

  4. Deploy and start the application. See the IBM WebSphere documentation for instructions.

Package EclipseLink in the WAR

If you do not or cannot implement container-managed persistence, as described in the previous two scenarios, you can create an application managed entity manager. In this case, all library configuration and classloader scope changes must be done inside the EAR itself.

  1. Add eclipselink.jar and javax.persistence_ver_no.jar to the web application archive (WAR) file in the following location:

    WAR_archive/WEB-INF/lib/

  2. Configure the class loader order for your application to load the classes with the application class loader first. See the WebSphere documentation for instructions on setting class loader order using the Administrative console.

  3. Deploy and start the application. See the IBM WebSphere documentation for instructions.