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 compliling 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 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 1:

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.

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

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.

WebLogic Server hosts the RMI registry and provides server infrastructure for RMI clients. The overhead for RMI registry and server communications is minimal, because registry traffic is multiplexed over the same connection as JDBC and other kinds of traffic. Clients use a single socket for RMI; scaling for RMI clients is linear in the WebLogic Server environment.

The WebLogic RMI registry is created when WebLogic Server starts up, and calls to create new registries simply locate the existing registry. Objects that have been bound in the registry can be accessed with a variety of client protocols, including the standard rmi://, as well as http://, or https://. In fact, all of the naming services use JNDI.

In general, functional equivalents of all methods in the java.rmi package are provided in WebLogic RMI, except for those methods in the RMIClassLoader and the method java.rmi.server.RemoteServer.getClientHost().

All other interfaces, exceptions, and classes are supported in WebLogic RMI. The following sections note particular implementations that may be of interest.

Use Java Naming and Directory Interface (JNDI) as the preferred mechanism for naming objects in WebLogic RMI. The JNDI is an application programming interface (API) that provides naming services to Java applications. JNDI is an integral component of Sun Microsystems Inc.'s Java 2 Enterprise Edition (J2EE) technology. A naming service associates names with objects and finds objects based on their given names. (The RMI registry is an example of a naming service.)

Using JNDI with RMI allows you to make distributed programming more efficient. However, you should be aware of the number of round trips between remote client and the server. Repeated JNDI lookups between the client and server may cause performance problems

rmi.RMISecurityManager is implemented as a non-final class with all public methods in WebLogic RMI, and, unlike the restrictive JavaSoft reference implementation, is entirely permissive. Security in WebLogic RMI is an integrated part of the larger WebLogic environment, for which there is support for SSL (Secure Socket Layer) and ACLs (Access Control Lists).

rmi.registry.LocateRegistry is implemented as a final class with all public methods. However, a call to LocateRegistry.createRegistry(int port) does not create a collocated registry, but rather attempts to connect to the server-side instance that implements JNDI, for which host and port are designated by attributes. In WebLogic RMI, a call to this method allows the client to find the JNDI tree on WebLogic Server.

Note: You can use protocols other than the default (rmi) as well, and provide the scheme, host, and port as a URL, as shown here:

This example locates a WebLogic Server registry on the local host at port 7002, using a standard SSL protocol.

rmi.server.LogStream diverges from the JavaSoft reference implementation in that the write(byte[]) method logs messages through the WebLogic Server log file.

rmi.server.RemoteObject is implemented in WebLogic RMI to preserve the type equivalence of UnicastRemoteObject, but the functionality is provided by the WebLogic RMI base class Stub.

rmi.server.RemoteServer is implemented as the abstract super-class of rmi.server.UnicastRemoteObject and all public methods are supported in WebLogic RMI with the exception of getClientHost().

rmi.server.UnicastRemoteObject is implemented as the base class for remote objects, and all the methods in this class are implemented in terms of the WebLogic RMI base class Stub. This allows the stub to override non-final Object methods and equate these to the implementation without making any requirements on the implementation.

In WebLogic RMI, all method parameters are pass-by-value, unless the invoking object resides in the same Java Virtual Machine (JVM) as the RMI object. In this scenario, method parameters are pass-by-reference.

Note: WebLogic RMI does not support uploading classes from the client. In other words, any classes passed to a remote object must be available within the server's CLASSPATH.

The setSecurityManager() method is provided in WebLogic RMI for compilation compatibility only. No security is associated with it, because WebLogic RMI depends on the more general security model within WebLogic Server. If, however, you do set a security manager, you can set only one. Before setting a security manager, you should test to see if one has already been set; if you try to set another, your program will throw an exception. Here is an example: