6 J2EE Interoperability

Transport

By default, OC4J EJBs use RMI/Oracle Remote Method Invocation (ORMI), a proprietary protocol, to communicate as described in Chapter 5, "Oracle Remote Method Invocation".

In OC4J, you can easily convert an EJB to use RMI/IIOP, making it possible for EJBs to invoke one another across different EJB containers. This chapter describes configuring and using RMI/IIOP.

Naming

OC4J supports the CORBA CosNaming service. OC4J can publish EJBHome object references in a CosNaming service and provides a JNDI CosNaming implementation that allows applications to look up JNDI names using CORBA. You can write your applications using either the JNDI or CosNaming APIs.

Security

OC4J supports Common Secure Interoperability Version 2 (CSIv2), which specifies different conformance levels; OC4J complies with the EJB specification, which requires conformance level 0.

Transactions

The EJB2.0 specification stipulates an optional transactional interoperability feature. Conforming implementations must choose one of the following:

• Transactionally interoperable: transactions are supported between beans that are hosted in different J2EE containers.

• Transactionally noninteroperable: transactions are supported only among beans in the same container.

The current release of OC4J is transactionally noninteroperable, so when a transaction spans EJB containers, OC4J raises a specified exception.

Client-Side Requirements

To access EJBs, you must do the following on the client-side:

1. Download the oc4j_client.zip file from

   http://www.oracle.com/technology/software/products/ias/devuse.html 
   
   

2. Unzip it into a client-side directory. (for example, d:\oc4jclient).

3. Add d:\oc4jclient\oc4jclient.jar to your CLASSPATH.

The oc4j_client.zip file contains all the JAR files required by the client (including oc4jclient.jar and optic.jar). These JAR files contain the classes necessary for client interaction. You need to add only oc4jclient.jar to your CLASSPATH, because all other JAR files required by the client are referenced in the oc4jclient.jar manifest classpath.

If you download this file into a browser, you must grant certain permissions as described in the "Granting Permissions" section of the Security chapter in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

The rmic.jar Compiler

To invoke or be invoked by CORBA objects, RMI objects must have corresponding stubs, skeletons, and Internet Description Language (IDL). Use the rmic.jar compiler to generate stubs and skeletons from Java classes or to generate IDL, as described in "Configuring OC4J for RMI".

For use with RMI/IIOP, be sure to compile using the -iiop option.

Simple Interoperability in a Standalone Environment

Follow these steps to convert an EJB to use RMI/IIOP in a standalone environment:

1. Restart OC4J with the -DGenerateIIOP=true flag.

2. Deploy your application using admin.jar. You must obtain the client's stub JAR file, using the -iiopClientJar switch. Here is an example:

   java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy -file filename -deploymentName application_name -iiopClientJar stub_jar_filename 
   

   
   

   Note: You must use the -iiopClientJar switch to enable interoperability (IIOP) for the application you are deploying. In OC4J, interoperability is enabled on a per-application basis.

   
   

3. Change the client's classpath to include the stub JAR file that was obtained during deployment, by running admin.jar with the -iiopClientJar switch.

   A copy of the stub JAR file that was generated by OC4J can also be found in the server's deployment directory at:

   application_deployment_directory/appname/ejb_module/module_iiopClient.jar 
   
   

4. Edit the client's JNDI property java.naming.provider.url to use a corbaname URL instead of an ormi URL. For details on the corbaname URL, see "The corbaname URL".

   
   

   Note: IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. This is why you must add the JAR file to the classpath yourself. If you run in the server, a list of generated classes required by the server and IIOP stubs is made available automatically.

   
   

5. (Optional) To make the bean accessible to CORBA applications, run rmic.jar to generate IDL describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

Advanced Interoperability in a Standalone Environment

This section expands upon the preceding section, describing how to convert an EJB to use RMI/IIOP in a standalone environment.

1. Specify CSIv2 security policies for the bean in orion_ejb_jar.xml and in internal_settings.xml. See the Oracle Application Server Containers for J2EE Security Guide for more information on these security-related topics.

2. Restart OC4J with the -DGenerateIIOP=true flag.

