View source for Integrating EclipseLink with an Application Server (ELUG)

[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''

----

<div style="float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Integrating EclipseLink with an Application Server (ELUG)|Related Topics]]</div>
This section describes how to configure EclipseLink for use with Java EE containers and application servers.

For more information, see the following:
* [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)|Creating EclipseLink Files for Deployment]]
* [[Packaging%20a%20EclipseLink%20Application%20(ELUG)|Packaging a EclipseLink Application]]
* [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying a EclipseLink Application]]



==Introduction to the Application Server Support==
EclipseLink can be used with ''any'' Java EE application server that meets the [[#What Are the Software Requirements|software requirements]] through the EclipseLink API. 

There is EclipseLink-specific integration support for the following servers:
* [[#Integrating EclipseLink with Oracle WebLogic Server|Oracle WebLogic Server]]
* [[#Integrating EclipseLink with Oracle Containers for J2EE (OC4J)|Oracle Containers for J2EE (OC4J)]]
* [[#Integrating EclipseLink with IBM WebSphere Application Server|IBM WebSphere Application Server]]
* [[#Integrating EclipseLink with Sun Application Server|Sun Application Server]]
* [[#Integrating EclipseLink with JBoss Application Server|JBoss Application Server]]
* [[#Integrating EclipseLink with SAP NetWeaver Application Server|SAP NetWeaver Application Server]]




==Integrating EclipseLink with an Application Server==
This section describes concepts unique to EclipseLink application server integration, including the following:
* [[#What Are the Software Requirements|What Are the Software Requirements]]
* [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]
* [[#How to Set Security Permissions|How to Set Security Permissions]]
* [[#How to Integrate Clustering|How to Integrate Clustering]]



===What Are the Software Requirements===
To run a EclipseLink application within a Java EE container, your system must meet the following software requirements:
* An application server or Java EE container
* XML parser (see [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]);
* A JDBC driver configured to connect with your local database system (for more information, see your database administrator);
* A Java development environment, such as the following:
** Eclipse IDE;
** Oracle JDeveloper;
** IBM WebSphere Studio Application Developer (WSAD);
** Sun Java Development Kit (JDK) 1.5 or later;
* Any other Java environment that is compatible with the Sun JDK 1.5 or later;
* A command-line JVM executable (such as <tt>java.exe</tt> or <tt>jre.exe</tt>).



===How to Configure the XML Parser Platform===
The EclipseLink run-time environment uses an XML parser to do the following:
* Read and write XML configuration files (see [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#project.xml File)|project.xml File]] and [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)#sessions.xml File|sessions.xml File]]);
* Read and write Workbench project files (see [[Using%20Workbench%20(ELUG)#Introduction to Workbench|Introduction to Workbench]]);
* Perform object-to-XML transformations in EIS projects using XML records (see [[Introduction%20to%20EIS%20Mappings%20(ELUG)|Introduction to EIS Mappings]]);
* Perform object-to-XML transformations in XML projects (see [[Introduction%20to%20XML%20Mappings%20(ELUG)|Introduction to XML Mappings]]);

Application servers use an XML parser to read deployment files, such as <tt>ejb-jar.xml</tt> and <tt><</tt>''<tt>Java EE container</tt>''><tt>-ejb-jar.xml</tt> files (see [[Creating%20EclipseLink%20Files%20for%20Deployment%20(ELUG)|Creating EclipseLink Files for Deployment]]).

To avoid XML parser conflicts, you must configure your EclipseLink application to use the same XML parser as that used by the application server on which you deploy your application.

Internally, EclipseLink accesses its XML parser using an instance of <tt>org.eclipse.persistence.platform.xml.XMLPlatform</tt> class.

You can configure EclipseLink to use any XML parser for which an <tt>XMLPlatform</tt> class exists (see [[#Configuring XML Parser Platform|Configuring XML Parser Platform]]).

You can also create your own <tt>XMLPlatform</tt> to provide access to an XML parser not currently supported by EclipseLink (see [[#Creating an XML Parser Platform|Creating an XML Parser Platform]]).



====Configuring XML Parser Platform====
EclipseLink provides the <tt>XMLPlatform</tt> instances shown in the following table.

<span id="table_7_1"></span>
'''''Supported XML Platforms'''''
{| class="HRuleFormalWideMax" dir="ltr" title="Supported XML Platforms" summary="This table lists XMLPlatform instances provided by EclipseLInk" width="100%" border="1" frame="hsides" rules="rows" cellpadding="3" frame="hsides" rules="rows"
|- align="left" valign="top"
! id="r1c1-t2" align="left" valign="bottom" | '''XMLPlatform...'''
! id="r1c2-t2" align="left" valign="bottom" | '''Provides Access to...'''
! id="r1c3-t2" align="left" valign="bottom" | '''Use with...'''
|- align="left" valign="top"
| id="r2c1-t2" headers="r1c1-t2" align="left" |
<tt>org.eclipse.persistence.platform.xml.xdk.XDKPlatform</tt>
| headers="r2c1-t2 r1c2-t2" align="left" |
<tt>XDKParser</tt><nowiki>: this class provides access to the Oracle XML Developer's Kit (XDK) XML parser (see </nowiki><tt>http://www.oracle.com/technology/tech/xml/xdkhome.html</tt>).
| headers="r2c1-t2 r1c3-t2" align="left" |
[[#Integrating EclipseLink with Oracle Containers for J2EE (OC4J)|Integrating EclipseLink with Oracle Containers for J2EE (OC4J)]]
|- align="left" valign="top"
| id="r3c1-t2" headers="r1c1-t2" align="left" |
<tt>org.eclipse.persistence.platform.xml.jaxp.JAXPPlatform</tt><sup>1 </sup>
| headers="r3c1-t2 r1c2-t2" align="left" |
<tt>JAXPParser</tt><nowiki>: this class provides access to the Java SDK XML parser in the </nowiki><tt>javax.xml.parsers</tt> package (see <tt>http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JAXPIntro2.html</tt>).
| headers="r3c1-t2 r1c3-t2" align="left" |
See the following:
* [[#Integrating EclipseLink with Oracle WebLogic Server|Integrating EclipseLink with Oracle WebLogic Server]]
* [[#Integrating EclipseLink with IBM WebSphere Application Server|Integrating EclipseLink with IBM WebSphere Application Server]]
|}

<br /><sup>1 </sup>Default.<br /><br />

{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note'''<nowiki>:</nowiki> To use an XML parser not listed in this table, create your own <tt>XMLPlatform</tt> (see [[#Creating an XML Parser Platform|Creating an XML Parser Platform]]).
|}

<br />

To configure your EclipseLink application to use a particular instance of the <tt>XMLPlatform</tt> class, set system property <tt>eclipse.persistence.xml.platform</tt> to the fully qualified name of your <tt>XMLPlatform</tt> class, as the following example shows.

<span id="Example 7-1"></span>
''''' Configuring XML Platform'''''
 eclipse.persistence.xml.platform=org.eclipse.persistence.platform.xml.jaxp.JAXPPlatform



====Creating an XML Parser Platform====
Using the <tt>org.eclipse.persistence.internal.xml</tt> classes you can create your own instance of the <tt>org.eclipse.persistence.platform.xml.XMLPlatform</tt> class to specify an XML parser not listed in the [[#table_7_1|Supported XML Platforms]] table.

After creating your <tt>XMLPlatform</tt>, configure EclipseLink to use it (see [[#Configuring XML Parser Platform|Configuring XML Parser Platform]]).



====XML Parser Limitations====
Crimson (<tt>http://xml.apache.org/crimson/</tt>) is the XML parser supplied in the Java Platform, Standard Edition (Java SE) and in some JAXP reference implementations.

If you use Crimson with the JAXP API to parse XML files whose system identifier is not a fully qualified URL, then XML parsing will fail with a ''not valid URL'' exception.

Other XML parsers defer validation of the system identifier URL until it is specifically referenced.

If you are experiencing this problem, consider one of the following alternatives:
* Ensure that your XML files use a fully qualified system identifier URL.
* Use another XML parser (such as the OracleAS XML Parser for Java v2).


===How to Set Security Permissions===
By default, when you run a EclipseLink-enabled application in a JVM configured with a nondefault <tt>java.lang.SecurityManager</tt>, the EclipseLink run-time environment executes certain internal functions by executing a <tt>PrivilegedAction</tt> with <tt>java.security.AccessController</tt> method <tt>doPrivileged</tt>. This ensures that you do not need to grant many permissions to EclipseLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional EclipseLink features you use.

For more information, see [[#Defining Security Permissions|Defining Security Permissions]].

If you run a EclipseLink-enabled application in a JVM without a nondefault <tt>SecurityManager</tt>, you do not need to set any permissions.


===How to Integrate Clustering===
Most application servers include a clustering service that you can use with your EclipseLink application.

To use EclipseLink with an application server cluster, use this general procedure:
# Install the <tt>eclipselink.jar</tt> file (and include it in the classpath) on each application server in the cluster to which you deploy EclipseLink applications.
# Configure EclipseLink cache consistency options appropriate for your application.<br>For more information, see [[Introduction%20to%20Cache%20(ELUG)|Introduction to Cache]].
# Configure clustering on each application server.<br>For more information, see your application server documentation.




==Integrating EclipseLink with Oracle WebLogic Server==
To integrate an EclipseLink application with Oracle WebLogic Server, you must consider the following:
* [[#How to Configure the WebLogic Classpath|How to Configure the WebLogic Classpath]]
* [[#How to Integrate with the WebLogic JTA|How to Integrate with the WebLogic JTA]]
<!--* [[#How to Integrate JMX|How to Integrate JMX]]-->
* [[#How to Integrate the Security Manager|How to Integrate the Security Manager]]

In addition to configuring these Oracle WebLogic Server-specific options, you must also consider the general application server integration issues in [[#Integrating EclipseLink with an Application Server|Integrating EclipseLink with an Application Server]].


===How to Configure the WebLogic Classpath===
EclipseLink works out of the box in Oracle WebLogic Server 10.3. The EclipseLink library resides in the following location on the server:
 $BEA_HOME/modules/org.eclipse.persistence_*.jar

Ensure that your EclipseLink application defines an XML parser platform (see [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]).

===How to Integrate with the WebLogic JTA===
For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]).

For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]].

===How to Integrate JMX===
By default, when you deploy an EclipseLink application to Oracle WebLogic Server, the EclipseLink runtime deploys the following Java Management Extensions (JMX) MBeans to the Oracle WebLogic Server JMX service for each EclipseLink session:
* <tt>org.eclipse.persistence.services.DevelopmentServices</tt> - This class is meant to provide facilities for managing an EclipseLink session internal to EclipseLink over JMX.
* <tt>org.eclipse.persistence.services.RuntimeServices</tt> - This class is meant to provide facilities for managing an EclipseLink session external to EclipseLink over JMX.

Use the API that this JMX MBean exposes to access and configure your EclipseLink sessions at run time using JMX code that you write, or to integrate your EclipseLink application with a third-party JMX management application, such as JConsole.

====Setting Up the Environment for EclipseLink JMX MBeans====
Perform the following steps:
# '''Set breakpoints:''' the <tt>eclipselink.jar</tt> deployed in the <tt>$WEBLOGIC_HOME/modules/org.eclipse.persistence_n.n.n.jar</tt> needs a source attachment. You set a breakpoint on the <tt>undeploy</tt> method of the <tt>org.eclipse.persistence.internal.jpa.EntityManagerSetupImpl</tt> pointing to the source JAR file or your workspace projects, and then redeploy. This will result in any breakpoints set in the <tt>predeploy</tt> method or prior to the first login to be hit. 
# '''Enable remote access on the Oracle WebLogic Server JVM''' by adding the following JVM option to your WebLogic startup script:<br><tt>C:\opt\wls103\user_projects\domains\base_domain\bin\startWebLogic.cmd</tt><br><tt>set JAVA_OPTIONS=%JAVA_OPTIONS% -Dcom.sun.management.jmxremote</tt>
# '''Enable MBean registration (deployment)''' by adding one or both of the two MBean system properties, as follows:<br><tt>rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=true</tt><br><tt>rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=true</tt><br>By default, EclipseLink does not register MBeans for Oracle WebLogic Server. If you enable the registration, it will occur as a post step during the first login to the session (see [[Configuring%20a%20Session%20(ELUG)#Configuring a Session Login|Configuring a Session Login]]).<br>If both <tt>eclipselink.register.dev.mbean</tt> and <tt>eclipselink.register.run.mbean</tt> properties are missing, MBean registration will not proceed for that bean. 
# '''Configure Oracle WebLogic Server domain security'''.<br>For more information, see ''[http://wiki.eclipse.org/EclipseLink/Examples/JPA/WebLogic_Web_Tutorial EclipseLink JMX MBean Support in Oracle WebLogic Server tutorial]''.
<!--
====Confirming that EclipseLink JMX MBeans are Deployed====
Before you access EclipseLink JMX MBeans, you can use various methods to determine whether or not they were successfully deployed in Oracle WebLogic Server.

'''To confirm that EclipseLink JMX MBeans are deployed:'''
# Package and deploy your EclipseLink application to Oracle WebLogic Server.<br>For more information, see [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying an EclipseLink Application]].
# Examine Oracle WebLogic Server logs and look for the appropriate log messages. Note that for a JPA application, EclipseLink session instantiation and login occurs at <tt>EntityManager</tt> instantiation time.
# Use the System MBean Browser in the Oracle Enterprise Manager Fusion Middleware Control to access the EclipseLink JMX MBeans.<br>For more information, see [[#Accessing EclipseLink JMX MBeans Using Oracle Enterprise Manager Fusion Middleware Control|Accessing EclipseLink JMX MBeans Using Oracle Enterprise Manager Fusion Middleware Control]].

====Accessing EclipseLink JMX MBeans Using Oracle Enterprise Manager Fusion Middleware Control====
After you deploy your EclipseLink application, you can use the System MBean Browser in the Oracle Enterprise Manager Fusion Middleware Control to access and use a subset of the public API that EclipseLink MBeans provide.

'''To access EclipseLink JMX MBeans using Oracle Enterprise Manager Fusion Middleware Control:'''
* 1. Package and deploy your EclipseLink application to Oracle WebLogic Server.<br>For more information, see [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying an EclipseLink Application]].
* 2. Determine the HTTP port for the <tt>wls_admin</tt> component using the following <tt>asctl</tt> command on the computer on which the <tt>wls_admin</tt> component is running:
 $ asctl getports ORACLE_INSTANCE_NAME/wls_admin/http-web-site
     
     --------------------------------------------------------
    | Name      | Dps Id    | Port      | Ip Address| Port Status |
    |           |           |           |           |             |
    | http-web-site| /farm1_FarmRoot/farm1/asinst_1/wls_admin/http-web-site|6799|10.3| READY|
     --------------------------------------------------------
Where <tt>ORACLE_INSTANCE_NAME</tt> is the name of the Oracle instance that hosts <tt>wls_admin</tt>. In this example, the <tt>ORACLE_INSTANCE_NAME</tt> is <tt>asinst_1</tt>, and the HTTP port for the <tt>wls_admin</tt> component is 6799.<br>For more information, see ''Oracle Fusion Middleware Administration and Application Deployment Guide for Oracle WebLogic Server''.
* 3. Log in to the Fusion Middleware Control Console by launching a Web browser and entering a URL like:
 http://HOST_NAME:PORT/em/faces/targetauth/emasLogin
Where <tt>HOST_NAME</tt> is the host name or IP address of the computer on which the <tt>wls_admin</tt> component is running, and <tt>PORT</tt> is the HTTP port for the <tt>wls_admin</tt> component from step 2.
* 4. In the navigator, click on the '''Farm''' tab pull-down menu and select '''Administration''', and then select '''System MBean Browser'''.
* 5. On the System MBean Browser page, expand the '''Search''' menu and select '''MBean Name'''.
* 6. Enter your EclipseLink session or application name in the search field, and then click '''Search'''.<br>The Fusion Middleware Control Console finds all the MBeans associated with your EclipseLink session or application.<br>The following figure shows the MBeans for an EclipseLink application. <<figure goes below>>
* 7. Select a MBean and use the '''Attributes''', '''Operations''', and '''Notifications''' tabs to access attributes, invoke operations, and examine MBean notifications.<br>Fusion Middleware Control Console gives you access to a subset of the public API of the <tt>RuntimeServices</tt> MBeans.
-->

====Accessing EclipseLink JMX MBeans Using a Third-Party JMX Management Application====
After you deploy your EclipseLink application, you can use any JMX-compliant management application to access and use the full public API that EclipseLink MBeans provide.

'''To access EclipseLink JMX MBeans using a third-party JMX management application:'''
# Package and deploy your EclipseLink application to Oracle WebLogic Server.<br>For more information, see [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying an EclipseLink Application]].
# Optionally, examine Oracle WebLogic Server logs and look for the appropriate log messages. Note that for a JPA application, EclipseLink session instantiation and login occurs at <tt>EntityManager</tt> instantiation time. 
# Launch your third-party JMX management application.<br>For example, launch JConsole (<tt>JDK_HOME\bin\jconsole.exe</tt>) using the command prompt, and then select the running <tt>weblogic.Server</tt> local process, as the following figure shows.<br><br>[[Image:Jconsole_attach_to_weblogic_server_jvm.jpg]]<br><br> 

<!-- # Establish a connection to the Oracle WebLogic Server JMX service using the following JMX URL:<br><tt>service:jmx:rmi:///opmn://OPMN_HOST:OPMN_PORT/WLS_NAME</tt><br>The following figure shows how to create a JConsole connection to the Oracle WebLogic Server JMX service. -->
<!--
# Use your third-party JMX management application to examine EclipseLink MBean attributes, operations, and notifications.<br>Using JConsole or JMX code you write, you can access the full public API of the <tt>RuntimeServices</tt> MBeans.<br>The following figure shows the JConsole display for an EclipseLink application.<br><br>[[Image:Eclipselink_jmx_mbeans_in_jconsole.jpg]]<br><br>
Notice the EclipseLink MBeans off the root of the JNDI tree. The preceding example contains two separate EAR files deployed to Oracle WebLogic Server, each with its own set of MBeans based on the login session.
-->
# Optionally, launch JRockit Mission Control '''JMC.exe''', attach to the JVM process and navigate to the MBeans tab - you will see the following screen showing the EclipsLink MBeans for your session.
[[Image:Jrockit_jconsole_mbeans_via_non_jndi_generic_spec_lookup.JPG]]

====Disabling EclipseLink JMX Support==== 
There are a number of ways to disable EclipseLink JMX support.

'''To disable deployment of MBeans to Oracle WebLogic Server for your EclipseLink application using system properties''', remove, disable, or do not add in the first place <tt>eclipselink.register.dev.mbean</tt> and <tt>eclipselink.register.run.mbean</tt> MBean system properties. The following example shows how to disable these properties:<br><tt>rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=false</tt><br><tt>rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=false</tt>.


'''To disable deployment of MBeans to Oracle WebLogic Server for your EclipseLink application using deployment XML''', use an EclipseLink <tt>sessions.xml</tt> file (assuming your application has one):
# Undeploy your EclipseLink application on Oracle WebLogic Server.
# Edit your EclipseLink application’s Oracle WebLogic Server platform to disable run-time services.<br>For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]].
# Package your EclipseLink application and redeploy on Oracle WebLogic Server.<br>For more information, see [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying an EclipseLink Application]].
# Confirm that EclipseLink JMX MBean instances for your application no longer exist.

If your application does not include an EclipseLink <tt>sessions.xml</tt> file, you can use a <tt>preLogin</tt> event handler to disable this feature (see the following section).


'''To disable deployment of MBeans to Oracle WebLogic Server for your EclipseLink application using the EclipseLink session preLogin event handler''':
<ol>
<li> Undeploy your EclipseLink application on Oracle WebLogic Server.
<li> Create an EclipseLink session customizer.<br>For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring a Session Customizer Class|Configuring a Session Customizer Class]].
<li> In your session customizer, create a session event listener for the <tt>preLogin</tt> session event and register the listener with the session event manager, as the following example shows.
<div class="pre">
 <tt>import oracle.eclipselink.tools.sessionconfiguration.SessionCustomizer;</tt>
 <tt>import oracle.eclipselink.sessions.Session;</tt>
 <tt>import oracle.eclipselink.sessions.SessionEvent;</tt>
 <tt>import oracle.eclipselink.sessions.SessionEventAdapter;</tt>
 <tt>import oracle.eclipselink.platform.server.ServerPlatform;</tt>
 <tt>public class EmployeeSessionCustomizer implements SessionCustomizer {</tt>
   
   <tt>public void customize(Sesssion session) {</tt>
       <tt>SessionEventAdapter myEventListener = new SessionEventAdapter() {</tt>
           <tt>'''// Listen for preLogin event'''</tt>
           <tt>public void preLogin(SessionEvent event) {</tt>
               <tt>'''// Disable runtime services'''</tt>
               <tt>Session session event.getSession();</tt>
               <tt>ServerPlatform serverPlatform = session.getServerPlatform();</tt>
               <tt>serverPlatform.disableRuntimeServices();</tt>
           <tt>}</tt>
       <tt>};</tt>
       <tt>'''// Register session event listener'''</tt>
       <tt>session.getEventManager().addListener(myEventListener);</tt>
   <tt>}</tt>
 <tt>}</tt>
</div>
For more information, see [[Configuring%20a%20Session%20(ELUG)#Configuring Session Event Listeners|Configuring Session Event Listeners]].
<li> Package your EclipseLink application, including your session customizer, and redeploy on Oracle WebLogic Server.<br>For more information, see [[Packaging%20a%20EclipseLink%20Application%20(ELUG)|Packaging an EclipseLink Application]] and [[Deploying%20a%20EclipseLink%20Application%20(ELUG)|Deploying an EclipseLink Application]].
<li> Confirm that EclipseLink JMX MBean instances for your application are not deployed.
</ol>


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': Follow the preceding procedure if you EclipseLink application does not include an Oracle WebLogic Server <tt>sessions.xml</tt> file (such as a EclipseLink JPA application).
|}

<!--
====Handling Exceptions====
EclipseLink logs warning messages and the stack trace for exceptions involving naming, security and session collision 
-->
====What You May Need to Know About EclipseLink JMX Support====
For more information on EclipseLink and Oracle WebLogic Server JMX support, see the following:
* <i>Oracle WebLogic Server: Developing Manageable Applications with JMX</i>
* O<i>racle WebLogic Server: Developing Custom Management Utilities with JMX</i>
<!--* EclipseLink JMX MBean Tutorial for WebLogic at http://wiki.eclipse.org/EclipseLink/Examples/JMX/MBeans_WebLogic-->

For more information on JMX in general, see http://java.sun.com/docs/books/tutorial/jmx/index.html

===How to Integrate the Security Manager===
If you use a security manager, specify a security policy file in the <tt>weblogic.policy</tt> file (normally located in the WebLogic install directory), as follows:
 -Djava.security.manager
 -Djava.security.policy==c:\weblogic\weblogic.policy

The WebLogic installation procedure includes a sample security policy file. You need to edit the <tt>weblogic.policy</tt> file to grant permission for EclipseLink to use reflection.

The following example illustrates only the permissions that EclipseLink requires, but most <tt>weblogic.policy</tt> files contain more permissions than are shown in this example.


<span id="Example 7-5"></span>
''''' A Subset of a "Grant" Section from a WebLogic.policy File'''''
<source lang="java">
 grant {
 '''// "enableSubstitution" required to run the WebLogic console'''
 permission java.io.SerializablePermission "enableSubstitution";
 '''// "modifyThreadGroup" required to run the WebLogic Server'''
 permission java.lang.RuntimePermission "modifyThreadGroup";
 '''// grant permission for EclipseLink to use reflection'''
 
     permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
 };
</source>


==Integrating EclipseLink with Oracle Containers for J2EE (OC4J)==
To integrate a EclipseLink application with OC4J, you must consider [[#How to Integrate with the OC4J JTA|integration with the OC4J JTA]].

In addition to configuring these OC4J-specific options, you must also consider the general application server integration issues described in [[#Integrating EclipseLink with an Application Server|Integrating EclipseLink with an Application Server]].


===How to Integrate with the OC4J JTA===
For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]).

For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]].

===How to Configure the OC4J Application Server Classpath===
To configure EclipseLink support for OC4J, add the <tt>eclipselink.jar</tt> file to the application server classpath in the global <tt>applib</tt> directory. Place the <tt>eclipselink.jar</tt> as noted by the element <tt><shared-library name="global.libraries"></tt> element in the <tt>$OC4J_HOME/config/server.xml</tt> file in the <tt>$OC4J_HOME/applib</tt> directory, as follows: 

 /oc4j/j2ee/home/applib/eclipselink.jar

==Integrating EclipseLink with IBM WebSphere Application Server==
To integrate a EclipseLink application with IBM WebSphere Application Server, you must consider the following:
* [[#How to Configure the WebSphere Classpath|How to Configure the WebSphere Classpath]]
* [[#How to Configure Class Loader Order|How to Configure Class Loader Order]]
* [[#How to Integrate with the WebSphere JTA|How to Integrate with the WebSphere JTA]]

In addition to configuring these IBM WebSphere application server-specific options, you must also consider the general application server integration issues in [[#Integrating EclipseLink with an Application Server|Integrating EclipseLink with an Application Server]].



===How to Configure the WebSphere Classpath===

You configure the IBM WebSphere application server classpath differently depending on what version of this server you are using:


====Configuring Classpath for IBM WebSphere Application Server 6.1 and Later====
EclipseLink provides JTA and general integration support for IBM WebSphere application server 6.1 and later. To configure the classpath for this version, do the following:
# Create a shared library that contains the <tt> ''<ECLIPSELINK_HOME>''\jlib\eclipselink.jar''</tt> file and associate the shared library with the application.
# Ensure that your EclipseLink application defines an XML parser platform (see [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]).

===How to Configure Class Loader Order===
If you are deploying a EclipseLink enabled application that uses EclipseLink <tt>sessions.xml</tt> or XML project deployment, you must use the WebSphere Application Server Administrative Console to set '''Class loader order''' to '''Class loaded with application class loader first'''.



===How to Integrate with the WebSphere JTA===
For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]).

For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]].



===How to Configure Clustering on IBM WebSphere Application Server===
For information on integrating a EclipseLink application with an application server cluster, see [[#How to Integrate Clustering|How to Integrate Clustering]].




==Integrating EclipseLink with Sun Application Server==
To integrate a EclipseLink application with Sun Application Server (SunAS), you must consider the following:
* [[#How to Configure the Sun Application Server Classpath|How to Configure the Sun Application Server Classpath]]
* [[#How to Integrate with the Sun Application Server JTA|How to Integrate with the Sun Application Server JTA]]

In addition to configuring these SunAS-specific options, you must also consider the general application server integration issues in [[#Integrating EclipseLink with an Application Server|Integrating EclipseLink with an Application Server]].



===How to Configure the Sun Application Server Classpath===
To configure EclipseLink support for SunAS, do the following:
# Add the <tt>''<ECLIPSELINK_HOME>''\jlib\eclipselink.jar</tt> file to the application server classpath. 
# Ensure that your EclipseLink application defines an XML parser platform (see [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]).

===How to Integrate with the Sun Application Server JTA===
For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session (see [[Configuring%20a%20Session%20(ELUG)|Configuring the Server Platform]]).

For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]].




==Integrating EclipseLink with JBoss Application Server==

These instructions apply to JBoss AS versions prior to AS7. AS7 changes the setup quite dramatically; the best available documentation is currently here: https://community.jboss.org/wiki/HowToUseEclipseLinkWithAS7</b>

To integrate a EclipseLink application with JBoss Application Server, you must consider the following:
* [[#How to Configure the JBoss Classpath|How to Configure the JBoss Classpath]]
* [[#How to Integrate with the JBoss JTA|How to Integrate with the JBoss JTA]]

In addition to configuring these JBoss-specific options, you must also consider the general application server integration issues in [[#Integrating EclipseLink with an Application Server|Integrating EclipseLink with an Application Server]].



===How to Configure the JBoss Classpath===
To configure EclipseLink support for JBoss, do the following:
# Add the <tt>''<ECLIPSELINK_HOME>''\jlib\eclipselink.jar</tt> file to the application server classpath. 
# Ensure that your EclipseLink application defines an XML parser platform (see [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]).

===How to Integrate with the JBoss JTA===
For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session (see [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]]).

For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]].



===How to Configure JPA Application Deployment to JBoss 4.2 Application Server===
For JPA applications, to enable the container to manage entities, statically weave the entities and reference JBoss as the target server in the <tt>persistence.xml</tt> file.

Perform the following deployment changes:
<ol>
<li> If weaving is required, statically weave the entities before EAR packaging. Use  either the command-line weaver or the weaving Ant task (see [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#How to Configure Static Weaving for JPA Entities|How to Configure Static Weaving for JPA Entities]]).</li>
<li> Ensure that the <tt>eclipselink.target-server</tt> property (see [[Using%20EclipseLink%20JPA%20Extensions%20(ELUG)#Using EclipseLink JPA Extensions for Session, Target Database and Target Application Server|Using EclipseLink JPA Extensions for Session, Target Database and Target Application Server]]) is set in the <tt>persistence.xml</tt> file of all persistence units deployed to the JBoss container:
<div class="pre">
 <tt><property name="eclipselink.target-server" value="JBoss"/></tt>
</div>
Otherwise, even though the container-managed entities are predeployed, they will not be managed at run time.</li>
</ol>
For more information and examples, see the following: 
* http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/JBoss
* [[Packaging%20and%20Deploying%20EclipseLink%20JPA%20Applications%20(ELUG)#How to Deploy an Application to Generic Java EE 5 Application Servers|How to Deploy an Application to Generic Java EE 5 Application Servers]]

==Integrating EclipseLink with SAP NetWeaver Application Server==
To integrate a EclipseLink application with SAP NetWeaver Application Server, you must consider the following:
* [[#How to Configure the NetWeaver Classpath|How to Configure the NetWeaver Classpath]]
* [[#How to Integrate with the NetWeaver JTA|How to Integrate with the NetWeaver JTA]]

In addition to configuring these NetWeaver-specific options, you must also consider the general application server integration issues in [[#Integrating EclipseLink with an Application Server|Integrating EclipseLink with an Application Server]].



===How to Configure the NetWeaver Classpath===
To configure EclipseLink support for NetWeaver, do the following:
# Create and deploy a standard library (i.e. an SDA file) that contains the  <tt> ''<ECLIPSELINK_HOME>''\jlib\eclipselink.jar</tt> file and associate the library with the application.
# Ensure that your EclipseLink application defines an XML parser platform (see [[#How to Configure the XML Parser Platform|How to Configure the XML Parser Platform]]).

===How to Integrate with the NetWeaver JTA===
For applications that require JTA integration, specify the external transaction controller when you configure the server platform in your session. See [[Configuring%20a%20Session%20(ELUG)#Configuring the Server Platform|Configuring the Server Platform]] for general information on configuring the server platform and [[EclipseLink/Development/ServerPlatform/NetweaverPlatform]] for a description of the NetWeaver server platform.

For more information, see [[Using%20Advanced%20Unit%20of%20Work%20API%20(ELUG)#Integrating the Unit of Work with an External Transaction Service|Integrating the Unit of Work with an External Transaction Service]].

==Defining Security Permissions==
By default, when you run a EclipseLink-enabled application in a JVM configured with a nondefault <tt>java.lang.SecurityManager</tt>, the EclipseLink run time executes certain internal functions by executing a <tt>PrivilegedAction</tt> with <tt>java.security.AccessController</tt> method <tt>doPrivileged</tt>. This ensures that you do not need to grant many permissions to EclipseLink for it to perform its most common operations. You need only grant certain permissions depending on the types of optional EclipseLink features you use (see [[#How to Define Permissions Required by EclipseLink Features|How to Define Permissions Required by EclipseLink Features]]).

While using <tt>doPrivileged</tt> method provides enhanced security, it will severely impact overall performance. Alternatively, you can configure EclipseLink to disable the use of <tt>doPrivileged</tt> method even when a nondefault <tt>SecurityManager</tt> is present (see [[#How to Disable doPrivileged Operation|How to Disable doPrivileged Operation]]). In this case, you must grant EclipseLink all required permissions (see [[#How to Define Permissions Required by EclipseLink Features|How to Define Permissions Required by EclipseLink Features]] and [[#How to Define Permissions Required when doPrivileged Is Disabled|How to Define Permissions Required when doPrivileged Is Disabled]]).


{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
| align="left" |
'''Note''': While enabling the use of <tt>doPriviledged</tt> method enhances EclipseLink application security, it does not guarantee that secure code cannot be called by application code in ways that the system did not intend. You must consider the use of <tt>doPriviledged</tt> method within the context of your overall application security strategy. For more information, see <tt>http://java.sun.com/security/index.jsp</tt>.
|}


If you run a EclipseLink-enabled application in a JVM without a nondefault <tt>SecurityManager</tt>, you do not need to grant any permissions.



===How to Define Permissions Required by EclipseLink Features===
When you run a EclipseLink-enabled application in a JVM configured with a nondefault <tt>java.lang.SecurityManager</tt> and <tt>doPrivileged</tt> operation is enabled, you may need to grant additional permissions if your application requires any of the following:
* [[#Defining System Properties|Defining System Properties]]
* [[#Loading project.xml or sessions.xml Files|Loading project.xml or sessions.xml Files]]
* [[#Defining Cache Coordination|Defining Cache Coordination]]
* [[#Accessing a Data Source by Port|Accessing a Data Source by Port]]
* [[#Logging with java.util.logging|Logging with java.util.logging]]
* [[#Granting Permissions for Java EE Application Deployment|Granting Permissions for Java EE Application Deployment]]



====Defining System Properties====
By default, a EclipseLink-enabled application requires access to the system properties granted in the default <tt><</tt>''<tt>JAVA_HOME</tt>''<tt>>/lib/security/java.policy</tt> file. If your application requires access to other platform-specific, environment, or custom properties, then grant further <tt>PropertyPermission</tt> permissions, as the following example shows.

<span id="Example 7-6"></span>
'''''Permissions for System Properties'''''
 permission java.util.PropertyPermission "my.property", "read";



====Loading project.xml or sessions.xml Files====
Most EclipseLink-enabled applications read in <tt>project.xml</tt> and <tt>sessions.xml</tt> files directly. Grant permissions to the specific files or file locations, as the following example shows. This example assumes that both <tt>project.xml</tt> and <tt>sessions.xml</tt> files are located in the same directory (given by application-specific system property <tt>deployment.xml.home</tt>). Alternatively, you can specify a separate <tt>FilePermission</tt> for each file.


<span id="Example 7-7"></span>
''''' Permissions for Loading Deployment XML Files'''''
 permission java.io.FilePermission "${deployment.xml.home}/*.xml", "read";

For information on <tt>FilePermission</tt> settings for Java EE applications, see [[#Granting Permissions for Java EE Application Deployment|Granting Permissions for Java EE Application Deployment]].



====Defining Cache Coordination====
If your application uses cache coordination (see [[Introduction%20to%20Cache%20(ELUG)#Cache Coordination|Cache Coordination]]), then grant <tt>accept</tt>, <tt>connect</tt>, <tt>listen</tt>, and <tt>resolve</tt> permissions to the specific sockets used by your coordinated cache, as the following example shows. This example assumes that the coordinated cache multicast port (see [[Configuring%20a%20Coordinated%20Cache%20(ELUG)#Configuring a Multicast Port|Configuring a Multicast Port]]) is 1024.

<span id="Example 7-8"></span>
''''' Permissions for Cache Coordination'''''
 permission java.net.SocketPermission "localhost:1024-", "accept, connect, listen, resolve";



====Accessing a Data Source by Port====
If your EclipseLink-enabled application accesses a data source using a socket, then grant <tt>connect</tt> and <tt>resolve</tt> permissions for that socket, as the following example shows. This example assumes that the host name (or IP address) of the remote host that provides the data source (such as a relational database server host) is given by application-specific system property <tt>remote.data.source.host</tt> and that this host accepts data source connections on port 1025.

<span id="Example 7-9"></span>
''''' Permissions for non-Java EE Data Source Connections'''''
 permission java.net.SocketPermission "${remote.data.source.host}:1025-", "connect, resolve";

For Java EE applications, data source socket permissions are usually handled by the application server.



====Logging with java.util.logging====
If you configure your EclipseLink-enabled application to use <tt>java.util.logging</tt> package (see [[Configuring%20a%20Session%20(ELUG)#Configuring Logging|Configuring Logging]]), then grant your application <tt>control</tt> permissions, as this example shows.


<span id="Example 7-10"></span>
'''''Permissions for java.util.logging'''''
 permission java.util.logging.LoggingPermission "control"



====Granting Permissions for Java EE Application Deployment====
If you are deploying a EclipseLink-enabled Java EE application, you must grant permissions for the following:

* The <tt>eclipselink.jar</tt> file. For example: 
 grant codeBase "file:<ECLIPSELINK_HOME>/jlib/eclipselink.jar" {
     permission java.security.AllPermission;
 };

If you are using an XML platform, you must also grant the following permissions:
* The <tt>eclipse.persistence.xml.platform</tt> system property. For Example: 
 permission java.util.PropertyPermission "eclipse.persistence.xml.platform", "read"



===How to Define Permissions Required when doPrivileged Is Disabled===
If you disable <tt>doPrivileged</tt> operation when you run a EclipseLink-enabled application in a JVM configured with a nondefault <tt>java.lang.SecurityManager</tt>, you must grant the following permissions:
* <tt>java.lang.reflect.RelectPermission "suppressAccessChecks"</tt>
* <tt>java.lang.RuntimePermission "accessDeclaredMembers"</tt>
* <tt>java.lang.RuntimePermission "getClassLoader"</tt>

You may also have to grant additional permissions depending on the EclipseLink features your application uses. For more information, see [[#How_to_Define Permissions_Required_by_EclipseLink_Features|How to Define Permissions Required by EclipseLink Features]].



===How to Disable doPrivileged Operation===
To disable <tt>doPrivileged</tt> operation when you run a EclipseLink-enabled application in a JVM configured with a nondefault <tt>java.lang.SecurityManager</tt>, set system property <tt>oracle.j2ee.security.usedoprivileged</tt> to <tt>false</tt>. If you are using OC4J, set system property <tt>oracle.j2ee.security.usedoprivileged</tt> to <tt>false</tt>.

To enable <tt>doPrivileged</tt> operation, set these system properties to <tt>true</tt>.


----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Task]]
[[Category: Concept]]