The BEA WebLogic Enterprise RMI API

 

There are several packages shipped as part of BEA WebLogic Enterprise RMI on IIOP. The public application programming interface (API) includes the BEA WebLogic Enterprise implementation of the Java RMI base classes and, for compatibility, the equivalent WebLogic Server (WLS) packages (weblogic.rmi). The BEA WebLogic Enterprise implementation also includes the WebLogic RMI code generator (weblogic.rmic).

Writing an application that uses remote method invocation (RMI) is essentially characterized by using the RMI API.

This topic includes the following sections:

• Overview of BEA WebLogic Enterprise RMI Packages

• Other Java Packages Related to BEA WebLogic Enterprise RMI

• What Is Different in BEA WebLogic Enterprise RMI API?

For detailed API reference information on the packages described in this topic, see the the BEA WebLogic Enterprise API Javadoc page in the BEA WebLogic Enterprise online documentation.

 

---

Overview of BEA WebLogic Enterprise RMI Packages

You can use either the Sun Microsystems, Inc. JavaSoft RMI related packages and classes or the BEA WebLogic RMI packages and classes to create BEA WebLogic Enterprise RMI applications. For compatibility with BEA WebLogic Server (WLS), the java.rmi classes are also implemented as weblogic.rmi classes.

Table 7-1 shows the Sun JavaSoft and BEA WebLogic packages that make up the BEA WebLogic Enterprise RMI API. The packages shown are generally supported in BEA WebLogic Enterprise but with some differences which are summarized in the table. Details on how BEA WebLogic Enterprise RMI differs from Sun JavaSoft RMI are provided in the section What Is Different in BEA WebLogic Enterprise RMI API?. Please be sure to read this section.

Table 7-1 BEA WebLogic Enterprise RMI Java Packages

Package	Description	Summary of Differences
java.rmi	The java.rmi package and the weblogic.rmi.package include the interface java.rmi.Remote which is the basic building block for all remote objects. java.rmi.Remote contains no methods-it simply functions as a "tag" to identify remote classes. You must extend this tagging interface to create your own remote interface, with method stubs that create a structure for your remote object. Then you implement your own remote interface with a remote class. Your implementation needs to be bound to a name in the Java Naming and Directory Interface (JNDI), from where a client or server may look up the object and use it remotely. (For more about using the JNDI API, see javax.naming.) The java.rmi package also includes several exception classes that extend java.rmi.RemoteException. You should code to catch these RMI exceptions in your BEA WebLogic Enterprise applications. Methods on remote objects should throw java.rmi.RemoteException. For details on how the BEA WebLogic Enterprise RMI API differs from the Sun JavaSoft implementation, see the topic What Is Different in BEA WebLogic Enterprise RMI API?	Some rmi classes are not effective for use in BEA WebLogic Enterprise. For details, see API Differences.
javax.rmi	The javax.rmi package includes one class called javax.rmi.PortableRemoteObject. The method narrow method on this class can be used in combination with the WLE implementations of JNDI and RMI. All other functions in the PortableRemoteObject throw UnsupportedOperationException in WLE. Server implementation objects may either inherit from javax.rmi.PortableRemoteObject or they may implement a remote interface and then use the exportObject method to register themselves as a server object. Optionally, you can use PortableRemoteObject.narrow in BEA WebLogic Enterprise RMI applications to perform type-narrowing, instead of a cast operator. Use of narrow is strongly recommended. A client program that is intended to be interoperable with all compliant EJB container implementations must use the method PortableRemoteObject.narrow to perform type-narrowing of the client-side representations of the home and remote interface.	None
com.beasys.rmi	Starts up classes described by properties in a way compatible with BEA WebLogic Server.	Not applicable.

 

---

Other Java Packages Related to BEA WebLogic Enterprise RMI

Table 7-2 shows other J2EE packages that provide additional functionality needed to create BEA WebLogic Enterprise RMI classes.

Table 7-2 Other Java Packages Related to BEA WebLogic Enterprise RMI

