| CONTENTS |PREV |NEXT | Java Remote Method Invocation |
UnicastRemoteObject Classjava.rmi.server.UnicastRemoteObject provides supportfor creating and exporting remote objects. The class implements aremote server object with the following characteristics:package java.rmi.server;public class UnicastRemoteObject extends RemoteServer { protected UnicastRemoteObject() throws java.rmi.RemoteException {...} protected UnicastRemoteObject(int port) throws java.rmi.RemoteException {...} protected UnicastRemoteObject(int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws java.rmi.RemoteException {...} public Object clone() throws java.lang.CloneNotSupportedException {...} public static RemoteStub exportObject(java.rmi.Remote obj) throws java.rmi.RemoteException {...} public static Remote exportObject(java.rmi.Remote obj, int port) throws java.rmi.RemoteException {...} public static Remote exportObject(Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws java.rmi.RemoteException {...} public static boolean unexportObject(java.rmi.Remote obj, boolean force) throws java.rmi.NoSuchObjectException {...}}UnicastRemoteObject, the exporting involves listeningon a TCP port (note that more than one remote object can acceptincoming calls on the same port, so listening on a new port is notalways necessary). A remote object implementation can extend theclassUnicastRemoteObject to make use of itsconstructors that export the object, or it can extend some otherclass (or none at all) and export the object viaUnicastRemoteObject'sexportObjectmethods.The constructor that takes no arguments creates and exports a remote 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 and exports a remote object that accepts incoming calls on the specifiedport via aServerSocket created from theRMIServerSocketFactory; clients will make connections to the remote object viaSockets supplied from theRMIClientSocketFactory.
Note that if you export a remote object without specifying a socket factory, or if you export the object with a version of the methodUnicastRemoteObject.exportObject or the constructorUnicastRemoteObject that does not contain parameters of typeRMIClientSocketFactory andRMIServerSocketFactory), then the remote object is exported to all local addresses. To export a remote object to a specific address, see the sectionRMI Socket Factories.
RemoteObjectexportObject method (any of the forms) is usedto export a simple peer-to-peer remote object that is notimplemented by extending theUnicastRemoteObjectclass. The first form of theexportObject method takesa single parameter,obj, which is the remote object thatwill accept incoming RMI calls; thisexportObjectmethod exports the object on an anonymous (or arbitrary) port,chosen at runtime. The secondexportObject methodtakes two parameters, both the remote object,obj, andport, the port number on which the remote object acceptsincoming calls. The thirdexportObject method exportsthe object,obj, with the specifiedRMIClientSocketFactory,csf, andRMIServerSocketFactory,ssf, on the specifiedport. TheexportObject method returns aRemote stubwhich is the stub object for the remote object,obj,that is passed in place of the remote object in an RMI call.
UnicastRemoteObject in an RMI CallUnicastRemoteObject is passedas a parameter or return value in an RMI call, the object isreplaced by the remote object's stub. An exported remote objectimplementation remains in the virtual machine in which it wascreated and does not move (even by value) from that virtualmachine. In other words, an exported remote object is passed byreference in an RMI call; exported remote object implementationscannot be passed by value.UnicastRemoteObjectUnicastRemoteObject is transient and is not saved ifan object of that type is written to a user-definedObjectOutputStream (for example, if the object iswritten to a file using serialization). An object that is aninstance of a user-defined subclass ofUnicastRemoteObject, however, may have non-transientdata that can be saved when the object is serialized. When aUnicastRemoteObject is read from anObjectInputStream usingUnicastRemoteObject'sreadObjectmethod, the remote object is automatically exported to the RMIruntime so that it may receive RMI calls. If exporting the objectfails for some reason, deserializing the object will terminate withan exception.
UnicastRemoteObjectunexportObject method makes the remote object,obj, unavailable for incoming calls. If the forceparameter is true, the object is forcibly unexported even if thereare pending calls to the remote object or the remote object stillhas calls in progress. If the force parameter is false, the objectis only unexported if there are no pending or in-progress calls tothe object. If the object is successfully unexported, the RMIruntime removes the object from its internal tables. Unexportingthe object in this forcible manner may leave clients holding staleremote references to the remote object. This method throwsjava.rmi.NoSuchObjectException if the object was notpreviously exported to the RMI runtime.clone methodjava.lang.Cloneable interface. The classjava.rmi.server.UnicastRemoteObject does not implementthis interface, but does implement theclone method sothat if subclasses need to implementCloneable, theremote object will be capable of being cloned properly. Theclone method can be used by a subclass to create acloned remote object with initially the same contents, but isexported to accept remote calls and is distinct from the originalobject.