6 Using Remote Method Invocation

Choosing RMI/ORMI or RMI/IIOP

When can you use RMI/ORMI versus RMI/IIOP?

• Use RMI/ORMI to invoke methods on remote objects within or across OC4J instances.

  See "Using Oracle Remote Method Invocation (RMI/ORMI)" for details.

• Use RMI/IIOP to invoke methods on remote objects across OC4J and non-Oracle J2EE containers, such as BEA WebLogic.

  See "Switching from ORMI to IIOP Transport" for details.

Introducing RMI/ORMI

The Oracle Remote Method Invocation (ORMI) is Oracle's proprietary implementation of the RMI protocol that is optimized for use with OC4J.

By default, EJBs within OC4J server instances exchange RMI calls over ORMI. Alternatively, you can convert an EJB to exchange RMI calls over IIOP, making it possible for EJBs to invoke one another across different EJB containers from different vendors, such as OC4J and BEA WebLogic. See "Switching from ORMI to IIOP Transport" for more.

Configuring RMI in a Standalone OC4J Installation

In a standalone OC4J installation, you must specify RMI server data in the RMI configuration file, rmi.xml. You must also specify the location of this file in server.xml, the OC4J configuration file.

The rmi.xml file and the server.xml file are installed in ORACLE_HOME/j2ee/home/config by default

1. Specify the path to the RMI configuration file—rmi.xml—in the <rmi-config> element in server.xml, the OC4J server configuration file.

   The syntax is as follows:

   <rmi-config path="RMI_PATH" /> 
   

   The typical value for RMI_PATH is ./rmi.xml.

2. Add an <rmi-server> element specifying the host, port, and user name and password to use to connect to (and accept connections from) remote RMI servers to the rmi.xml file on the OC4J instance. This file is installed in ORACLE_HOME/j2ee/home/config by default.

   For example:

   <rmi-server host="hostname" port="port"> 
   </rmi-server>
   

   The attributes of the <rmi-server> element are:

   • host: The host name or IP address from which the RMI server accepts RMI requests. If you omit this attribute, the RMI server accepts RMI requests from any host.

   • port: The port number on which the RMI server listens for RMI requests. In an OC4J standalone environment, if you omit this attribute, it defaults to 23791.

3. Optionally configure the <rmi-server> element with one or more <server> elements that each specify a remote (point-to-point) RMI server that your application can contact over RMI.

   For example:

   <rmi-server host="hostname" port="port"> 
       <server host="serverhostname" username="username" port="serverport" 
       password="password"/> 
   </rmi-server>
   

   The host attribute is required; the remaining attributes are optional. Here are the user-replaceable attributes of the server element:

   • serverhostname: the host name or IP address on which the remote RMI server listens for RMI requests

   • username: the user name of a valid principal on the remote RMI server

   • serverport: the port number on which the remote RMI server listens for RMI requests

   • password: the password used by the principal username

<rmi-server  
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation=
   "http://xmlns.oracle.com/oracleas/schema/rmi-server-10_0.xsd"
  port="23791"
  ssl-port="23943"
  schema-major-version="10"
  schema-minor-version="0">

      <access-mask default="deny" >
         <host-access domain="localhost" mode="allow"/>
         <ip-access ip="192.168.1.0" netmask="255.255.255.0" mode="allow"/>
      </access-mask>

  <log>
    <file path="../log/rmi.log" />
  </log>

  <ssl-config
    keystore="../wallets/wallet-server-a/ewallet.p12"
    keystore-password="serverkey-a"
   />

   </rmi-server>

Client-Side Requirements to Use RMI/ORMI

This section lists the ZIP files that you use to install the Oracle and J2EE standard JAR files that enable EJB and JMS lookup using RMI/ORMI.

The following ZIP files are available from http://www.oracle.com/technology/software/products/ias/htdocs/utilsoft.html

• To enable EJB lookup using ORMI, download and expand oc4j_client_<version>.zip.

• To enable other lookups, such as JMS, download and expand oc4j_extended.zip instead of oc4j_client.zip.

