Remote Objects

The Java Remote Method Invocation (RMI) system is a mechanism that enables an object on one Java virtual machine to invoke methods on an object in another Java virtual machine. Any object whose methods can be invoked in this way must implement the java.rmi.Remote interface. When such an object is invoked, its arguments are marshalled and sent from the local virtual machine to the remote one, where the arguments are unmarshalled and used. When the method terminates, the results are marshalled from the remote machine and sent to the caller's virtual machine.
To make a remote object accessible to other virtual machines, a program typically registers it with the RMI registry. The program supplies to the RMI registry the string name of the remote object and the remote object itself. When a program wants to access a remote object, it supplies the object's string name to the RMI registry on the same machine as the remote object. The RMI registry returns to the caller a reference (called "stub") to the remote object. When the program receives the stub for the remote object, it can invoke methods on the remote object (through the stub). A program can also obtain references to remote objects as a result of remote calls to other remote objects or from other naming services. For example, the program can look up a reference to a remote object from an LDAP server that supports the schema defined RFC 2713.
The string name accepted by the RMI registry has the syntax "rmi://hostname:port/remoteObjectName", where hostname and port identify the machine and port on which the RMI registry is running, respectively, and remoteObjectName is the string name of the remote object. hostname, port, and the prefix, "rmi:", are optional. If hostname is not specified, it defaults to the local host. If port is not specified, it defaults to 1099. If remoteObjectName is not specified, then the object being named is the RMI registry itself. See the RMI specification for details.
RMI can be supported by using different protocols: the Java Remote Method Protocol (JRMP) and the Internet Inter-ORB Protocol (IIOP). The JRMP is a specialized protocol designed for RMI; the IIOP is the standard protocol for communication between CORBA objects. RMI over IIOP allows Java remote objects to communicate with CORBA objects which might be written in a non-Java programming language.
Some service providers, such as Sun's LDAP service provider, support the binding of java.rmi.Remote objects into directories. By binding java.rmi.Remote objects or RMI registries into an enterprise-wide, shared namespace such as the LDAP, RMI clients can look up java.rmi.Remote objects without knowing on which machine the objects are running.
Binding a Remote Object

Before you go on: To run this example, you need the Java 2 Platform, v 1.2 or higher releases. You also need ldapbp.jar, as stated in the introduction of this lesson.

This example defines a java.rmi.Remote interface Hello with one method, sayHello().
public interface Hello extends Remote {
    public String sayHello() throws RemoteException;
}
It also defines an implementation of this interface, HelloImpl.
public class HelloImpl extends UnicastRemoteObject implements Hello {
    public HelloImpl() throws RemoteException {
    }

    public String sayHello() throws RemoteException {
        return ("Hello, the time is " + new java.util.Date());
    }
}
This example creates an instance of HelloImpl and binds it to the directory, assigning it the name "cn=RemoteHello".
// Create Remote object to be bound and give it a name
Hello h = new HelloImpl();

// Bind to directory
ctx.bind("cn=RemoteHello", h);
After the object has been bound in the directory, an application can look it up by using the following code:
Hello h2 = (Hello)ctx.lookup("cn=RemoteHello");
h2.sayHello();
To run this example, you must do the following:
Compile Hello.java, HelloImpl.java and this example.
# javac Hello.java HelloImpl RemoteObj.java
Run rmic with HelloImpl as the argument to produce the stubs for the remote object.
# rmic HelloImpl
Copy Hello.class, HelloImpl.class and the class files generated by rmic to a directory on a Web server.
Specify this directory as the codebase to the Java interpreter.
# java -Djava.rmi.server.codebase=http://web1/example/classes/ RemoteObj
RemoteObj does not terminate because it created the remote object HelloImpl that other RMI client can contact and use. However, this program will terminate eventually when the remote object becomes garbage collected. To prevent it from being garbage collected, you must maintain a (live) reference to the remote object. If you had registered the object in the the RMI registry instead, maintaining a reference would not be necessary because the registry would automatically maintain a reference to the object.
Afterwards, when you look up this object from the directory, the directory will return the HelloImpl remote object that is bound. The RMI will automatically download the necessary class files from the codebase specified in the "java.rmi.server.codebase" property. See the Reading Objects from the Directory lesson for an example.
Binding a Remote Object Using a Reference

Before you go on: This example requires that you have started the RMI registry on your machine. You also need rmiregistry.jar, as stated in the introduction of this lesson.

