WebLogic RMI Features and Guidelines


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| Download Documentation \| Contact \| Glossary

\| WebLogic Server Doc Home \| Programming WebLogic RMI \| Previous Topic \| Next Topic \| Contents \| View as PDF

The following sections describe the WebLogic RMI features that you use to program RMI for use with WebLogic Server.

WebLogic RMI Framework

WebLogic RMI is divided between a client and server framework. The client runtime 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, the client must be connected 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 will only be reachable as long as the server that carried out the bind is reachable.

WebLogic RMI Compiler

The WebLogic RMI compiler (weblogic.rmic) generates dynamic proxies on the client-side for custom remote object interfaces and provides hot code generation for server-side objects. When rmic is run, the hot code generation feature generates bytecode that is dynamically created at runtime, when the RMI object is deployed.

Note: You only need to explicitly run rmic for clusterable or IIOP clients. (WebLogic RMI over IIOP extends the RMI programming model by providing the ability for clients to access RMI remote objects using the Internet Inter-ORB Protocol, IIOP.) See Programming WebLogic RMI over IIOP for more information on using RMI over IIOP.

The dynamic proxy class is the serializable class that is passed to the client. Hot code generation is the RMI feature that produces the bytecode is a server-side class that processes requests from the dynamic proxy on the client. The implementation for the class is bound to a name in the RMI registry in WebLogic Server.

A client acquires the proxy for the class by looking up the class in the registry. The client calls methods on the proxy just as if it were a local class and the proxy serializes the requests and sends them to WebLogic Server. The dynamically created bytecode de-serializes client requests and executes them against the implementation classes, serializing results and sending them back to the proxy on the client.

Migrating from Stubs and Skeletons to Dynamic Proxies and Bytecode

In previous versions of WebLogic Server, pre 6.1, running rmic generated stubs on the client and skeleton code on the server-side. Now, rmic generates an XML deployment descriptor which is loaded at runtime. Instead of a stub, the client uses a dynamic proxy to communicate with remote objects. A skeleton class is created on the fly in memory. So, you no longer need to generate classes.

To enable pre-6.1 WebLogic RMI objects to run under later versions of WebLogic Server, rerun rmic on those objects. This will generate the necessary proxies and bytecode that enable the deployed RMI object.

If your remote objects are EJBs, rerun weblogic.ejbc again to enable pre-WebLogic Server 6.1 objects to work in the post-6.1 version. See Programming Enterprise JavaBeans for instructions on using weblogic.ejbc.

Rerunning either weblogic.rmic using one or more of the following parameters, -oneway, -clusterable, -stickToFirstServer or weblogic.ejbc on the remote object produces a deployment descriptor file for that object

WebLogic RMI Compiler Options

The WebLogic RMI compiler accepts any option supported by the Java compiler; for example, you could add -d \classes examples.hello.HelloImpl to the compiler option at the command line. All other options supported by the Java compiler can be used and are passed directly to the Java compiler.

The following tables list java weblogic.rmic options. Enter these options after java weblogic.rmic and before the name of the remote class.

Table 2-1 WebLogic RMI Compiler Options

Option	Description
-callRouter <callRouterClass>	Only for use in conjunction with -clusterable. Specifies the class to be used for routing method calls. This class must implement weblogic.rmi.cluster.CallRouter. If specified, an instance of the class is called before each method call and can designate a server to route to based on the method parameters. This option either returns a server name or null. Null indicates that the current load algorithm should be used.
-clusterable	Marks the service as clusterable (can be hosted by multiple servers in a WebLogic cluster). Each hosting object, or replica, is bound into the naming service under a common name. When the service proxy is retrieved from the naming service, it contains a replica-aware reference that maintains the list of replicas and performs load-balancing and fail-over between them.
-commentary	Emits commentary
-dispatchPolicy <queueName>	Specifies a configured execute queue that the service should use for obtaining execute threads in WebLogic Server. See Using Execute Queues to Control Thread Usage for more information.
-help	Prints a description of the options
-idl	Generates IDLs for remote interfaces
-idlOverwrite	Overwrites existing IDL files
-idlVerbose	Displays verbose information for IDL information
-idlStrict	Generates IDL according to OMG standard
-idlNoFactories	Prevents generation of factory methods for value types
-idlDirectory <idlDirectory>	Specifies the directory where IDL files will be created (Default = current directory)
-iiop	Generates IIOP proxy from servers
-iiopDirectory	Specifies the directory where IIOP proxy classes are written
-keepgenerated	Allows you to keep the source of generated proxy classes and bytecode when you run the WebLogic RMI compiler.
-loadAlgorithm <algorithm>	Only for use in conjunction with -clusterable. Specifies a service specific algorithm to use for load-balancing and fail-over (Default = weblogic.cluster.loadAlgorithm). Must be one of the following: round-robin, random, or weight-based.
-methodsAreIdempotent	Only for use in conduction with -clusterable. Indicates that the methods on this class are idem potent. This allows the proxy to attempt recovery form any communication failure, even if it can not ensure that failure occurred before the remote method was invoked. By default (if this option is not used) the proxy only retries on failures that are guaranteed to have occurred before the remote method was invoked.
-nomanglednames	Causes the compiler to produce proxies specific to the remote class.
-replicaListRefreshInterval <seconds>	Only for use in conjunction with -clusterable. Specifies the minimum time to wait between attempts to refresh the replica list from the cluster (Default = 180 seconds).
-stickToFirstServer	Only for use in conjunction with -clusterable. Enables "sticky" load balancing. The server chosen for servicing the first request is used for all subsequent requests.
-version	Prints version information

