Using the WebLogic RMI Compiler

4 Using the WebLogic RMI Compiler

This chapter describes how to use the features and options of the WebLogic RMI compiler.

This chapter includes the following sections:

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 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 JNDI tree 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 JNDI. 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.
`-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 is the 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 is 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.
`-iiop`	Generates IIOP stubs from servers.
`-iiopDirectory`	Specifies the directory where IIOP proxy classes are written.
`-timeout`	Used in conjunction with remote-client-timeout .
`-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. See weblogic-ejb-jar.xml Elements in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.

Java SE Enhancements

You can find additional information on Java SE enhancements for Java RMI at http://docs.oracle.com/javase/8/docs/technotes/guides/rmi/.