Programming WebLogic RMI

Using the WebLogic RMI Compiler

The following sections describe the WebLogic RMI compiler:

Overview of the 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.

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.

WebLogic RMI Compiler Features

The following sections provide information on WebLogic RMI Compiler features for this release:

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.

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.

Proxy Generation

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.

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.

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.

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.

$java weblogic.rmic [options] <classes>...

Table 4-1 WebLogic RMI Compiler Options

Option	Description
`-help`	Prints a description of the options.
`-version`	Prints version information.
`-d <dir>`	Specifies the target (top level) directory for compilation.
`-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.
`-oneway`	Specifies all calls are one-way calls.
`-idl`	Generates IDLs for remote interfaces.
`-idlOverwrite`	Overwrites existing IDL files.
`-idlVerbose`	Displays verbose information for IDL information.
`-idlDirectory <idlDirectory>`	Specifies the directory where IDL files will be created (Default = current directory).
`-idlFactories`	Generates factory methods for valuetypes.
`-idlNoValueTypes`	Prevents the generation of valuetypes and the methods/attributes that contain them.
`-idlNoAbstractInterfaces`	Prevents the generation of abstract interfaces and the methods/attributes that contain them.
`-idlStrict`	Generates IDL according to OMG standard.
`-idlVisibroker`	Generate IDL compatible with Visibroker 4.5 C++.
`-idlOrbix`	Generate IDL compatible with Orbix 2000 2.0 C++.
`-iiopTie`	Generate CORBA skeletons using Sun's version of `rmic`.
`-iiopSun`	Generate CORBA stubs using Sun's version of `rmic`.
`-nontransactional`	Suspends the transaction before making the RMI call and resumes after the call completes.
`-compiler <javac>`	Specifies the Java compiler. If not specified, the `-compilerclass` option will be used.
-compilerclass <com.sun.tools.javac.Main>	Compiler class to invoke.
`-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.
`-timeout`	Used in conjunction with remote-client-timeout.
`-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.
-g	Compile debugging information into the class.
-O	Compile with optimization.
-nowarn	Compile without warnings.
-verbose	Compile with verbose output.
-verboseJavac	Enable Java compiler verbose output.
-nowrite	Prevent the generation of `.class` files.
-deprecation	Provides warnings for deprecated calls.
-classpath <path>	Specifies the classpath to use.
-J<option>	Use to pass flags through to the Java runtime.
`-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 Stub Generation

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.

Using Persistent Compiler Options

During deployment, appc and ejbc run each EJB container class through the RMI compiler to create RMI descriptors necessary to dynamically generate stubs and skeletons. Use the weblogic-ejb-jar.xml file to persist iiop-security-descriptor elements. For more information, see 2.0 weblogic-ejb-jar.xml Elements in Programming WebLogic Enterprise JavaBeans.

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