Replicating Stubs in a Cluster

You can also generate stubs that are not replicated in the cluster; these are known as "pinned" services, because after they are registered they will be available only from the host with which they are registered and will not provide transparent fail-over or load balancing.

If you use weblogic.rmic to compile an RMI object using the clustering option and then deploy the object on two nodes (A and B) of a three node server cluster A, B, and C) with replicating binding on all three nodes you get the same view from each server. When you do a JNDI lookup on all three nodes, you get the same stub and when you make method calls, the server performs load balancing between the first two nodes

Therefore, if you compile RMI objects with the clusterable option and bind them to a JNDI tree with replicate bindings set to false, when you do a JNDI lookup you get the following results:

On Server A, you get a stub that points to Sever A
On Server B, you get a stub that points to Server B
On Server C, you get a NameNotFoundException

If you make a remote call to Server A fails and it fails because the server is no longer available, the clusterable stub does a re-lookup and depending on where the call is routed, one of the following can occur:

On Server B, you get a stub that points to Server B
On Server C, you get a NameNotFoundException

If your RMI object is non-clusterable and you bind it to a JNDI tree with replicate bindings set to false, when you do a JNDI lookup you get pinned stubs and there is no failover. 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 fail-over to another server.

If your RMI object is non-clusterable and you bind it to a JNDI tree with replicate bindings set to true, this will fail because the object is non-clusterable and only one server can provide a non-clusterable service in a cluster.

Additional WebLogic RMI Compiler Features

Other features of the WebLogic RMI compiler include:

Signatures of remote methods do not need to throw RemoteException.
Remote exceptions can be mapped to RuntimeException.
Remote classes can also implement non-remote interfaces.

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, dynamic proxies are

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.

Using the WebLogic RMI Compiler with Proxies

The default behavior of the WebLogic RMI compiler is to produce proxies for the remote interface and for the remote classes to share the proxies. A proxy is a class used by the clients of a remote object. In the case of RMI, dynamically generated bytecode and proxy classes are used.

For example, example.hello.HelloImpl and counter.example.CiaoImpl are represented by a single proxy class and bytecode—the proxy that matches the remote interface implemented by the remote object, in this case, example.hello.Hello.

When a remote object implements more than one interface, the proxy names and packages are determined by encoding the set of interfaces. You can override this default behavior with the WebLogic RMI compiler option -nomanglednames, which causes the compiler to produce proxies specific to the remote class. When a class-specific proxy is found, it takes precedence over the interface-specific proxy.

In addition, with WebLogic RMI proxy classes, the proxies are not final. References to collocated remote objects are references to the objects themselves, not to the proxies.

Hot Code Generation

When you run rmic, you use WebLogic Server's hot code generation feature to automatically generate bytecode in memory for server classes. This bytecode is generated on the fly as needed for the remote object. WebLogic Server no longer generates the skeleton class for the object when weblogic.rmic is run.

RMI and T3 Protocol

RMI communications in WebLogic Server use the T3 protocol, an optimized protocol used to transport data between WebLogic Server and other Java programs, including clients and other WebLogic Servers. A server instance keeps track of each Java Virtual Machine (JVM) with which it connects, and creates a single T3 connection to carry all traffic for a JVM.

For example, if a Java client accesses an enterprise bean and a JDBC connection pool on WebLogic Server, a single network connection is established between the WebLogic Server JVM and the client JVM. The EJB and JDBC services can be written as if they had sole use of a dedicated network connection because the T3 protocol invisibly multiplexes packets on the single connection.

Any two Java programs with a valid T3 connection—such as two server instances, or a server instance and a Java client—use periodic point-to-point "heartbeats" to announce and determine continued availability. Each end point periodically issues a heartbeat to the peer, and similarly, determines that the peer is still available based on continued receipt of heartbeats from the peer.

The frequency with which a server instance issues heartbeats is determined by the heartbeat interval, which by default is 60 seconds.

The number of missed heartbeats from a peer that a server instance waits before deciding the peer is unavailable is determined by the heartbeat period, which by default, is 4.

Hence, each server instance waits up to 240 seconds, or 4 minutes, with no messages—either heartbeats or other communication—from a peer before deciding that the peer is unreachable.

Changing timeout defaults is not recommended.