This example uses the same Hello and HelloImpl classes used in the previous example. This example creates a Reference containing an RMI URL ("rmi://mymachine/hello") and binds it in the directory.
String rmiurl = "rmi://mymachine/hello";

// Create reference containing (future) location of object
Reference ref = new Reference("Hello", new StringRefAddr("URL", rmiurl));

// Bind to directory
ctx.bind("cn=RefHello", ref);
It then creates an instance of HelloImpl and binds it to the local RMI registry using the same RMI URL ("rmi://mymachine/hello").
// Create Remote object to be bound
Hello h = new HelloImpl();

// Bind to RMI registry
ctx.rebind(rmiurl, h);
After the object has been bound in both the directory and RMI registry, an application can look up the object by using the following code:
Hello h2 = (Hello)ctx.lookup("cn=RefHello");
System.out.println(h2.sayHello());
In effect, this method has an extra level of indirection than the previous example. The information stored in the directory (the Reference) is actually a pointer to information stored in another naming service (the RMI Registry), which in turn, contains the reference to the java.rmi.Remote object.
To run this example, you must do the following:
Perform steps 1-3 from the previous example.
Compile this example.
# javac RemoteRef.java
Specify the codebase directory as the codebase to the Java interpreter.
# java -Djava.rmi.server.codebase=http://web1/example/classes/ RemoteRef
RemoteRef does not terminate because it created the remote object HelloImpl that other RMI client can contact and use.
Afterwards, when you look up this object from the directory, the directory will return the HelloImpl remote object that is bound. The RMI will automatically download the necessary class files from the codebase specified in the "java.rmi.server.codebase" property. See the Reading Objects from the Directory lesson for an example.
Binding a Remote Object that uses IIOP

Before you go on: This example requires that you have ldapbp.jar, as stated in the introduction of this lesson. If you are not using the Java 2 SDK, v 1.3, you also need to install the RMI-IIOP Standard Extension. If you are not using the Java 2 SDK, v 1.2 or higher releases, you also need to install Java IDL, a version of which comes with the RMI-IIOP Standard Extension.

The procedure for binding a java.rmi.Remote object that uses IIOP or one that uses JRMP is identical as far as the JNDI is concerned. From the user/application's perspective, the only difference is how the stubs for the java.rmi.Remote object are generated. Looking up the object presents a bigger difference: when the object is looked up from the directory (or some other naming service), the result must be narrowed by using the javax.rmi.PortableRemoteObject.narrow() method instead of the Java type cast operator.
This example uses the Hello interface from the JRMP example. It defines an implementation of this interface, RiHelloImpl, analogous to HelloImpl except that it extends from javax.rmi.PortableRemoteObject instead of java.rmi.server.UnicastRemoteObject.
public class RiHelloImpl extends PortableRemoteObject implements Hello {
    public RiHelloImpl() throws RemoteException {         
    }

    public String sayHello() throws RemoteException {
        String date = new String((new java.util.Date()).toString());
        return ("RMI/IIOP hello | " + date);
    }
}
This example creates an instance of RiHelloImpl and binds it to the directory, assigning it the name "cn=RmiiiopHello".
// Create Remote object to be bound and give it a name
Hello h = new RiHelloImpl();

// Bind to directory
ctx.bind("cn=RmiiiopHello", h);
After the object has been bound in the directory, an application can look it up by using the following code:
// Look up object
org.omg.CORBA.Object cobj = (org.omg.CORBA.Object)ctx.lookup("cn=RmiiiopHello");

// Narrow to desired type
Hello robj = (Hello)PortableRemoteObject.narrow(cobj, Hello.class);

// Invoke method
System.out.println(robj.sayHello());
To run this example, you must do the following:
Compile Hello.java, RiHelloImpl.java and this example.
# javac Hello.java RiHelloImpl RmiiiopObj.java
Run rmic with RiHelloImpl as the argument and the "-iiop" option to produce the IIOP stubs for the remote object.
# rmic -iiop RiHelloImpl
Copy Hello.class, RiHelloImpl.class and the class files generated by rmic to a directory on a Web server.
Specify this directory as the codebase to the Java interpreter.
# java -Djava.rmi.server.codebase=http://web1/example/classes/ RmiiiopObj
RmiiiopObj does not terminate because it created the remote object RiHelloImpl that other RMI client can contact and use.
Afterwards, when you look up this object from the directory, the directory will return the RiHelloImpl remote object that is bound. The RMI will automatically download the necessary class files from the codebase specified in the "java.rmi.server.codebase" property. See the Reading Objects from the Directory lesson for an example.

Storing Objects in the Directory