6 Using TopLink with IBM WebSphere Application Server
This chapter includes the following sections:
Use Case
TopLink can be used with a number of popular Java EE application servers, including WebSphere Application Server.
Solution
Configure WebSphere to use EclipseLink runtime, and deploy applications developed using EclipseLink APIs.
Components
-
TopLink 12c (12.1.2.0.0) or later.
Note:
TopLink's core functionality is provided by EclipseLink, the open source persistence framework from the Eclipse Foundation. EclipseLink implements Java Persistence API (JPA), Java Architecture for XML Binding (JAXB), and other standards-based persistence technologies, plus extensions to those standards. TopLink includes all of EclipseLink, plus additional functionality from Oracle.
-
EclipseLink 2.4 or later.
-
WebSphere Application Server 7 or later. These instructions are based on WebSphere 8.5.
-
A compliant Java Database Connectivity (JDBC) database, such as Oracle Database, Oracle Express, MySQL, the Derby database included in WebSphere Application Server, and so on.
Introduction to the Solution
WebSphere Application Server implements Java Platform, Enterprise Edition (Java EE). WebSphere V8.5 fully supports Java EE 6 and can support Java Platform, Standard Edition (Java SE) 7 via a plugin.
By configuring WebSphere support EclipseLink, you can create and deploy applications that take advantage of EclipseLink's full support for Java Persistence API (JPA), as well as EclipseLink's many extensions.
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:
-
IBM WebSphere, Version 7 or later. These instructions are based on WebSphere, Version 8.5.
Obtain IBM WebSphere from
http://www-01.ibm.com/software/webservers/appserv/was/
. -
TopLink 12c (12.1.2.0.0) or later.
Download TopLink from
http://www.oracle.com/technetwork/middleware/toplink/downloads/index.html
.You will use the following files:
-
eclipselink.jar
, located in theoracle_common\modules\oracle.toplink_
ver_no
directory created by the TopLink quick installer -
javax.persistence_
ver_no
.jar
, located in theoracle_common\modules
directory created by the TopLink quick installer
EclipseLink 2.4 or later.
Download EclipseLink from
http://www.eclipse.org/eclipselink/downloads/
.You will use the following files:
-
eclipselink.jar
-
javax.persistence_
ver_no
.jar
-
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
valueWebSphere_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 topersistence_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)
-
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 TopLink 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
, andMDSYS.SDO_GEOMETRY
with JPA, you must also includexdb.jar
andsdoapi.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.
-
-
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.
Additional Resources
See the following resources for more information about the technologies and tools used to implement the solutions in this chapter:
-
WebSphere Application Server at
http://www-01.ibm.com/software/webservers/appserv/was/
.