3. Deploy your application using admin.jar. You must obtain the client's stub JAR file using the -iiopClientJar switch. Here is an example:

   java -jar $J2EE_HOME/admin.jar ormi://localhost admin welcome -deploy -file filename -deployment_name application_name -iiopClientJar stub_jar_filename 
   

   
   

   Note: You must use the -iiopClientJar switch to enable interoperability (IIOP) for the application that you are deploying. In OC4J, interoperability is enabled on a per-application basis.

   
   

4. Change the client's classpath to include the stub JAR file that was obtained during deployment, by running admin.jar with the -iiopClientJar switch.

   You can also find a copy of the stub JAR file that was generated by OC4J in the server's deployment directory at:

   application_deployment_directory/appname/ejb_module/module_iiopClient.jar 
   
   

5. Edit the client's JNDI property java.naming.provider.url to use a corbaname URL instead of an ormi URL. For details on the corbaname URL, see "The corbaname URL".

   
   

   Note: IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. This is why you must add the JAR file to the classpath yourself. If you run in the server, a list of generated classes required by the server and IIOP stubs is made available automatically.

   
   

6. (Optional) To make the bean accessible to CORBA applications, run rmic.jar to generate IDL describing its interfaces. See "Configuring OC4J for Interoperability" for a discussion of command-line options.

Simple Interoperability in Oracle Application Server Environment

You can access an EJB using RMI/IIOP in an Oracle Application Server environment in two ways:

• Configuring for Interoperability Using Oracle Enterprise Manager 10g

• Configuring for Interoperability Manually

Advanced Interoperability in Oracle Application Server Environment

You can access an EJB using RMI/IIOP in an Oracle Application Server environment in two ways:

• Configuring for Interoperability Using Oracle Enterprise Manager 10g

• Configuring for Interoperability Manually

The corbaname URL

To interoperate, an EJB must look up other beans using CosNaming. This means that the URL for looking up the root NamingContext must use the corbaname URL scheme instead of the ormi URL scheme. This section discusses the corbaname subset that EJB developers use most often. For a full discussion of the corbaname scheme, see section 2.5.3 of the CORBA Naming Service specification. The corbaname scheme is based on the corbaloc scheme, which section 13.6.10.1 of the CORBA specification discusses.

The most common form of the corbaname URL scheme is:

corbaname::host[:port] 

This corbaname URL specifies a conventional DNS host name or IP address, and a port number. For example,

corbaname::example.com:8000 

A corbaname URL can also specify a naming context by following the host and port by # and NamingContext in string representation. The CosNaming service on the specified host is responsible for interpreting the naming context.

corbaname::host[:port]#namingcontext 

For example:

corbaname::example.com:8000#Myapp 

The OPMN URL

This section describes OPMN URL details that are specific to RMI/IIOP. For general information about the OPMN URL, see "JNDI Properties for RMI".

In an Oracle Application Server environment, IIOP ports for all OC4J processes within each Oracle Application Server instance are dynamically managed by OPMN. Because of this, it may not be possible for clients to know the ports on which OC4J processes are actively listening for IIOP requests. To enable clients to successfully make RMI/IIOP requests in an Oracle Application Server environment without having to know the IIOP ports for all active OC4J processes, modify the jndi.naming.provider.url property (in the client's jndi.properties file) with a URL of the following format:

opmn:corbaname::opmn_host[:opmn_port]:]:OC4J_instance_name#naming_context 

For example:

opmn:corbaname::dlsun74:6003:home#stateless 

Exception Mapping

When EJBs are invoked over IIOP, OC4J must map system exceptions to CORBA exceptions. Table 6-1 lists the exception mappings.

Invoking OC4J-Hosted Beans from a Non-OC4J Container

EJBs that are not hosted in OC4J must add the file oc4j_interop.jar to the classpath to invoke OC4J-hosted EJBs. OC4J expects the other container to make the HandleDelegate object available in the JNDI name space at java:comp/HandleDelegate. The oc4j_interop.jar file contains the standard portable implementations of home and remote handles, and metadata objects.

Interoperability OC4J Flags

The following OC4J startup flags support RMI interoperability:

• -DGenerateIIOP=true generates new stubs and skeletons whenever you redeploy an application.

