WebLogic RMI Features and Guidelines

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

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.

The WebLogic RMI compiler (weblogic.rmic) is a command-line utility for generating and compiling remote objects. Use weblogic.rmic to generate dynamic proxies on the client-side for custom remote object interfaces in your application and provide hot code generation for server-side objects.

The dynamic proxy class is the serializable class that is passed to the client. A client acquires the proxy for the class by looking up the class in the WebLogic RMI 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.

Hot code generation produces the bytecode for a server-side class that processes requests from the dynamic proxy on the client. 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. The implementation for the class is bound to a name in the WebLogic RMI registry in WebLogic Server.

When you run weblogic.rmic, automatically creates the proxy classes and the hot code generation feature generates the bytecode that is dynamically created at runtime, when the RMI object is deployed. See Step 4. Compile the Implementation Class with RMI Compiler for instructions on using weblogic.rmic. to See WebLogic RMI Compiler Options for a list of the weblogic.rmic command-line options.

Note: You only need to explicitly run weblogic.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.

In previous versions of WebLogic Server, pre 6.1, running weblogic.rmic generated stubs on the client and skeleton code on the server-side. Now, dynamic proxies have replace generated stubs on the client-side and bytecode has replaced skeletons on the server-side. 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 weblogic.rmic on those objects. This will generate the necessary proxies and bytecode that enable the deployed RMI object. See Dynamic Proxies in RMI, for more information on dynamic proxies.

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.

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 table lists 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
-help	Prints a description of the options.
-version	Prints version information.
-dispatchPolicy <queueName>	Specifies a configured execute queue that the service should use to obtain execute threads in WebLogic Server. See Using Execute Queues to Control Thread Usage for more information.
-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).
-clusterable	This cluster-specific options marks the service as clusterable (can be hosted by multiple servers in a WebLogic Server cluster). Each hosting object, or replica, is bound into the naming service under a common name. When the service stub 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.
-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.
-callRouter <callRouterClass>	This cluster-specific option used 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 means that you use the current load algorithm.
-stickToFirstServer	This cluster-specific option used in conjunction with -clusterable enables "sticky" load balancing. The server chosen for servicing the first request is used for all subsequent requests.
-methodsAreIdempotent	This cluster-specific option used in conjunction with -clusterable indicates that the methods on this class are idempotent. This allows the stub to attempt recovery from 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 stub only retries on failures that are guaranteed to have occurred before the remote method was invoked.
-replicaListRefreshInterval <seconds>	This cluster-specific option used in conjunction with -clusterable specifies the minimum time to wait between attempts to refresh the replica list from the cluster (Default = 180 seconds).
-iiop	Generates IIOP stubs from servers.
-iiopDirectory	Specifies the directory where IIOP proxy classes are written.
-commentary	Emits commentary.
-nomanglednames	Causes the compiler to produce proxies specific to the remote class.
-keepgenerated	Allows you to keep the source of generated stub and skeleton class files when you run the WebLogic RMI compiler.
-disableHotCodeGen	Causes the compiler to create stubs at skeleton classes when compiled.

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.

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—unmarshals 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.

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.

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 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.