5 Oracle Remote Method Invocation

Increased RMI Message Throughput

Using ORMI, OC4J can process at a very high transaction rate. This is reflected in Oracle's SpecJ Application Server benchmarks at:

http://www.spec.org/

One way ORMI achieves this performance is by using messages that are much smaller than IIOP messages. Smaller messages take less bandwidth to send and receive, and less processing time to encode and decode. ORMI message size is further reduced by optimizing how much state information is exchanged between client and server. Using ORMI, some state is cached on the server so that it does not need to be transmitted in every RMI call. This does not violate the RMI requirement to be stateless because in the event of a failover, the client code resends all the state information required by the new server.

Enhanced Threading Support

ORMI is tightly coupled with the OC4J threading model to take full advantage of its queuing, pooling, and staging capabilities.

ORMI uses one thread per client. For multi-threaded clients, OC4J multiplexes each call through one connection. However, OC4J does not serialize them, so multiple threads do not block each other.

This feature ensures that each client (single-threaded or multi-threaded) has one connection to the remote server.

Co-Located Object Support

For co-located objects, RMI/ORMI detects the co-located scenario and avoids the extra, unnecessary socket call.

The same is true when the JNDI registry is co-located.

Editing server.xml

Your server.xml file must specify the path name of the RMI configuration file in the <rmi-config> element. Here is the syntax:

<rmi-config path="RMI_PATH" /> 

The usual RMI_PATH is ./rmi.xml; you can name the file whatever you like.

In an Oracle Application Server environment only, apply changes by running the following on the Oracle Application Server command line:

dcmctl updateConfig 

Editing rmi.xml

Edit the rmi.xml file to specify which host, port, and user name and password to use to connect to (and accept connections from) remote RMI servers by configuring an rmi-server element.

To configure the rmi.xml file:

1. Add an rmi-server element for this local RMI server.

   For example:

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

   Here are the user-replaceable attributes of the <rmi-server> element:

   • hostname: 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.

     
     

     Note: In an OC4J standalone environment, if you omit this attribute, it defaults to 23791. In an Oracle Application Server environment, opmn selects an RMI port for each OC4J instance from the range of RMI ports defined in the opmn.xml file (see "Editing opmn.xml"); the rmi-server element port attribute is ignored.

     
     

2. Configure the rmi-server element with zero 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

3. Configure the rmi-server element with zero or more log elements that each specify a file to which RMI-specific notifications are written.

   For example, using the file element:

   <rmi-server host="hostname" port="port"> 
       <log>
           <file path="logfilepathname" />
       </log> 
   </rmi-server>
   
   

   Or using the odl element:

   <rmi-server host="hostname" port="port"> 
       <log>
           <odl path="odlpathname" max-file-size="size" max-num-files="num"/>
       </log> 
   </rmi-server>
   
   

   You can use either the file element or the odl element (but not both).

   Here are the user-replaceable attributes of the log element:

   • odlpathname: the path and folder name of the log folder for this area. You can use an absolute path or a path relative to the J2EE_HOME/config directory. This denotes where the RMI log files will reside.

   • size: the maximum size in bytes of each individual log file.

   • num: the maximum number of log files.

   • logfilepathname: the path name of a log file (logfilepathname) to which the server writes all RMI requests.

   The <odl> element is new in the OC4J 10g Release 2 (10.1.2) implementation. The ODL log entries are each written out in XML format in its respective log file. The log files have a maximum limit. When the limit is reached, the log files are overwritten.

   When you enable ODL logging, each message goes into its respective log file, named logN.xml, where N is a number starting at 1. The first log message starts the log file log1.xml. When the log file size maximum is reached, the second log file, named log2.xml, is opened to continue the logging. When the last log file is full, the first log file, log1.xml, is erased and a new one is opened for the new messages. Thus, your log files are constantly rolling over and do not encroach on your disk space.

   For more information about ODL logging, see the Oracle Application Server Containers for J2EE User's Guide.

4. In an Oracle Application Server environment only, apply changes by running the following on the Oracle Application Server command line:

   dcmctl updateConfig 
   

Editing opmn.xml

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

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="ajp" range="3301-3400" />
           <port id="rmi" range="3101-3200" />
           <port id="jms" range="3201-3300" />
           <process-set id="default-island" 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 on the Oracle Application Server command line:

   dcmctl updateConfig 
   

