Fusion Middleware Documentation
Advanced Search


Developing RMI Applications for Oracle WebLogic Server
Close Window

Table of Contents

Show All | Collapse

3 WebLogic RMI Features

This chapter describes the WebLogic RMI features and guidelines required to program RMI for use with WebLogic Server.

This chapter includes the following sections:

WebLogic RMI Clients

WebLogic RMI is divided between a client and server framework. The client run time does not have server sockets and therefore does not listen for connections. It obtains its connections through the server. Only the server knows about the client socket. Therefore if you plan to host a remote object on the client, you must connect the client to WebLogic Server. WebLogic Server processes requests for and passes information to the client. In other words, client-side RMI objects can only be reached through a single WebLogic Server, even in a cluster. If a client-side RMI object is bound into the JNDI naming service, it only be reachable as long as the server that carried out the bind is reachable.

WebLogic RMI Security Support

WebLogic Server implements authentication, authorization, and Java EE security services. For more information see Developing Applications with the WebLogic Security Service.

WebLogic RMI Transaction Support

WebLogic Server supports transactions in the Java Platform, Enterprise Edition (Java EE) programming model. For detailed information on using transactions in WebLogic RMI applications, see the following:

Failover and Load Balancing RMI Objects

The following sections contain information on WebLogic Server support for failover and load balancing of RMI objects:

Clustered RMI Applications

For clustered RMI applications, failover is accomplished using the object's replica-aware stub. When a client makes a call through a replica-aware stub to a service that fails, the stub detects the failure and retries the call on another replica.

To make Java EE services available to a client, WebLogic binds an RMI stub for a particular service into its JNDI tree under a particular name. The RMI stub is updated with the location of other instances of the RMI object as the instances are deployed to other servers in the cluster. If a server within the cluster fails, the RMI stubs in the other server's JNDI tree are updated to reflect the server failure.

You specify the generation of replica-aware stubs for a specific RMI object using the -clusterable option of the WebLogic RMI compiler, as explained in Table 5-1, "WebLogic RMI Compiler Options". For example:

$ java weblogic.rmic -clusterable classes

For more information, see "Replication and Failover for EJBs and RMIs" in Administering Clusters for Oracle WebLogic Server.

Load Balancing RMI Objects

The load balancing algorithm for an RMI object is maintained in the replica-aware stub obtained for a clustered object. You specify the load balancing algorithm for a specific RMI object using the -loadAlgorithm <algorithm> option of the WebLogic RMI compiler. A load balancing algorithm that you configure for an object overrides the default load balancing algorithm for the cluster. The WebLogic Server RMI compiler supports the following load balancing algorithms:

For example, to set load balancing on an RMI object to round robin, use the following rmic options:

$ java weblogic.rmic -clusterable -loadAlgorithm round-robin classes

To set load balancing on an RMI object to weight-based server affinity, use rmic options:

$ java weblogic.rmic -clusterable -loadAlgorithm weight-based -stickToFirstServer classes

For more information, see "Load Balancing for EJBs and RMI Objects" in Administering Clusters for Oracle WebLogic Server.

Parameter-Based Routing for Clustered Objects

Parameter-based routing allows you to control load balancing behavior at a lower level. Any clustered object can be assigned a CallRouter using the weblogic.rmi.cluster.CallRouter interface. This is a class that is called before each invocation with the parameters of the call. The CallRouter is free to examine the parameters and return the name server to which the call should be routed.

weblogic.rmi.cluster.CallRouter. 

      Class java.lang.Object
        Interface weblogic.rmi.cluster.CallRouter
        (extends java.io.Serializable)

A class implementing this interface must be provided to the RMI compiler (rmic) to enable parameter-based routing. Run rmic on the service implementation using these options (to be entered on one line):

$ java weblogic.rmic -clusterable -callRouter <callRouterClass> <remoteObjectClass>

The call router is called by the clusterable stub each time a remote method is invoked. The router is responsible for returning the name of the server to which the call should be routed.

Each server in the cluster is uniquely identified by its name as defined with the WebLogic Server Console. These are the names that the method router must use for identifying servers.

Consider the ExampleImpl class which implements a remote interface Example, with one method foo:

public class ExampleImpl implements Example {
   public void foo(String arg) { return arg; }
   }

This CallRouter implementation ExampleRouter ensures that all foo calls with 'arg' < "n " go to server1 (or server3 if server1 is unreachable) and that all calls with 'arg' >= "n " go to server2 (or server3 if server2 is unreachable).

public class ExampleRouter implements CallRouter {
  private static final String[] aToM = { "server1", "server3" };
  private static final String[] nToZ = { "server2", "server3" };

  public String[] getServerList(Method m, Object[] params) {
    if (m.GetName().equals("foo")) {
      if (((String)params[0]).charAt(0) < 'n') {
        return aToM;
      } else {
        return nToZ;
      }
    } else {
      return null;
    }
  }
}