Once the appropriate ZIP file is expanded, make sure that oc4jclient.jar is included in the CLASSPATH.

The ZIP files contain all the JAR files required by the client. The JAR files contain the classes necessary for client interaction. You only have to add oc4jclient.jar to your CLASSPATH, because all other JAR files required by the client are referenced in the oc4jclient.jar manifest classpath.

To enable EJB lookup, make sure that the following JAR files are included on the client side.

To enable resource adapter lookup, include the following JAR files on the client side.

To enable internal OEMS JMS In-Memory and File-Based lookup, make sure that the JAR files listed in Table 6-3, "Client-side JAR Files Required for OEMS JMS In-Memory and File-Based Lookup" are included on the client side.

To enable internal OEMS JMS Database lookup directly from an application client, make sure that the JAR files listed in Table 6-4, "Client-side JAR Files Required for OEMS JMS Database Lookup" are included on the client side.

Configuring RMI in an Oracle Application Server Environment

In an Oracle Application Server environment, you must edit the opmn.xml file to specify the port range on which this local RMI server listens for RMI requests.

Note that manual changes to configuration files in an Oracle Application Server environment must be manually updated on each OC4J instance.

To configure the opmn.xml file:

1. Configure the rmi port range using the port id="rmi" element as shown in the following example opmn.xml file excerpt:

   <ias-component id="OC4J">
       <process-type id="home" module-id="OC4J">
           <port id="default-web-site" range="12501-12600" protocol="ajp" />
           <port id="rmi" range="12401-12500" />
           <port id="rmis" range="12801-12900" />
           <port id="jms" range="12601-12700" />
           <process-set id="default_group" numprocs="1"/>
       </process-type>
   </ias-component>
   

   For more information on configuring the opmn.xml file, see the Oracle Application Server Administrator's Guide.

2. Apply changes by running the following opmnctl command:

   opmnctl reload 
   

Setting JNDI Properties for RMI

The following RMI/ORMI properties are specified in the client's jndi.properties file:

• java.naming.provider.url (see "Setting the Java Naming Provider URL")

• java.naming.factory.initial (see "Specifying the Context Factory")

<protocol>://<host>:[<port>]:<oc4j_instance>/<appName>

java.naming.provider.url=opmn:ormi://myHost:home/ejbsamples

<notification-server>
    <port local="6100" remote="6200" request="6004"/>
    <log-file path="$OLE_HOME/opmn/logs/ons.log" level="4"         rotation-size="1500000"/>
    <ssl enabled="true" wallet-file="$OLE_HOME/opmn/conf/ssl.wlt/default"/>
</notification-server>

opmnctl status -l 

Processes in Instance: server817.company.us.com
-------------------+--------------------+-------+ ... +------
ias-component      | process-type       |   pid | ... | ports
-------------------+--------------------+-------+ ... +------
OC4J               | home               |  2012 | ... | iiop:12701,jms:12601,rmi:12401
HTTP_Server        | HTTP_Server        | 28818 | ... | http2:7200,http1:7778,http:7200

Configuring ORMI Request Load Balancing

Load balancing of client ORMI requests made to EJBs deployed into multiple clustered OC4J instances is supported in OC4J.

The default behavior is for the client to connect to the same OC4J instance with each call. Specifically, each time the client calls InitialContext() using the same user/password/provider URL combination, the cached Context object created the first time the client was invoked will be returned. Thus, the client will send requests to the same OC4J instance defined by this Context object.

In situations where the number of client calls is fairly low, connecting in this manner is efficient and results in the best performance.

However, in situations where heavy request volume is expected, load balancing of requests across OC4J instances may be desired. Load balancing is configurable using the oracle.j2ee.rmi.loadBalance property, which can be set in the client's jndi.properties file or in a Hashtable in the client code. The values for this property are outlined in the following table.