Package	Description	Summary of Differences
javax.naming	Provides the classes and interfaces for accessing naming services. In BEA WebLogic Enterprise, the recommended connection bootstrap is to create an InitialContext. It is created with a hash table of parameters. Some of these affect the RMI implementation.	BEA WebLogic Enterprise supports keys from both javax.naming.Context, and from weblogic.jndi.WLContext. For details, see the topic Connection Bootstrapping and Security Differences.
javax.transaction	Contains three exceptions thrown by the ORB machinery during unmarshalling.	None
java.sql	Provides the classes and interfaces for accessing databases via Standard Query Language (SQL).	None
javax.sql	The javax.sql API is used for bean managed persistence in EJB 1.1. Explicit access to a database starts by looking up a javax.sql.DataSource.	None

 

---

What Is Different in BEA WebLogic Enterprise RMI API?

The BEA WebLogic Enterprise RMI API is a subset of the Java Development Kit 2 RMI API. As such, it supports most aspects of the Java Enterprise Edition (J2EE) including use of Java Naming and Directory Interface (JNDI) and transactions services which are needed to interact with EJBs. In BEA WebLogic Enterprise, RMI is hosted on IIOP which means firewalls configured to support IIOP traffic will accept WebLogic RMI on IIOP messages as standard IIOP messages.

BEA WebLogic Enterprise RMI supports use of RMI classes in java.rmi, but you need to be aware of the specific implementation of these packages in the BEA WebLogic Enterprise RMI development environment. BEA WebLogic Enterprise RMI differs from the Sun JavaSoft RMI implementation. Keep these differences in mind when you are:

• Creating new RMI applications in BEA WebLogic Enterprise especially if you have previous experience with the BEA WebLogic Server or the JavaSoft RMI classes.

• Converting existing RMI classes from Sun JavaSoft RMI classes. (For step-by-step instructions on how to convert existing RMI classes to BEA WebLogic Enterprise classes, refer to Converting Sun JavaSoft RMI to BEA WebLogic Enterprise RMI Classes.)

The differences are summarized in the following sections:

• API Differences

• Connection Bootstrapping and Security Differences

• Tool Differences

• Configuration Differences

API Differences

Table 7-3 lists the differences when using WLE RMI on IIOP.

Table 7-3 BEA WebLogic Enterprise RMI API Differences

Sun JavaSoft RMI Classes	BEA WebLogic Enterprise RMI on IIOP
Naming, Connecting, and Bootstrapping
java.rmi.Naming	Use of rmi.Naming is not effective for use in BEA WebLogic Enterprise. For developing BEA WebLogic Enterprise RMI applications, use Java Naming and Directory Interface (JNDI) javax.naming instead of the RMI registry. java.rmi.Naming classes relate to the Sun JavaSoft implementation of the RMI registry. BEA WebLogic Enterprise provides no equivalent. java.rmi.Naming classes will actually compile and may run in BEA WebLogic Enterprise, but will produce errors and undesired results.
java.rmi.registry.LocateRegistry	Use of RMI registry related classes is not effective in BEA WebLogic Enterprise. For developing BEA WebLogic Enterprise RMI applications, use JNDI javax.naming instead. Registry classes relate to the Sun Microsystems JavaSoft implementation of the RMI registry. BEA WebLogic Enterprise provides no equivalent. java.rmi.registry classes will actually compile and may run in BEA WebLogic Enterprise, but will produce errors and undesired results.
Security
java.rmi.RMISecurityManager java.rmi.server.RMISocketFactory java.rmi.server.RMIClassLoader java.rmi.server.UnicastRemoteObject LoaderHandler, Operation, RemoteCall, RemoteRef, RemoteStub, Skeleton from java.rmi.server (deprecated in 1.2 without replacement)	Use of the RMI class RMISecurityManager is not effective in BEA WebLogic Enterprise. For developing BEA WebLogic Enterprise RMI applications, use JNDI to specify security instead. RMISecurityManager classes will actually compile and may run in BEA WebLogic Enterprise, but will produce errors and undesired results.
java.rmi.RemoteServer
Static method getClientHost in java.rmi.server.RemoteServer	Use of rmi.server classes is not effective in BEA WebLogic Enterprise. java.rmi.server classes will actually compile and may run in BEA WebLogic Enterprise, but will produce errors and undesired results.
getLog and setLog in java.rmi.server.RemoteServer	Use of rmi.server classes is not effective in BEA WebLogic Enterprise. java.rmi.server classes will actually compile and may run in BEA WebLogic Enterprise, but will produce errors and undesired results.
Stubs and Skeletons
java.rmi.RemoteObject java.rmi.server.RemoteStub	Use of rmi.RemoteObject is not effective in BEA WebLogic Enterprise. java.rmi.RemoteObject classes will actually compile and may run in BEA WebLogic Enterprise, but will produce errors and undesired results.
SkeletonMismatchException and SkeletonNotFoundException in java.rmi.server (deprecated in JDK 1.2)	These exception classes from java.rmi.server will compile and run in BEA WebLogic Enterprise. These classes are not actually used by BEA WebLogic Enterprise. BEA WebLogic Enterprise uses reflection instead of skeletons.
Others
java.rmi.dgc.Lease and VMID (not usable)	Not supported in BEA WebLogic Enterprise.
java.rmi.server.LogStream (deprecated in JDK 1.2 without replacement)	Not supported in BEA WebLogic Enterprise.
java.rmi.server.ObjID (not usable)	Use of rmi.server classes is not effective in BEA WebLogic Enterprise. java.rmi.server classes that use ObjID might actually compile and run in BEA WebLogic Enterprise, but will produce errors and undesired results.

