CAROL Library User Manual: CAROL (Common Architecture for RMI ObjectWeb Layer), a RMI manager | ||
---|---|---|
Prev | Chapter 2. CAROL overview | Next |
CAROL is behind the standard RMI IIOP and JNDI API. A Java server using CAROL have to be a standard RMI IIOP server and use only the JNDI interfaces for name service connections (see the section RMI IIOP Development rules and the JNDI Development rules section). A standard RMI IIOP server is required to migrate to the CAROL library without any code modification. Using CAROL library, in this case, is only a configuration manipulation. CAROL simulates a standard RMI IIOP PortableRemoteObjectDelegate and a standard JNDI context factory for interceptions and manipulations of the RPC and naming mechanism. CAROL allows any RMI IIOP remote object to be manipulate by a server on different RMI architectures and different naming services, in the same time, without code modification on the server or on the client side.
CAROL uses the standard RMI IIOP PortableRemoteObject to abstract the export mechanism. The figure 2.1 shows that the server only manipulate remote object via the RMI IIOP PortableRemoteObject and this PortableRemoteObject is a delegation to a "configured by system properties" PortableRemoteObjectDelegate class.
In fact, the CAROL remote object API is the standard RMI IIOP API. A Java server using CAROL is supposed to use only the java.rmi.* and the javax.rmi.* classes and never to call directly the CAROL library classes.
The same mechanism is used for objects registering through JNDI: a CAROL server is supposed to use only the JNDI interface to manipulate and contact the remote object name service. So, with JNDI, a CAROL server use the InitialContext mechanism, for (un)registering object, and this InitialContext delegate the registering to a context object build by a factory "configured by system properties". In the figure 2.2 we can see that the server only manipulates remote object registered via the JNDI InitialContext API.
This section describes the basic rules of RMI IIOP development. For more information, see the Sun entry for RMI IIOP Documentation. This RMI IIOP quick start guide is design for a 3 step development:
Development of the RMI IIOP remote objects and development of the RMI server part
Java and CAROL RMI IIOP objects compilation
Deployment step in a distributed environment
A RMI IIOP remote object needs only to expose its remote methods in a Java interface extending Remote. This is exactly the same development rules than in classical RMI JRMP. In the example 2-1, the remote object Foo exposes its remote method myMethod() in the remote interface FooRemoteInterface.
Example 2-1. RMI basic example
//The foo object is a remote object import java.rmi.RemoteException; //The class foo implements only //the FooRemoteInterface interface public class Foo implement FooRemoteInterface { //This method is remote public Integer myMethod() throws RemoteException{ return new Integer(0); } }
//The foo remote interface //extends only the Remote interface //and exposes the remote methods import java.rmi.Remote; import java.rmi.RemoteException; public interface FooRemoteInterface extends Remote { //This method is remote public Integer myMethod() throws RemoteException; }
![]() | The method myMethod() throws a RemoteException if an exceptions occurs in the remote method call. |
The RMI IIOP server has to manage remote objects. This section only describes the (un)export management of a RMI IIOP remote object. Please see the JNDI development rules section for the remote object (un)registering managment. One of the most important step in a remote object life cycle is the export step (and the opposite unexport step). To Exporte a remote object means to prepare this object to receive remote call. RMI IIOP abstracts the intricate CORBA implementation mechanism of this export with the API class PortableRemoteObject. To Export a remote object is mandatory for remote call. There is two way for this export:
The implicit method: if the remote object class implements the PortableRemoteObject class, this remote object is automatically export in is creation time. In the example 2-2 the remote object is implicitly exported by inheritance. In this case, the server only needs to construct the remote object to exported it.
Example 2-2. RMI implicit export
//The foo object is a remote object import java.rmi.RemoteException; import javax.rmi.PortableRemoteObject; //The class foo extends PortableRemoteObject //and implements the FooRemoteInterface interface public class Foo extends PortableRemoteObject implements FooRemoteInterface { //The constructor public Foo() throws RemoteException { super(); } //This method is remote public Integer myMethod() throws RemoteException { return new Integer(0); } }
//The foo remote object server import java.rmi.RemoteException; import org.objectweb.carol.util.configuration.CarolConfiguration; public class Server { //The main method of this server public static void main(String [] args) { try { //initialize carol CarolConfiguration.init(); FooRemoteInterface myFoo = new Foo(); // the object is automatically // exported on RMI IIOP } catch (RemoteException e) { //Foo construction problem } } }
The explicit method: if the remote object class do not implement the PortableRemoteObject class, this remote object has to be explicitly exported by the server. The public static void exportObject(java.rmi.Remote) method in PortableRemoteObject class allow to do that. In the example 2-3 the remote object is explicitly exported by the server.
Example 2-3. RMI explicit export
//The foo object is a remote object import java.rmi.RemoteException; //The class foo implements //only the FooRemoteInterface interface public class Foo implement FooRemoteInterface { //The constructor public Foo() throws RemoteException { super(); } //This method is remote public Integer myMethod() throws RemoteException { return new Integer(0); } }
//The foo remote object server import java.rmi.RemoteException; import javax.rmi.PortableRemoteObject; import org.objectweb.carol.util.configuration.CarolConfiguration; public class Server { //The main method of this server public static void main(String [] args) { try { //initialize carol CarolConfiguration.init(); FooRemoteInterface myFoo = new Foo(); //The object is explicitly exported on RMI IIOP: PortableRemoteObject.exportObject(myFoo); } catch (RemoteException e) { //Foo construction problem } } }
The compilation step is designed by Java and RMI. There is no particular compilation step in order to use CAROL. Therefore, you need to compile Java classes and to compile stubs and skeletons with each RMI provider compiler for each RMI architecture (IIOP, JRMP, JEREMIE ...).
The 3 points below are mandatory for CAROL server deploying on multi-RMI architecture:
There is 2 ways for carol initialization: first, the best way, is to call the org.objectweb.carol.util.configuration.CarolConfiguration.init() method. The second way is to set the 2 system property javax.rmi.CORBA.PortableRemoteObjectClass =org.objectweb.carol.rmi.multi.MultiPRODelegate and java.naming.factory.initial =org.objectweb.carol.jndi.spi.MultiOrbInitialContextFactory in the server JVM. This second method doesn't allows to switch off carol features by configuration: The properties carol.start.rmi=false and carol.start.jndi=false doesn't work with this configuration method.
The carol.properties file can be configured (see the CAROL Configuration chapter) and visible in the JVM classpath.
For each RMI architecture all remote objects stub and skeleton have to be visible in the classpath.
![]() | For the moment, in CAROL library, there is 3 remote architectures available (CAROL SPI implementation): IIOP, JRMP and JEREMIE. There is no, in those 3 architectures, stub/skeleton class conflicts. For example, if my remote object is Foo with FooItf remote interface:
|
![]() | But, be careful, there is stubs and/or skeletons class name conflicts for different providers of the same RMI architecture. For example, this is not possible, with CAROL, to deploy a remote object on two RMI provider with the same architecture (for example RMI JRMP 1.1 and RMI JRMP 1.2 or DAVID RMI IIOP and SUN JDK 1.4 RMI IIOP) because there are a stubs and/or skeletons class name conflicts in the server JVM. |
This section describes the basic JNDI development rules. For more information, see the Sun entry for JNDI Documentation. This JNDI start guide is designed for a 2 steps development:
Development of the JNDI server part
JNDI deployment step on a distributed environment
For remote object access with CAROL, the first part is to develop and deploy RMI IIOP remote objects (see the RMI IIOP Development rules chapter) on a Java server. The second part is to register those objects in one/many name service through the standard JNDI Interface. For this, the server needs to build a InitialContext object and to register all remote objects in this context like in the Example 2-4:
Example 2-4. JNDI basic example
//The foo remote object server import java.rmi.RemoteException; import javax.naming.InitialContext; import javax.naming.NamingException; import org.objectweb.carol.util.configuration.CarolConfiguration; public class Server { //The main method of this server public static void main(String [] args) { try { //initialize carol CarolConfiguration.init(); // the object is automatically // exported on RMI IIOP FooRemoteInterface myFoo = new Foo(); // now the server bind this object trough JNDI // with the name myobjectname InitialContext ic = new InitialContext(); ic.rebind("myobjectname", myFoo) } catch (RemoteException e) { //Foo construction problem }catch (NamingException ne) { //Foo binding problem } } }
![]() | In this example, the server use a default IntialContext without configuration. You may want to configure your server JNDI for each name service (registry, cosnaming ...). Please use only the CAROL configuration to setup your multi JNDI name service. For this feature, a Java server, needs the CAROL JNDI context factory (see the CAROL Configuration chapter). |
The 3 points below are mandatory for CAROL server deploying on multi name service architecture:
The system property java.naming.factory.initial need to be instantiated to org.objectweb.carol.jndi.spi.MultiOrbInitialContextFactory in the server JVM.
The carol.properties and the jndi.properties files need to be configured (see the CAROL Configuration chapter) and visible in the server JVM classpath.
Each name service (registry, cosnaming, ...) can be launched in the distribute environment.
![]() | Be careful, the InitialContext need to be configured for CAROL with the system property java.naming.factory.initial instantiated to org.objectweb.carol.jndi.spi.MultiOrbInitialContextFactory. Every other properties configured directly in the server InitialContext will be lost. The important point is to understand that the IntialContext is an indirection to an other context, the CAROL one, which manage all the contexts for each name service. |