The following example illustrates how this property can be set to lookup in a Hashtable:

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,"com.evermind.server.rmi.RMIInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "jazn.com/admin");
env.put(Context.SECURITY_CREDENTIALS, "password");
env.put(Context.PROVIDER_URL,"opmn:ormi://<hostname>:oc4j_inst1/ejbsamples");
env.put("oracle.j2ee.rmi.loadBalance","lookup");

Example Lookups Using ORMI

This section provides examples of how to look up an EJB using ORMI in:

• Standalone OC4J

• OC4J in Oracle Application Server

• OC4J in Previous Oracle Application Server Releases

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,"oracle.j2ee.rmi.RMIInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "admin");
env.put(Context.SECURITY_CREDENTIALS, "password");
env.put(Context.PROVIDER_URL, "ormi://<hostname>:23792/ejbsamples");

Context context = new InitialContext(env);
Object homeObject = context.lookup("MyCart"); 
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class); 

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,"oracle.j2ee.rmi.RMIInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "jazn.com/admin");
env.put(Context.SECURITY_CREDENTIALS, "password");
env.put(Context.PROVIDER_URL,"opmn:ormi://<hostname>:oc4j_inst1/ejbsamples");

Context context = new InitialContext(env);
Object homeObject = context.lookup("MyCart"); 
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class);

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,"com.evermind.server.rmi.RMIInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "jazn.com/admin");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
env.put(Context.PROVIDER_URL, "ormi://<hostname>:12401/ejbsamples");

Context context = new InitialContext(env);
Object homeObject = context.lookup("MyCart"); 
CartHome home = (CartHome)PortableRemoteObject.narrow(homeObject,CartHome.class); 

Introduction to RMI/IIOP

Java RMI enables you to create distributed Java-based to Java-based applications, in which the methods of remote Java objects can be invoked between JVMs, possibly on different hosts.

Version 2.0 of the EJB specification introduced features that make it easy for EJB-based applications to invoke one another across different containers. You can make your existing EJB interoperable without changing a line of code: simply edit the bean's properties and redeploy. "Switching from ORMI to IIOP Transport" discusses redeployment details.

EJB interoperability consists of the following:

• Transport interoperability, through CORBA IIOP Internet Inter-ORB Protocol, where ORB is Object Request Broker)

• Naming interoperability, through the CORBA CosNaming Service (CORBA Object Service Naming, part of the OMG CORBA Object Service specification)

• Security interoperability, through Common Secure Interoperability Version 2 (CSIv2)

• Transaction interoperability, through the CORBA Transaction Service (OTS)

OC4J furnishes transport, naming, and security interoperability.

Configuring OC4J for Interoperability

To add interoperability support to your EJB, you must specify interoperability properties. Some of these properties are specified when starting OC4J and others in bean properties that are specified in deployment files.

Client-Side Requirements to Use IIOP

This section lists the ZIP files that you use to install the Oracle and J2EE standard JAR files that enable EJB and JMS lookup using RMI/IIOP.

The following ZIP files are available from http://www.oracle.com/technology/software/products/ias/index.html:

• To enable EJB lookup using IIOP, download and expand oc4j_iiop_client.zip.

• To enable other lookups, such as JMS, you must also download and expand oc4j_extended.zip.

Once these ZIP files are expanded, make sure that oc4jclient.jar is included in the CLASSPATH.

The ZIP files contain all the JAR files required by the client. The JAR files contain the classes necessary for client interaction. You only have to add oc4jclient.jar to your CLASSPATH, because all other JAR files required by the client are referenced in the oc4jclient.jar manifest classpath.

While running the IIOP Client, the following properties must be set for IIOP clients:

• -Dorg.omg.CORBA.ORBInitialHost=${orb.host}

• -Dorg.omg.CORBA.ORBInitialPort=${orb.port}

• -Djavax.rmi.CORBA.PortableRemoteObjectClass=com.sun.corba.ee.impl.javax.rmi.PortableRemoteObject

• -Dcom.oracle.CORBA.OrbManager=com.oracle.corba.ee.impl.orb.ORBManagerImpl

Configuring an EJB for Interoperability in a Standalone OC4J Environment

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

