|
|
|
|
| |
Programming WebLogic RMI
The following sections describe the WebLogic RMI features used to program RMI for use with WebLogic Server.
Run the WebLogic RMI compiler (rmic) by executing the weblogic.rmic class on the Java class file you want to execute via RMI. The compiler produces a stub and skeleton.
The stub class is the serializable class that is passed to the client. The skeleton is a server-side class that processes requests from the stub on the client. The implementation for the class is bound to a name in the RMI registry in the WebLogic Server.
A client acquires the stub for the class by looking up the class in the registry. WebLogic Server serializes the stub and sends it to the client. The client calls methods on the stub just as if it were a local class and the stub serializes the requests and sends them to the skeleton on the WebLogic Server. The skeleton deserializes client requests and executes them against the implementation classes, serializing results and sending them back to the stub on the client.
With the WebLogic RMI compiler, you can specify that more platform-specific compilers should be used. By default, weblogic.rmic invokes the compiler from the JDK distribution, javac, but you may call any compiler with the -compiler option to weblogic.rmic, as shown in this example which calls the Symantec Java compiler:
$ java weblogic.rmic -compiler \Cafe\bin\sj.exe
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 command above. All other options supported by the compiler can be used, and are passed directly to the Java compiler. The following options for java weblogic.rmic are available for you to use, and should be entered in one line, after java weblogic.rmic and before the name of the remote class.
|
-help |
Prints a description of the options |
|
-version |
Prints version information |
|
-d <dir> |
Target (top-level) directory for complation |
|
-verbosemethods |
Instruments proxies to print debug info for std err |
|
-descriptor |
Associates or creates a descriptor for each remote class |
|
-nomanglednames |
Does not mangle the names of stubs and skeletons |
|
-idl |
Generates IDLs for remote interfaces |
|
-idlOverwrite |
Overwrites existing IDL files |
|
-idlVerbose |
Displays verbose information for IDL information |
|
-idlStrict |
Generate IDL according to OMG standard |
|
-idlNoFactories |
Do not generate factory methods for valuetypes |
|
-idlDirectory <idlDirectory> |
Specifies the directory where IDL files will be created (Default = current directory) |
|
-clusterable |
Marks the service as clusterable (can be hosted by multiple servers in a WebLogic 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 failover (Default = weblogic.cluster.loadAlgorithm). Must be one of the following: round-robin, random, or weight-based. |
|
-callRouter <callRouterClass> |
Only for use in conjunction with -clusterable. Specifies the class to be used for routing method calls. This class must implement weblogic.rmi.extensions.CallRouter. If specified, an instance of the class will be called before each method call and be given the opportunity to choose a server to route to based on the method parameters. It either returns a server name or null--indicating that the current load algorithm should be used. |
|
-stickToFirstServer |
Only for use in conjunction with -clusterable. Enables 'sticky' load balancing. The server chosen for servicing the first request will be used for all subsequent requests. |
|
-methodsAreIdempotent |
Only for use in conjuction with -clusterable. Indicates that the methods on this class are idempotent. This allows the stub to attempt recovery form any communication failure, even if it can not ensure that failure occurred before the remote methode was invoked. By default (if this option is not used) the stub will only retry on failures that are guaranteed to have occured before the remote method was invoked. |
|
-replicaListRefreshInterval <seconds> |
Only for use in conjunction with -clusterable. Specifies the minimum time to wait between attempts to refresh the replica list from the cluster (Default = 180 seconds). |
|
-iiop |
Generate IIOP stubs from servers |
|
-iiopDirectory |
Directory where IIOP proxy classes are written |
|
-keepgenerated |
Keeps the generated .java files |
|
-commentary |
Emits commentary |
|
-compiler <compiler> |
Specifies the java compiler (Default = javac) |
|
-comilerclass <null> |
Loads the compiler as a class instead of an executable |
|
-g |
Compiles debugging information into a class file |
|
-O |
Compiles with optimization enabled |
|
-debug |
Compiles with debugging enabled |
|
-nowarn |
Compiles without warnings |
|
-verbose |
Compiles with verbose output |
|
-nowrite |
Does not generate .class files |
|
-deprecation |
Warns of deprecated calls |
|
-normi |
Passes through to Symantec's sj |
|
-J <option> |
Flags passed through to java runtime |
|
-classpath <path> |
Classpath to use during compilation |
Additional WebLogic RMI Compiler Features
Other features of the WebLogic RMI compiler include:
A proxy is a class used by the clients of a remote object, in the case of RMI, a skeleton and a stub. The stub class is the instance that is invoked upon in the client's Java Virtual Machine (JVM); the stub marshals the invoked method name and its arguments, forwards these to the remote JVM, and -- after the remote invocation is completed and returns -- unmarshals the results on the client. The skeleton class, which exists in the remote JVM, unmarshals 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.
In the JavaSoft RMI reference implementation, there is a one-to-one correspondence between the proxy classes and the remote objects. For example, running the JavaSoft RMI compiler against example.hello.HelloImpl -- which implements the remote class example.hello.Hello -- will produce two classes, example.hello.HelloImpl_Skel and example.hello.HelloImpl_Stub. If another class -- for example, counter.example.CiaoImpl also implements the same remote interface (example.hello.Hello), a virtually identical pair of proxy classes will be produced with the JavaSoft RMI compiler (counter.example.CiaoImpl_Skel and counter.example.CiaoImpl_Stub).
Using the WebLogic RMI Compiler with Proxies
The WebLogic RMI compiler works differently. 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. For example, example.hello.HelloImpl and counter.example.CiaoImpl are represented by a single stub and skeleton, 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 will cause 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 stubs are not final. References to colocated remote objects are references to the objects themselves, not to the stubs.
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, since 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.
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. Here are notes on particular implementations that may be of interest:
rmi.Naming is implemented as a final class in WebLogic RMI with all public methods supported by JNDI, which is the preferred mechanism for naming objects in WebLogic RMI.
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, but a call to LocateRegistry.createRegistry(int port) will not create a colocated registry, but rather will attempt 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 the 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:
Note: LocateRegistry.getRegistry(https://localhost:7002);
Note: which will locate 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 superclass 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 scenerio, 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, since WebLogic RMI depends on the more general security model within WebLogic Server. If, however, you do set a SecurityManager, you can set only one. Before setting a SecurityManager, 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)
System.setSecurityManager(new RMISecurityManager());
The following classes are implemented but unused in WebLogic RMI:
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|