This rmic call associates the ExampleRouter with ExampleImpl to enable parameter-based routing:

$ rmic -clusterable -callRouter ExampleRouter ExampleImpl

Custom Call Routing and Collocation Optimization

If a replica is available on the same server instance as the object calling it, the call is not load-balanced as it is more efficient to use the local replica. For more information, see "Optimization for Collocated Objects" in Administering Clusters for Oracle WebLogic Server.

Request Timeouts

You can specify timeout period for the remote call to complete or the client receives a weblogic.rmi.extensions.RequestTimeoutException.

WebLogic Server provides the following connect and read timeouts:

Using a Connect Timeout

Use a connect timeout to define the length of time a client waits for connections to the server to be bootstrapped or re-established. The following table describes how to set this timeout.

Table 3-1 Setting a Connect Timeout

Description Scope

System property: -Dweblogic.ConnectTimeout=milliseconds

Server

Set KernelMBean.ConnectTimeout property

Server

Set NetworkAccessPointMBean.connectTimeout property. For non-default channels only and overrides a server scoped setting. Only connections established using this channel definition are subject to this timeout.

Channel

Set WLContext.CONNECT_TIMEOUT to establish the connection to a server. (Within the scope of the context, used for both bootstrapping a connection as well re-establishing a lost connection.)

Thread


Using a Read Timeout

Use a read timeout to define the length of time that a client waits to receive a response from a server. The following table describes various ways to set this timeout value.

Table 3-2 Setting a Read Timeout

Description Scope

Set WLContext.RESPONSE_READ_TIMEOUT in the JNDI (InitialContext) environment used to lookup the remote stub.

Interface (stub)

Specify the method level annotation (@RmiMethod(timeout=<value>)) in the remote object implementation class.

Method

Set a timeout attribute in method definition in an rtd.xml file for non-annotated classes. See Example rtd.xml file with a Timeout.

Method

Specify the method level annotation @TransactionTimeoutSeconds(<timeout>) in the EJB bean implementation class.

Method

Specify a remote-client-timeout in EJB descriptor (weblogic-ejb-jar.xml). See Example weblogic-ejb-jar.xml file with a Timeout.

Method


Consider the following when implementing a read timeout:

  • In the WebLogic Server EJB bean implementation, a transaction timeout (@TransactionTimeoutSeconds) takes precedence over remote-client-timeout if it has a greater value.

  • The precedence of multiple read timeouts is determined using the following rules:

    • A timeout specified in rtd.xml on the client overrides any other read timeout.

    • A timeout specified using an RmiMethod annotation overrides a WLContext.RESPONSE_READ_TIMEOUT.

Example rtd.xml file with a Timeout

The following code provides an example of an rtd.xml file that includes an timeout:

<rmi Name="foo">
   <method
       name="methodname"
       timeout="timeoutinmilliseconds">
   </method>
</rmi>

To generate an rtd.xml file on the client, set -Dweblogic.RefreshClientRuntimeDescriptor=true on both the client and the server. When the flag is true, a check is made to see if the rtd.xml file is available on the classpath. If available, the file is read and the values specified are used.

Example weblogic-ejb-jar.xml file with a Timeout

The following code provides an example of how to specify a remote-client-timeout in the weblogic-ejb-jar.xml file:

<weblogic-enterprise-bean>
     <ejb-name>AccountBean</ejb-name>
     . . .
     <remote-client-timeout>5</remote-client-timeout>
</weblogic-enterprise-bean>

Creating Pinned Services

You can also use weblogic.rmic to generate stubs that are not replicated in the cluster. These stubs are known as "pinned " services, because after they are registered they are available only from the host with which they are registered and will not provide transparent failover or load balancing. Pinned services are available cluster-wide, because they are bound into the replicated cluster-wide JNDI tree. However, if the individual server that hosts the pinned services fails, the client cannot failover to another server.

You specify the generation of non-replicated stubs for a specific RMI object by not using the -clusterable option of the WebLogic RMI compiler, as explained in Table 5-1, "WebLogic RMI Compiler Options". For example:

$ java weblogic.rmic classes

Dynamic Proxies in RMI

A dynamic proxy or proxy is a class used by the clients of a remote object. This class implements a list of interfaces specified at runtime when the class is created. In the case of RMI, dynamically generated bytecode and proxy classes are used. The proxy class is the instance that is invoked upon in the client's Java Virtual Machine (JVM). The proxy class marshals the invoked method name and its arguments; forwards these to the remote JVM. After the remote invocation is completed and returns, the proxy class unmarshals the results on the client. The generated bytecode — which exists in the remote JVM — unmarhsals the invoked method and arguments on the remote JVM, invokes the method on the instance of the remote object, and then marshals the results for return to the client.