• -Diiop.debug=true generates deployment-time debugging messages, most of which have to do with code generation.

• -Diiop.runtime.debug=true generates runtime debugging messages.

Interoperability Configuration Files

Before EJBs can communicate, you must configure the parameters in the configuration files listed in Table 6-2.

JNDI Properties for Interoperability (jndi.properties)

The following RMI/IIOP properties are controlled by the client's jndi.properties file:

• java.naming.provider.url may be an OPMN or a corbaname URL for the bean to be interoperable. For details on corbaname URLs, see "The corbaname URL". For details on the OPMN URL, see "The OPMN URL".

• contextFactory can be either ApplicationClientInitialContextFactory or the class IIOPInitialContextFactory.

  If your application has an application-client.xml file, then leave contextFactory set to ApplicationClientInitialContextFactory. If your application does not have an application-client.xml file, then change contextFactory to IIOPInitialContextFactory.

Enabling IIOP in OC4J

This tutorial describes the steps necessary to enable IIOP applications in OC4J. After completing this exercise you should be able to:

• Access a remote EJB over IIOP

• Secure EJB invocations with IIOP over SSL

• Secure corbaname lookups by remote clients with IIOP over SSL

To minimize deployment and configuration changes, the tutorial uses the demo "helloworld" EJB application available through the installation and on Oracle's OTN site:

http://www.oracle.com/technology/sample_code/tech/java/ejb_corba/index.html

Building and deploying the helloworld application with a default OC4J installation results in an application that is only accessible over ORMI. To enable IIOP for a given application you must make the following changes to OC4J's server configuration and the client application. The required changes include:

• Configure the IIOPServerExtensionProvider

• Change the java.naming.provider.url

• Deploy the application using the -iiopClientJar argument

The following sections describe the steps in more detail.

Getting Started

Expand the EJB demos to your development environment. The helloworld application should be under <install-dir>/demo/ejb/helloworld with the following structure:

|-------dist
|-------etc
|       |-------application-client.xml
|       |-------application.xml
|       |-------ejb-jar.xml
|       |-------jndi.properties
|-------src
|       |-------ejb
|       |       |-------client
|       |       |       |-------HelloClient.java
|       |       |-------helloworld-ejb
|       |               |-------Hello.java
|       |               |-------HelloBean.java
|       |               |-------HelloHome.java
|       |               |-------HelloLocal.java
|       |               |-------HelloLocalHome.java
|------build.xml

Applications other than the helloworld example can be ignored for the remainder of the tutorial, but should be unaffected by changes required for enabling IIOP. This tutorial installs the demos to the root partition, so the application is under /demo/ejb/helloworld.

The supplied Ant build file provides targets for compiling the src, building the jar and ear, and running the client application. This tutorial assumes you are familiar with Ant build files. If you are unfamiliar with Ant, please see Apache's Ant documentation site: http://ant.apache.org/manual/index.html

Configure IIOP in OC4J

Edit the server.xml file as follows:

  <install-dir>j2ee/home/config/internal-settings.xml

Make sure the server.xml file contains the following line:

<sep-config path="./internal-settings.xml" />

If the line is missing, or commented out, remove the comments or add the line below the following line:

<rmi-config path="./rmi.xml" />

This configures the IIOPServerExtensionProvider for OC4J.

Now edit the internal-settings.xml file as follows to configure your IIOP settings:

<install-dir>j2ee/home/config/internal-settings.xml

Make sure the file contains the following settings:

<server-extension-provider name="IIOP"
   class="com.oracle.iiop.server.IIOPServerExtensionProvider">
   <sep-property name="port" value="5555" />
   <sep-property name="host" value="localhost" />
   <sep-property name="ssl" value="false" />
   <sep-property name="trusted-clients" value="*" />
</server-extension-provider>

If necessary, you can modify the host and port to match your environment. If your file contains entries for SSL, temporarily comment them out:

<!--
   <sep-property name="ssl-port" value="5556" />
   <sep-property name="ssl-client-server-auth-port" value="5557" />
   <sep-property name="keystore" value="keystore.jks" />
   <sep-property name="keystore-password" value="->pwForSSL" />
   <sep-property name="truststore" value="truststore.jks" />
   <sep-property name="truststore-password" value="->pwForSSL" />