Naming Provider URL

Use the following syntax to set thejava.naming.provider.url:

<prefix>://<host>:<port>:<oc4j_instance>/<application-name> 

Table 5-2 describes arguments used in this syntax.

For example:

java.naming.provider.url=opmn:ormi://localhost:oc4j_inst1/ejbsamples 

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

opmnctl status -l 

Processes in Instance: core817.dsunrdb22.us.oracle.com
-------------------+--------------------+-------+ ... +------
ias-component      | process-type       |   pid | ... | ports
-------------------+--------------------+-------+ ... +------
WebCache           | WebCacheAdmin      | 28821 | ... | administration:4000
WebCache           | WebCache           | 28820 | ... | statistics:4002,invalidation:4001,http:7777
OC4J               | home               |  2012 | ... | iiop:3401,jms:3701,rmi:3201,ajp:3000
HTTP_Server        | HTTP_Server        | 28818 | ... | http2:7200,http1:7778,http:7200
dcm-daemon         | dcm-daemon         | 28811 | ... | N/A
LogLoader          | logloaderd         |   N/A | ... | N/A

iiop:3401,jms:3701,rmi:3201,ajp:3000 

Context Factory Usage

The initial context factory creates the initial context class for the client.

Set thejava.naming.factory.initial property to one of the following:

• com.evermind.server.ApplicationClientInitialContextFactory

• com.evermind.server.ApplicationInitialContextFactory

• com.evermind.server.RMIInitialContextFactory.

The ApplicationClientInitialContextFactory is used when looking up remote objects from standalone application clients. It uses the refs and ref-mappings found in application-client.xml and orion-application-client.xml. It is the default initial context factory when the initial context is instantiated in a Java application.

The RMIInitialContextFactory is used when looking up remote objects between different containers using the ORMI protocol.

The type of initial context factory that you use depends on who the client is:

• If the client is a pure Java client outside the OC4J container, then use the ApplicationClientInitialContextFactory class.

• If the client is an EJB or servlet client within the OC4J container, then use the ApplicationInitialContextFactory class. This is the default class; thus, each time you create a new InitialContext without specifying an initial context factory class, your client uses the ApplicationInitialContextFactory class.

• If the client is an administrative class that is going to manipulate or traverse the JNDI tree, then use the RMIInitialContextFactory class.

• If the client is going to use DNS load balancing, then use the RMIInitialContextFactory class.

OC4J Standalone

The following example shows how to look up an EJB called MyCart in the J2EE application ejbsamples deployed in a standalone OC4J instance. The application is located on a node named localhost, configured to listen on RMI port 23792:

Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY,"com.evermind.server.rmi.RMIInitialContextFactory");
env.put(Context.SECURITY_PRINCIPAL, "admin");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
env.put(Context.PROVIDER_URL, "ormi://localhost:23792/ejbsamples");

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

OC4J in Oracle Application Server: Releases Before 9.0.4

In an OC4J instance in an Oracle Application Server environment, RMI ports are assigned dynamically, and JAZNUserManager is the default user manager.

In Oracle Application Server releases before 10g Release 2 (10.1.2), if you are accessing an EJB in Oracle Application Server, you have to know the RMI ports assigned by opmn. If you have only one JVM for your OC4J instance, then you have to limit the port ranges for RMIs to a specific number, for example: 3101-3101.

The following example shows how to look up an EJB called MyCart in the J2EE application ejbsamples in an Oracle Application Server environment in releases before 10g Release 2 (10.1.2). The application is located on a node named localhost configured to listen on RMI port 3101:

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://localhost:3101/ejbsamples");

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

OC4J in Oracle Application Server Since 9.0 4

You can use the following type of lookup in the URL to look up an EJB in an Oracle Application Server environment without needing to know the RMI port assigned to your OC4J instance.

The following example shows how to look up the EJB named MyCart in the J2EE application ejbsamples in an Oracle Application Server 10g Release 2 (10.1.2) environment. The EJB application is located on a node named localhost. The differences between this invocation and the standalone invocation are: the opmn prefix to ormi, the specification of the OC4J instance name oc4j_inst1 to which the EJB application is deployed, and no requirement to specify the RMI port:

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,"opmn:ormi://localhost:oc4j_inst1/ejbsamples");

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