Difference between revisions of "Integrating EclipseLink with an Application Server (ELUG)"

Latest revision as of 11:21, 18 July 2012

For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/

This section describes how to configure EclipseLink for use with Java EE containers and application servers.

For more information, see the following:

• Creating EclipseLink Files for Deployment
• Packaging a EclipseLink Application
• Deploying a EclipseLink Application

Introduction to the Application Server Support

EclipseLink can be used with any Java EE application server that meets the software requirements through the EclipseLink API.

There is EclipseLink-specific integration support for the following servers:

• Oracle WebLogic Server
• Oracle Containers for J2EE (OC4J)
• IBM WebSphere Application Server
• Sun Application Server
• JBoss 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
• How to Configure the XML Parser Platform
• How to Set Security Permissions
• 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);
• 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 java.exe or jre.exe).

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 project.xml File and sessions.xml File);
• Read and write Workbench project files (see Introduction to Workbench);
• Perform object-to-XML transformations in EIS projects using XML records (see Introduction to EIS Mappings);
• Perform object-to-XML transformations in XML projects (see Introduction to XML Mappings);

Application servers use an XML parser to read deployment files, such as ejb-jar.xml and <Java EE container>-ejb-jar.xml files (see 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 org.eclipse.persistence.platform.xml.XMLPlatform class.

You can configure EclipseLink to use any XML parser for which an XMLPlatform class exists (see Configuring XML Parser Platform).

You can also create your own XMLPlatform to provide access to an XML parser not currently supported by EclipseLink (see Creating an XML Parser Platform).

Configuring XML Parser Platform

EclipseLink provides the XMLPlatform instances shown in the following table.

Supported XML Platforms

¹ Default.

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

Configuring XML Platform

eclipse.persistence.xml.platform=org.eclipse.persistence.platform.xml.jaxp.JAXPPlatform

Creating an XML Parser Platform

Using the org.eclipse.persistence.internal.xml classes you can create your own instance of the org.eclipse.persistence.platform.xml.XMLPlatform class to specify an XML parser not listed in the Supported XML Platforms table.

After creating your XMLPlatform, configure EclipseLink to use it (see Configuring XML Parser Platform).

XML Parser Limitations

Crimson (http://xml.apache.org/crimson/) 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 java.lang.SecurityManager, the EclipseLink run-time environment executes certain internal functions by executing a PrivilegedAction with java.security.AccessController method doPrivileged. 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.

If you run a EclipseLink-enabled application in a JVM without a nondefault SecurityManager, 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:

1. Install the eclipselink.jar file (and include it in the classpath) on each application server in the cluster to which you deploy EclipseLink applications.
2. Configure EclipseLink cache consistency options appropriate for your application.
   For more information, see Introduction to Cache.
3. Configure clustering on each application server.
   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 Integrate with the WebLogic JTA
• 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.

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 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 the Server Platform).

For more information, see 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:

• org.eclipse.persistence.services.DevelopmentServices - This class is meant to provide facilities for managing an EclipseLink session internal to EclipseLink over JMX.
• org.eclipse.persistence.services.RuntimeServices - 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:

1. Set breakpoints: the eclipselink.jar deployed in the $WEBLOGIC_HOME/modules/org.eclipse.persistence_n.n.n.jar needs a source attachment. You set a breakpoint on the undeploy method of the org.eclipse.persistence.internal.jpa.EntityManagerSetupImpl pointing to the source JAR file or your workspace projects, and then redeploy. This will result in any breakpoints set in the predeploy method or prior to the first login to be hit.
2. Enable remote access on the Oracle WebLogic Server JVM by adding the following JVM option to your WebLogic startup script:
   C:\opt\wls103\user_projects\domains\base_domain\bin\startWebLogic.cmd
   set JAVA_OPTIONS=%JAVA_OPTIONS% -Dcom.sun.management.jmxremote
3. Enable MBean registration (deployment) by adding one or both of the two MBean system properties, as follows:
   rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=true
   rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=true
   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 a Session Login).
   If both eclipselink.register.dev.mbean and eclipselink.register.run.mbean properties are missing, MBean registration will not proceed for that bean.