1. Specify CSIv2 security policies for the bean in orion-ejb-jar.xml and in internal-settings.xml.

   For information about security topics, see the CSIv2 chapter in the Oracle Containers for J2EE Security Guide.

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 you are deploying. In OC4J, interoperability is individualy enabled for each application.

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.

   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/_iiopClient.jar 
   

   Note:

   IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. Therefore, you must manually add the JAR file to the classpath.

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 "Specifying the corbaname URL".

6. (Optional) To make the bean accessible to CORBA applications, run rmic.jar to generate IDL describing its interfaces.

Configuring an EJB for Interoperability in an Oracle Application Server Environment

This section describes how to convert an EJB to use RMI/IIOP in an Oracle Application Server environment.

1. Specify CSIv2 security policies for the bean in orion-ejb-jar.xml and in internal-settings.xml.

   For information about security topics, see the CSIv2 chapter in the Oracle Containers for J2EE Security Guide.

2. By default, RMI/IIOP is disabled in an Oracle Application Server environment. To enable RMI/IIOP, confirm in the OPMN configuration file J2EE_HOME/opmn/conf/opmn.xml that a unique iiop, iiops1, and iiops2 port (or port range) exists for each OC4J instance to be managed by OPMN. These are the port meanings:

   iiop—standard IIOP port

   iiops1—IIOP/SSL port used for server-side authentication only

   iiops2—IIOP/SSL port used for both client and server authentication

   Note:

   You must specify an iiop, iiops1, and iiops2 port (or port range) for each OC4J instance in which interoperability with CSIv2 is to be enabled. Failure to do so causes OC4J to not configure an IIOP listener, thus automatically disabling interoperability, regardless of the configuration in the internal-settings.xml file of OC4J.

   Here is an example:

   <ias-component id="OC4J">
       <process-type id="home" module-id="OC4J">
           <port id="ajp" range="3000-3100"/>
           <port id="rmi" range="23791-23799"/>
           <port id="jms" range="3201-3300"/>
           <port id="iiop" range="3401-3500"/>
           <port id="iiops1" range="3501-3600"/> 
           <port id="iiops2" range="3601-3700"/>
           <process-set id="default_group" numprocs="1"/>
       </process-type>
   </ias-component>
   

   Note:

   If you choose to configure your client's JNDI property java.naming.provider.url to use an OPMN URL, then your client cannot connect to iiops1 or iiops2 ports because OPMN-allocated ports are not reported to OC4J.

3. Use opmnctl to restart all OC4J instances that are managed by OPMN. Use the -DGenerateIIOP=true flag.

   opmnctl -DGenerateIIOP=true startall 
   

4. Deploy your application specifying the -enableIIOP option. For information about deployment, see the Oracle Containers for J2EE Deployment Guide.

5. Change the client's classpath to include the stub JAR file that was generated by OC4J. This is normally found in the server's deployment directory:

   application_deployment_directory/appname/ejb_module/_iiopClient.jar 
   

   Note:

   IIOP stub and tie class code generation occurs at deployment time, unlike ORMI stub generation, which occurs at runtime. Therefore, you must manually add the JAR file to the classpath.

6. Edit the client's JNDI property java.naming.provider.url to use an OPMN or corbaname URL instead of an ormi URL. For details on the corbaname URL, see "Specifying the corbaname URL". For details on the OPMN URL, see "Specifying the OPMN URL".

7. (Optional) To make the bean accessible to CORBA applications, run rmic.jar to generate IDL describing its interfaces.

Specifying 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

Specifying the OPMN URL

This section describes OPMN URL details that are specific to RMI/IIOP. For general information about the OPMN URL, see "Setting 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::host[:port][#instance-name]#appname

For example:

opmn:corbaname::dlsun74:6003#oc4j_inst1#ejbsamples 

Exception Mapping

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

Invoking OC4J-Hosted Beans from a Non-OC4J Container

EJBs that are not hosted in OC4J must be able to find oc4j_interop.jar on the classpath in order to invoke OC4J-hosted EJBs. OC4J expects the host 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.