-->

Now OC4J is configured for IIOP. The final step to enable IIOP on the server side is to start OC4J with the JVM argument: -DgenerateIIOP=true. This can be done on the command line for OC4J standalone, and in the ${ORACLE_HOME}/opmn/opmn.xml file for Oracle Application Server installs.

Configure the JNDI provider URL

Edit the jndi.properties file as follows for the helloworld application:

<install-dir>/demo/ejb/helloworld/etc/jndi.properties

java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory
java.naming.provider.url=corbaname:iiop:localhost:5555#helloworld
#java.naming.provider.url=ormi://localhost:23791/helloworld
java.naming.security.principal=admin
java.naming.security.credentials=welcome

Comment out the line containing the ORMI provider URL, and add a line matching the corbaname provider URL in the example.

Build and deploy the application

From the <install-dir>/demo/ejb/helloworld directory, run the default ant target to build the application:

<install-dir>/demo/ejb/helloworld > ant

Start OC4J if you have not done so already, then execute the following deploy command:

java -jar ${J2EE_HOME}/admin.jar ormi://localhost:23791 admin welcome -deploy -file dist/helloworld.ear -deploymentName helloworld -iiopClientJar dist/helloworld_iiop_client.jar 

This deploys the helloworld application and generates the client EJB JAR containing the client IIOP stubs in dest/helloworld_iiop_client.jar.

Run the application

Edit the <install-dir>/demo/ejb/common.xml file, and make sure the environment settings for ORACLE_HOME, JAVA_HOME, and J2EE_HOME match your environment.

Execute > ant run

You should see the appropriate "Hello ..." response from the client application. To verify that communication is running over IIOP, you can set the following JMV arg on both the client and the server:

-Diiop.runtime.debug=true

Enable IIOP over SSL on the server

Edit the internal-settings.xml file and uncomment or add the SSL settings (indicated by the bold lines in the following example):

<server-extension-provider name="IIOP"
   class="com.oracle.iiop.server.IIOPServerExtensionProvider">
   <sep-property name="port" value="5555" />
   <sep-property name="host" value="localhost" />
   <sep-property name="ssl" value="true" />
   <sep-property name="trusted-clients" value="*" />
   <sep-property name="ssl-port" value="5556" />
   <sep-property name="ssl-client-server-auth-port" value="5557" />
   <sep-property name="keystore" value="keystore.jks" />
   <sep-property name="keystore-password" value="yourPWD" />
   <sep-property name="truststore" value="truststore.jks" />
   <sep-property name="truststore-password" value=" yourPWD " />
</server-extension-provider>

If necessary, you can modify the host and port to match your environment. The keystore and truststore files may be the same physical file. The names above are only for illustration. If you do not have a keystore file, you can use the following Sun example for using the keytool:

http://java.sun.com/docs/books/tutorial/security1.2/summary/tools.html

Add the absolute path and filename to the keystore and truststore properties in the example.

Enable SSL on the client

Edit the jndi.properties file for the helloworld application:

<install-dir>/demo/ejb/helloworld/etc/jndi.properties
java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory
java.naming.provider.url=corbaname:iiop:localhost:5556#helloworld
java.naming.security.principal=admin
java.naming.security.credentials=welcome

Change the port in the provider URL to be the SSL port from internal-settings.xml.

Create a file called ejb_sec.properties for the helloworld application:

oc4j.iiop.trustedServers=*
nameservice.useSSL=true
oc4j.iiop.trustStoreLoc=<path to server's keystore>
oc4j.iiop.trustStorePass=<password for server's keystore file>

This file communicates the applications security requirements to the OC4J client bootstrap classes. The properties in this example indicate that SSL should be used for EJB lookups, and that all servers supporting SSL should be trusted. The truststore setting is a quick way of using the same keystore configured for OC4J instead of exporting the certificate in the servers keystore and importing it into a second truststore file.

Run the application with IIOP over SSL

Execute > ant run

You should see the appropriate "Hello ..." response from the client application. To verify that communication is running with IIOP over SSL, set the -Diiop.runtime.debug=true for both the client and the server.