CONTENTS | PREV | NEXT Java Remote Method Invocation


5.4 The UnicastRemoteObject Class

The java.rmi.server.UnicastRemoteObject class provides support for point-to-point active object references using TCP-based streams. The class implements a remote server object with the following characteristics:


5.4.1 Constructing a New Remote Object

In a Java virtual machine running as a server, remote objects defined by the developer can be created by the server application. When a remote object class extends UnicastRemoteObject, the object's constructor calls one of UnicastRemoteObject's constructors in order to create and export the remote object. Exporting a remote object makes that object available to accept incoming calls from clients.

The default constructor creates and exports the object on an anonymous (or arbitrary) port, chosen at runtime. The second form of the constructor takes a single argument, port, that specifies the port number on which the remote object accepts incoming calls. The third constructor creates a remote object of the specified SocketType, type, that accepts incoming calls on the specified port. The default constructor creates a new unicast remote object using an anonymous port.

The clone method is used to create a unicast remote object with initially the same contents, but is exported to accept remote calls and is distinct from the original object.


5.4.2 Exporting an Implementation Not Extended From RemoteObject

The exportObject method (either form) is used to export a simple peer-to-peer remote object that is not implemented by extending the UnicastRemoteObject class. The first form of the exportObject method takes a single parameter, obj, which is the remote object that will accept incoming RMI calls; this exportObject method exports the object on an anonymous (or arbitrary) port, chosen at runtime. The second exportObject method takes two parameters, both the remote object, obj, and port, the port number on which the remote object accepts incoming calls. The third exportObject method exports the object, obj, with the specified SocketType, type, on the specified port.

The object must be exported prior to the first time it is passed in an RMI call as either a parameter or return value; otherwise, a java.rmi.server.StubNotFoundException is thrown when a remote call is attempted in which an "unexported" remote object is passed as an argument or return value.

Once exported, the object can be passed as an argument in an RMI call or returned as the result of an RMI call. When a remote object is passed, during marshaling a lookup is performed to find the matching remote stub for the remote object implementation and that stub is passed or returned instead.

The exportObject method returns a Remote stub which is the stub object for the remote object, obj, that is passed in place of the remote object in an RMI call.


5.4.3 Passing a UnicastRemoteObject in an RMI Call

As stated above, when an object of type UnicastRemoteObject is passed as a parameter or return value in an RMI call, the object is replaced by the remote object's stub. A remote object implementation remains in the virtual machine in which it was created and does not move (even by value) from that virtual machine. In other words, a remote object is passed by reference in an RMI call; remote objects cannot be passed by value.


5.4.4 Serializing a UnicastRemoteObject

Information contained in UnicastRemoteObject is transient and is not saved if an object of that type is written to a user-defined ObjectOutputStream (for example, if the object is written to a file using serialization). An object that is an instance of a user-defined subclass of UnicastRemoteObject, however, may have non-transient data that can be saved when the object is serialized.

When a UnicastRemoteObject is read from an ObjectInputStream, it is automatically exported to the RMI runtime so that it may receive RMI calls. If exporting the object fails for some reason, deserializing the object will terminate with an exception.



CONTENTS | PREV | NEXT
Copyright © 1997-1998 Sun Microsystems, Inc. All Rights Reserved.