blob: 33de18de4d6050e88bd9d5d2912b21686ec8fe80 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Implementing the Solution | EclipseLink 2.7 Understanding EclipseLink</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 1.0.22 Build 1" />
<meta name="date" content="2014-06-10T10:35:14Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Implementing the Solution" />
<meta name="relnum" content="Release 2.7" />
<link rel="stylesheet" type="text/css" href="../../dcommon/style.css" media="screen" />
<link rel="copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="start" href="../../index.htm" title="Home" type="text/html" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="prev" href="websphere001.htm" title="Previous" type="text/html" />
<link rel="next" href="websphere003.htm" title="Next" type="text/html" />
<!-- START: Disqus --><script type="text/javascript"> var disqus_developer = 0; </script><!-- END: Disqus --><!-- START: Sharethis --><script type="text/javascript">var switchTo5x=true;</script><script type="text/javascript" src="http://w.sharethis.com/button/buttons.js"></script><script type="text/javascript" src="http://s.sharethis.com/loader.js"></script> <!-- END: Sharethis --></head>
<body bgcolor="#FFFFFF"><iframe id="docheader" frameborder="0" framemargin="0" scrolling="no" src="../../dcommon/header.html"></iframe><script src="http://www.google.com/jsapi" type="text/javascript"></script><script type="text/javascript"> google.load('search', '1', {language : 'en'}); google.setOnLoadCallback(function() { var customSearchOptions = {}; var googleAnalyticsOptions = {}; googleAnalyticsOptions['queryParameter'] = 'q'; googleAnalyticsOptions['categoryParameter'] = ''; customSearchOptions['googleAnalyticsOptions'] = googleAnalyticsOptions; var customSearchControl = new google.search.CustomSearchControl( '016171230611334810008:enkkfjmsqju', customSearchOptions); customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET); var options = new google.search.DrawOptions(); options.setSearchFormRoot('cse-search-form'); customSearchControl.draw('cse', options); }, true);</script><link rel="stylesheet" href="http://www.google.com/cse/style/look/default.css" type="text/css" /><div id="cse" style="width:100%;"></div>
<div class="header"><a id="top" name="top"></a>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><font face="helvetica, arial, sans-serif"><b>EclipseLink Solutions Guide for EclipseLink</b><br />
Release 2.7</div></td>
<td valign="bottom" align="right" width="144">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<tr>
<td align="center"><a href="websphere001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="websphere003.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
<td>&nbsp;</td>
</tr>
</table>
</div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="A1584318" name="A1584318"></a><a id="TLADG770" name="TLADG770"></a>
<div class="sect1"><!-- infolevel="all" infotype="General" -->
<h1 class="sect1"><font face="arial, helvetica, sans-serif" color="#330099">Implementing the Solution</font></h1>
<p>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.</p>
<p>This section contains the following tasks for using EclipseLink with IBM WebSphere, Version 7 or later:</p>
<ul>
<li>
<p><a href="#CFHIHHBB">Task 1: Prerequisites</a></p>
</li>
<li>
<p><a href="#CEGCHAJB">Task 2: Configure Persistence Units</a></p>
</li>
<li>
<p><a href="#CEGCGFJB">Task 3: Configure the Server and the Application to Use EclipseLink</a></p>
</li>
</ul>
<a id="CFHIHHBB" name="CFHIHHBB"></a><a id="TLADG771" name="TLADG771"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Task 1: Prerequisites</font></h2>
<p>Ensure that you have installed the following components:</p>
<ul>
<li>
<p>IBM WebSphere, Version 7 or later. These instructions are based on WebSphere, Version 8.5.</p>
<p>Obtain IBM WebSphere from <code><a href="http://www-01.ibm.com/software/webservers/appserv/was/">http://www-01.ibm.com/software/webservers/appserv/was/</a></code>.</p>
</li>
<li>
<p>EclipseLink 2.4 or later.</p>
<p>Download EclipseLink from <code><a href="http://www.eclipse.org/eclipselink/downloads/">http://www.eclipse.org/eclipselink/downloads/</a></code>.</p>
<p>You will use the following files:</p>
<ul>
<li>
<p><code>eclipselink.jar</code></p>
</li>
<li>
<p><code>javax.persistence_</code><em><code>ver_no</code></em><code>.jar</code></p>
</li>
</ul>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="CEGCHAJB" name="CEGCHAJB"></a><a id="TLADG1105" name="TLADG1105"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Task 2: Configure Persistence Units</font></h2>
<p>Configure persistence units to use EclipseLink as the persistence provider and to use WebSphere as the target server.</p>
<p><a href="#CEGCBJCA">Example 6-1</a> shows a sample configuration for a container-managed persistence unit.</p>
<div class="example"><a id="CEGCBJCA" name="CEGCBJCA"></a><a id="TLADG1106" name="TLADG1106"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 6-1 Sample persistence.xml for a container-managed persistence unit</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;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"&gt;
&lt;persistence-unit name="default" transaction-type="JTA"&gt;
<strong>&lt;provider&gt;org.eclipse.persistence.jpa.PersistenceProvider&lt;/provider&gt;</strong>
&lt;jta-data-source&gt;jdbc/EclipseLinkDS&lt;/jta-data-source&gt;
&lt;exclude-unlisted-classes&gt;false&lt;/exclude-unlisted-classes&gt;
&lt;properties&gt;
&lt;<strong>property name="eclipselink.target-server" value="WebSphere_7"</strong>/&gt;
&lt;property name="eclipselink.target-database"
value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/&gt;
&lt;property name="eclipselink.validate-existence" value="true"/&gt;
&lt;property name="eclipselink.weaving" value="true"/&gt;
&lt;property name="eclipselink.logging.level" value="FINEST"/&gt;
&lt;/properties&gt;
&lt;/persistence-unit&gt;
&lt;/persistence&gt;
</pre></div>
<!-- class="example" -->
<p><a href="#CEGBBBJE">Example 6-2</a> shows a sample configuration for an application-managed persistence unit.</p>
<div class="example"><a id="CEGBBBJE" name="CEGBBBJE"></a><a id="TLADG1107" name="TLADG1107"></a>
<p><strong><em><font face="arial, helvetica, sans-serif">Example 6-2 Sample persistence.xml for an application-managed persistence unit</font></em></strong></p>
<pre xml:space="preserve" class="oac_no_warn">
&lt;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"&gt;
&lt;persistence-unit name="default" transaction-type="RESOURCE_LOCAL"&gt;
&lt;provider&gt;org.eclipse.persistence.jpa.PersistenceProvider&lt;/provider&gt;
&lt;non-jta-data-source&gt;jdbc/ELNonJTADS&lt;/non-jta-data-source&gt;
&lt;exclude-unlisted-classes&gt;false&lt;/exclude-unlisted-classes&gt;
&lt;properties&gt;
<strong> &lt;property name="eclipselink.target-server" value="WebSphere_7"/&gt;</strong>
&lt;property name="eclipselink.target-database"
value="org.eclipse.persistence.platform.database.oracle.Oracle11Platform"/&gt;
&lt;property name="eclipselink.validate-existence" value="true"/&gt;
&lt;property name="eclipselink.weaving" value="true"/&gt;
&lt;property name="eclipselink.logging.level" value="FINEST"/&gt;
&lt;/properties&gt;
&lt;/persistence-unit&gt;
&lt;/persistence&gt;
</pre></div>
<!-- class="example" -->
<p>Note the following about the two examples above:</p>
<ul>
<li>
<p>The <code>eclipselink.target-server</code> value <code>WebSphere_7</code> is used for WebSphere Application Server version 7 and later.</p>
</li>
<li>
<p>Specifying <code>persistence_1_0.xsd" version="1.0"</code> for the persistence schema version works with both JPA 1 and JPA 2. For a JPA 2.<em>n</em> -only application, you can change the version to <code>persistence_2_0.xsd" version="2.</code><em>n</em><code>"</code> (WebSphere's support for JPA 2 began in WebSphere Application Server 7.0.0.9.</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="CEGCGFJB" name="CEGCGFJB"></a><a id="TLADG1108" name="TLADG1108"></a>
<div class="sect2"><!-- infolevel="all" infotype="General" -->
<h2 class="sect2"><font face="arial, helvetica, sans-serif" color="#330099">Task 3: Configure the Server and the Application to Use EclipseLink</font></h2>
<p>The following are typical scenarios for using EclipseLink with the application server:</p>
<ul>
<li>
<p><a href="#CEGFHBBI"><strong>Modify Server to Make EclipseLink Available Globally</strong></a></p>
</li>
<li>
<p><a href="#CEGFFJEA"><strong>Package EclipseLink in the Application EAR</strong></a></p>
</li>
<li>
<p><a href="#CEGJBCHB"><strong>Package EclipseLink in the WAR</strong></a></p>
</li>
</ul>
<a id="CEGFHBBI" name="CEGFHBBI"></a><a id="TLADG1109" name="TLADG1109"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Modify Server to Make EclipseLink Available Globally</font></h3>
<p>You can make EclipseLink available globally for both container-managed and application-managed persistence units in either of the following ways:</p>
<ul>
<li>
<p><a href="#CEGGAEGJ">Option 1: Create a Global Shared Library (Recommended)</a></p>
</li>
<li>
<p><a href="#CEGGCCFC">Option 2: Add EclipseLink as a Server Library Extension</a></p>
</li>
</ul>
<a id="CEGGAEGJ" name="CEGGAEGJ"></a><a id="TLADG1110" name="TLADG1110"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Option 1: Create a Global Shared Library (Recommended)</font></b></p>
<ol>
<li><a id="CEGDEIEC" name="CEGDEIEC"></a>
<p>Create a global shared library containing the following files:</p>
<ul>
<li>
<p><code>eclipselink.jar</code></p>
<p>Find this file in the <em><code>TOPLINK_INSTALLATION</code></em><code>\oracle_common\modules\oracle.toplink_</code><em><code>ver_no</code></em> directory created by the EclipseLink quick installer.</p>
</li>
<li>
<p><code>xmlparserv2.jar</code></p>
<p>Find this file in the <em><code>TOPLINK_INSTALLATION</code></em><code>\toplink\modules</code> directory created by the s quick installer.</p>
</li>
<li>
<p>If you use Oracle Database features such as <code>NCHAR</code>, <code>XMLTYPE</code>, and <code>MDSYS.SDO_GEOMETRY</code> with JPA, you must also include <code>xdb.jar</code> and <code>sdoapi.jar</code> in the shared library. Those files are available in your Oracle Database distribution.</p>
</li>
</ul>
<p>See the WebSphere documentation for instructions on how to use WebSphere to facilitate the creation of shared libraries.</p>
</li>
<li>
<p>Associate the shared library with the application.</p>
<p>See the WebSphere documentation for instructions on how to use WebSphere to associate the shared library with an application.</p>
</li>
</ol>
<a id="CEGGCCFC" name="CEGGCCFC"></a><a id="TLADG1111" name="TLADG1111"></a>
<p><b><font face="arial, helvetica, sans-serif" color="#330099">Option 2: Add EclipseLink as a Server Library Extension</font></b></p>
<p>To add EclipseLink as a server library extension, copy <code>eclipselink.jar</code> and the other JAR file(s) listed in Option 1, above, to the <em><code>WAS_HOME</code></em><code>\lib\ext</code> directory.</p>
</div>
<!-- class="sect3" -->
<a id="CEGFFJEA" name="CEGFFJEA"></a><a id="TLADG1112" name="TLADG1112"></a>
<div class="sect3">
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Package EclipseLink in the Application EAR</font></h3>
<p>You can also implement container-managed persistence by adding <code>eclipselink.jar</code> in the application EAR, without making any modifications to the server configuration. In this case, the persistence unit is managed by <code>@PersistenceContext</code> entity manager proxy injection on a stateless session bean. The following instructions show a example of this approach.</p>
<ol>
<li>
<p>Add <code>eclipselink.jar</code> to the application EAR in the following location:</p>
<p><em><code>EAR_archive</code></em><code>/APP-INF/lib/</code></p>
</li>
<li>
<p>Add the path to the <code>eclipselink.jar</code> to the <em><code>ejbModule</code></em><code>/META-INF/MANIFEST.MF</code> file(s) in your EJB JAR(s), as shown below:</p>
<pre xml:space="preserve" class="oac_no_warn">
Manifest-Version: 1.0
Class-Path: APP-INF/lib/eclipselink.jar
</pre>
<p>This is the manifest at the root of the entities' location, in this case as part of the <code>ejb.jar.</code></p>
</li>
<li>
<p>Configure the class loader to load the classes with the application class loader first.</p>
</li>
<li>
<p>Deploy and start the application. See the IBM WebSphere documentation for instructions.</p>
</li>
</ol>
</div>
<!-- class="sect3" -->
<a id="CEGJBCHB" name="CEGJBCHB"></a><a id="TLADG1113" name="TLADG1113"></a>
<div class="sect3"><!-- infolevel="all" infotype="General" -->
<h3 class="sect3"><font face="arial, helvetica, sans-serif" color="#330099">Package EclipseLink in the WAR</font></h3>
<p>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.</p>
<ol>
<li>
<p>Add <code>eclipselink.jar</code> and <code>javax.persistence_</code><em><code>ver_no</code></em><code>.jar</code> to the web application archive (WAR) file in the following location:</p>
<p><em><code>WAR_archive</code></em><code>/WEB-INF/lib/</code></p>
</li>
<li>
<p>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.</p>
</li>
<li>
<p>Deploy and start the application. See the IBM WebSphere documentation for instructions.</p>
</li>
</ol>
</div>
<!-- class="sect3" --></div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="navigation simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100" align="center">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="websphere001.htm"><img src="../../dcommon/images/larrow.png" alt="Previous" border="0" height="16" width="16" /></a></td>
<td align="center"><a href="websphere003.htm"><img src="../../dcommon/images/rarrow.png" alt="Next" border="0" height="16" width="16" /></a></td>
</tr>
</table>
</td>
<td align="center" width="34%"><a href="http://www.eclipse.org/eclipselink/" title="EclipseLink home"><img src="../../dcommon/images/ellogo.png" alt="EclipseLink" width="150" border="0" /></a><br />
<font size="-2">Copyright&nbsp;&copy;&nbsp;2014,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</font> <a href="../../dcommon/html/cpyr.htm"><br />
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="../../dcommon/images/contents.png" alt="Go To Table Of Contents" border="0" height="16" width="16" /><br />
</td><td>&nbsp;</td><td align="center"><a href="../../" target="_top" class="external text" title="Search" rel="nofollow"><img src="../../dcommon/images/search.png" alt="Search" style="border:0;" /><br /><span class="mini"></span></a></td><td>&nbsp;</td><td align="center"><a href="../eclipselink_otlcg.pdf" title="PDF" target="_blank"><img src="../../dcommon/images/pdf_icon.png" style="padding-right:5px;border:0" alt="PDF"></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
<div id="copyright">Copyright &copy; 2014 by The Eclipse Foundation under the <a href="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License (EPL)</a><br /> <script type="text/javascript">var LastUpdated = document.lastModified;document.writeln ("Updated: " + LastUpdated);</script> </div><!-- START: Analytics --><script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-1608008-2']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script><!-- END: Analytics --><!-- START: Sharethis --><script>var options={ "publisher": "e2fe9e07-fab6-4f84-83ea-0991b429842c", "position": "right", "ad": { "visible": false, "openDelay": 5, "closeDelay": 0}};var st_hover_widget = new sharethis.widgets.hoverbuttons(options);</script><!-- END: Sharethis --></body>
</html>