Connection Bootstrapping and Security Differences

In BEA WebLogic Enterprise RMI, connection bootstrapping is achieved by creating an InitialContext via the Java Naming and Directory Interface (JNDI) with javax.naming.

Optionally, the JNDI WLEContext.SECURITY_AUTHENTICATION property can be used for security. Also, the property keys shown in the section JNDI Property Keys for BEA Tuxedo Style Authentication can be used for BEA Tuxedo style authentication.

For more information about JNDI, see Using the SPI Implementation for JNDI in the BEA WebLogic Enterprise online documentation.

For more information about using JNDI for security, see the Writing a WLE Enterprise JavaBean that Implements Security chapter in Using Security in the BEA WebLogic Enterprise online documentation.

JNDI Environment Properties

All J2EE Java remote client applications must first create environment properties. The initial context factory uses the various properties to customize the InitialContext for a specific environment. You can set these properties by using a hash table. These properties, which are name-to-value pairs, determine how the WLEInitialContextFactory creates the WLEContext.

WLEContext.INITIAL_CONTEXT_FACTORY

Set this property to the WLE initial context factory "com.beasys.jndi.WLEInitialContextFactory" to access the BEA WebLogic Enterprise domain and remote naming services.

The class com.beasys.jndi.WLEInitialContextFactory provides the implementation for delegating JNDI methods to the BEA WebLogic Enterprise JNDI implementation. The com.beasys.jndi.WLEInitialContextFactory provides an entry point for a client into the WLE domain namespace. (See Listing 7-1 for an example.)

Listing 7-1 WLEContext.INITIAL_CONTEXT_FACTORY Property Example

---

Hashtable env = new Hashtable();
/* 
* Specify the initial context implementation to use.
* The service provider supplies the factory class.
*/
env.put(WLEContext.INITIAL_CONTEXT_FACTORY, 
        "com.beasys.jndi.WLEInitialContextFactory");
   .
   .
   .

---

WLEContext.PROVIDER_URL

Set the URL of the service provider with the property name java.naming.provider.url. This property value should specify an IIOP Listener/Handler for the desired BEA WebLogic Enterprise target domain. (See Listing 7-2 for an example.)

Listing 7-2 WLEContext.PROVIDER_URL Property Example

---

   .
   .
   .
env.put(WLEContext.PROVIDER_URL, 
       "corbaloc://myhost:1000");
   .
   .
   .

---

The host and port combination that is specified in the URL must match the ISL parameter in the WLE domain's UBBCONFIG file. The format of the host and port combination, as well as the capitalization, must match. If the addresses do not match, the communication with the WLE domain fails.