4. Configure Oracle WebLogic Server domain security.
   For more information, see EclipseLink JMX MBean Support in Oracle WebLogic Server tutorial.

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:

1. Package and deploy your EclipseLink application to Oracle WebLogic Server.
   For more information, see Deploying an EclipseLink Application.
2. 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 EntityManager instantiation time.
3. Launch your third-party JMX management application.
   For example, launch JConsole (JDK_HOME\bin\jconsole.exe) using the command prompt, and then select the running weblogic.Server local process, as the following figure shows.
   
   
   
   

1. 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.

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 eclipselink.register.dev.mbean and eclipselink.register.run.mbean MBean system properties. The following example shows how to disable these properties:
rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=false
rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=false.

To disable deployment of MBeans to Oracle WebLogic Server for your EclipseLink application using deployment XML, use an EclipseLink sessions.xml file (assuming your application has one):

1. Undeploy your EclipseLink application on Oracle WebLogic Server.
2. Edit your EclipseLink application’s Oracle WebLogic Server platform to disable run-time services.
   For more information, see Configuring the Server Platform.
3. Package your EclipseLink application and redeploy on Oracle WebLogic Server.
   For more information, see Deploying an EclipseLink Application.
4. Confirm that EclipseLink JMX MBean instances for your application no longer exist.

If your application does not include an EclipseLink sessions.xml file, you can use a preLogin 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:

1. Undeploy your EclipseLink application on Oracle WebLogic Server.
2. Create an EclipseLink session customizer.
   For more information, see Configuring a Session Customizer Class.
3. In your session customizer, create a session event listener for the preLogin session event and register the listener with the session event manager, as the following example shows.

   import oracle.eclipselink.tools.sessionconfiguration.SessionCustomizer;
   import oracle.eclipselink.sessions.Session;
   import oracle.eclipselink.sessions.SessionEvent;
   import oracle.eclipselink.sessions.SessionEventAdapter;
   import oracle.eclipselink.platform.server.ServerPlatform;
   public class EmployeeSessionCustomizer implements SessionCustomizer {
     
     public void customize(Sesssion session) {
         SessionEventAdapter myEventListener = new SessionEventAdapter() {
             // Listen for preLogin event
             public void preLogin(SessionEvent event) {
                 // Disable runtime services
                 Session session event.getSession();
                 ServerPlatform serverPlatform = session.getServerPlatform();
                 serverPlatform.disableRuntimeServices();
             }
         };
         // Register session event listener
         session.getEventManager().addListener(myEventListener);
     }
   }
   

   For more information, see Configuring Session Event Listeners.

4. Package your EclipseLink application, including your session customizer, and redeploy on Oracle WebLogic Server.
   For more information, see Packaging an EclipseLink Application and Deploying an EclipseLink Application.
5. Confirm that EclipseLink JMX MBean instances for your application are not deployed.

What You May Need to Know About EclipseLink JMX Support

For more information on EclipseLink and Oracle WebLogic Server JMX support, see the following:

• Oracle WebLogic Server: Developing Manageable Applications with JMX
• Oracle WebLogic Server: Developing Custom Management Utilities with JMX

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 weblogic.policy 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 weblogic.policy file to grant permission for EclipseLink to use reflection.

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

A Subset of a "Grant" Section from a WebLogic.policy File

 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";
 };

Integrating EclipseLink with Oracle Containers for J2EE (OC4J)

To integrate a EclipseLink application with OC4J, you must consider 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.

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 the Server Platform).

For more information, see 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 eclipselink.jar file to the application server classpath in the global applib directory. Place the eclipselink.jar as noted by the element <shared-library name="global.libraries"> element in the $OC4J_HOME/config/server.xml file in the $OC4J_HOME/applib 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 Class Loader Order
• 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.

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:

1. Create a shared library that contains the <ECLIPSELINK_HOME>\jlib\eclipselink.jar file and associate the shared library with the application.
2. Ensure that your EclipseLink application defines an XML parser platform (see How to Configure the XML Parser Platform).

How to Configure Class Loader Order

If you are deploying a EclipseLink enabled application that uses EclipseLink sessions.xml 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 the Server Platform).

For more information, see 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.

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 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.

How to Configure the Sun Application Server Classpath

To configure EclipseLink support for SunAS, do the following:

1. Add the <ECLIPSELINK_HOME>\jlib\eclipselink.jar file to the application server classpath.
2. Ensure that your EclipseLink application defines an XML parser platform (see 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 the Server Platform).

For more information, see 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 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.

How to Configure the JBoss Classpath

To configure EclipseLink support for JBoss, do the following:

1. Add the <ECLIPSELINK_HOME>\jlib\eclipselink.jar file to the application server classpath.
2. Ensure that your EclipseLink application defines an XML parser platform (see 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 the Server Platform).

For more information, see 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 persistence.xml file.

Perform the following deployment changes:

1. If weaving is required, statically weave the entities before EAR packaging. Use either the command-line weaver or the weaving Ant task (see How to Configure Static Weaving for JPA Entities).
2. Ensure that the eclipselink.target-server property (see Using EclipseLink JPA Extensions for Session, Target Database and Target Application Server) is set in the persistence.xml file of all persistence units deployed to the JBoss container:

   <property name="eclipselink.target-server" value="JBoss"/>
   

   Otherwise, even though the container-managed entities are predeployed, they will not be managed at run time.

For more information and examples, see the following:

• http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/JBoss
• 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 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.

How to Configure the NetWeaver Classpath

To configure EclipseLink support for NetWeaver, do the following:

1. Create and deploy a standard library (i.e. an SDA file) that contains the <ECLIPSELINK_HOME>\jlib\eclipselink.jar file and associate the library with the application.
2. Ensure that your EclipseLink application defines an XML parser platform (see 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 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 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 java.lang.SecurityManager, the EclipseLink run time executes certain internal functions by executing a PrivilegedAction with java.security.AccessController method doPrivileged. 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).

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

If you run a EclipseLink-enabled application in a JVM without a nondefault SecurityManager, 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 java.lang.SecurityManager and doPrivileged operation is enabled, you may need to grant additional permissions if your application requires any of the following:

• Defining System Properties
• Loading project.xml or sessions.xml Files
• Defining Cache Coordination
• Accessing a Data Source by Port
• Logging with java.util.logging
• 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 <JAVA_HOME>/lib/security/java.policy file. If your application requires access to other platform-specific, environment, or custom properties, then grant further PropertyPermission permissions, as the following example shows.

Permissions for System Properties

permission java.util.PropertyPermission "my.property", "read";

Loading project.xml or sessions.xml Files

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

Permissions for Loading Deployment XML Files

permission java.io.FilePermission "${deployment.xml.home}/*.xml", "read";

For information on FilePermission settings for Java EE applications, see Granting Permissions for Java EE Application Deployment.

Defining Cache Coordination

If your application uses cache coordination (see Cache Coordination), then grant accept, connect, listen, and resolve 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 a Multicast Port) is 1024.

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 connect and resolve 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 remote.data.source.host and that this host accepts data source connections on port 1025.

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 java.util.logging package (see Configuring Logging), then grant your application control permissions, as this example shows.

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 eclipselink.jar 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 eclipse.persistence.xml.platform 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 doPrivileged operation when you run a EclipseLink-enabled application in a JVM configured with a nondefault java.lang.SecurityManager, you must grant the following permissions:

• java.lang.reflect.RelectPermission "suppressAccessChecks"
• java.lang.RuntimePermission "accessDeclaredMembers"
• java.lang.RuntimePermission "getClassLoader"

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 Disable doPrivileged Operation

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

To enable doPrivileged operation, set these system properties to true.

Copyright Statement