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

 

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 = 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.
-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 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.1 weblogic-ejb-jar.xml Elements” in Programming WebLogic Enterprise JavaBeans.