A WLE server that acts as a client must set the WLEContext.PROVIDER_URL property as an empty string or null. The server client connects to the current application in which it is booted.

WLEContext.SECURITY_AUTHENTICATION

The WLE system supports different levels of authentication. The SECURITY_AUTHENTICATION value determines whether certificate-based SSL authentication is attempted or BEA Tuxedo style authentication is used.

Valid values for this property key are "none", "simple", or "strong", as recommended by the Sun Microsystems Inc. JNDI specification. (See Listing 7-3 for an example.)

Listing 7-3 WLEContext.SECURITY_AUTHENTICATION Example

---

   .
   .
   .
env.put(WLEContext.SECURITY_AUTHENTICATION, 
        "strong");
.
.
.

---

If "none" is specified, then no authentication is attempted.

If "strong" is specified, then certificate-based authentication is attempted using SSL protocols.

If "simple" is specified or if SECURITY_AUTHENTICATION is not specified, then the BEA Tuxedo style authentication is used. See the next section for information about the WLE specific keys used to support BEA Tuxedo style authentication.

JNDI Property Keys for BEA Tuxedo Style Authentication

BEA WebLogic Enterprise supports use of the several keys from javax.naming.Context for security as shown in Table 7-4.

Table 7-4 WLE Property Keys for Security

Key	Description
WLEContext.SECURITY_PRINCIPAL	Specifies the identity of the principal used when authenticating the caller to the WLE domain.
WLEContext.SECURITY_CREDENTIALS	Specifies the credentials of the principal when authenticating the caller to the WLE domain. For certificate-based authentication enabled via SECURITY_AUTHENTICATION="strong", it specifies the pass phrase used to access the private key and certificate for the EJB. For password-based authentication enabled via SECURITY_AUTHENTICATION="simple", it specifies a string that is the user's password or an arbitrary object user_data used by the authentication server (AUTHSVR) to verify the credentials of the EJB.
WLEContext.CLIENT_NAME	Specifies the name of the EJB defined by the -c option of the tpusradd command.
WLEContext.SYSTEM_PASSWORD	The system password. Required only when using Username/Password authentication.

Listing 7-4 includes the WLE keys used to define Username/Password authentication.

Listing 7-4 WLE Keys for Username/Password Authentication

---

...
//Password-Based Authentication 
env.put(WLEContext.SECURITY_AUTHENTICATION, "simple");
env.put(WLEContext.SYSTEM_PASSWORD, "RMI");
env.put(WLEContext.SECURITY_PRINCIPAL, "sams");
env.put(WLEContext.CLIENT_NAME, "writers");
env.put(WLEContext.SECURITY_CREDENTIALS, "password");

---

Listing includes the WLE keys used to define certificate-based authentication.

Listing 7-5 WLE Keys for Certificate-Based Authentication

---

...
//Certificate-Based Authentication 
env.put(WLEContext.SECURITY_AUTHENTICATION, "strong");
env.put(WLEContext.SYSTEM_PASSWORD, "SSL");
env.put(WLEContext.SECURITY_PRINCIPAL, "sams");
env.put(WLEContext.SECURITY_CREDENTIALS, "credentials");
...

---

Tool Differences

Stubs and skeletons for BEA WebLogic Enterprise RMI applications are generated by running the WebLogic RMI compiler (weblogic.rmic) against the remote class. A stub is the client-side proxy for a remote object that forwards each BEA WebLogic Enterprise RMI call to its matching server-side skeleton, which in turn forwards the call to the actual remote object implementation.

BEA WebLogic Enterprise does not support java.rmi.Naming and, therefore, it has no rmiregistry tool. (Use of JNDI is supported instead.)

Configuration Differences

The only RMI configuration property used for BEA WebLogic Enterprise RMI is weblogic.system.startupClass.<virtualName> which is used to register the RMI implementation at startup time. An example of using a startup properties file is provided in Using a Startup Properties File.

The JavaSoft RMI specification defines several properties. None of these have any effect on the BEA WebLogic Enterprise RMI implementations.