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 Framework

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

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.

 

Migrating from Stubs and Skeletons to Dynamic Proxies and Bytecode

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 "ejbc" in Programming WebLogic Enterprise JavaBeans for instructions on using weblogic.ejbc.

Rerunning either weblogic.rmic with 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 table lists java weblogic.rmic options. Enter these options after java weblogic.rmic and before the name of the remote class.

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.


 

Non-Replicated Stubs in a Cluster

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.

 

Additional WebLogic RMI Compiler Features

Other features of the WebLogic RMI compiler include the following:

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

 

WebLogic RMI Registry

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.

 

WebLogic RMI Implementation Features

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.

 

JNDI

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

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

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: 

LocateRegistry.getRegistry(https://localhost:7002);

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

 

rmi.server Classes

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.

 

setSecurityManager

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: 

 if (System.getSecurityManager() == null)

 

Unused Classes

System.setSecurityManager(new RMISecurityManager());

The following classes are implemented but unused in WebLogic RMI:

 

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.

Skip navigation bar  Back to Top Previous Next