UnicastRemoteObject


1   /*
2    * @(#)UnicastRemoteObject.java 1.32 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package java.rmi.server;
8   
9   import java.rmi.*;
10  import sun.rmi.server.UnicastServerRef;
11  import sun.rmi.server.UnicastServerRef2;
12  
13  /**
14   * Used for exporting a remote object with JRMP and obtaining a stub
15   * that communicates to the remote object.
16   *
17   * <p>For the constructors and static <code>exportObject</code> methods
18   * below, the stub for a remote object being exported is obtained as
19   * follows:
20   *
21   * <p><ul>
22   *
23   * <li>If the remote object is exported using the {@link
24   * #exportObject(Remote) UnicastRemoteObject.exportObject(Remote)} method,
25   * a stub class (typically pregenerated from the remote object's class
26   * using the <code>rmic</code> tool) is loaded and an instance of that stub
27   * class is constructed as follows.
28   * <ul>
29   *
30   * <li>A "root class" is determined as follows:  if the remote object's
31   * class directly implements an interface that extends {@link Remote}, then
32   * the remote object's class is the root class; otherwise, the root class is
33   * the most derived superclass of the remote object's class that directly
34   * implements an interface that extends <code>Remote</code>.
35   *
36   * <li>The name of the stub class to load is determined by concatenating
37   * the binary name of the root class with the suffix <code>"_Stub"</code>.
38   *
39   * <li>The stub class is loaded by name using the class loader of the root
40   * class.  The stub class must extend {@link RemoteStub} and must have a
41   * public constructor that has one parameter, of type {@link RemoteRef}.
42   *
43   * <li>Finally, an instance of the stub class is constructed with a
44   * {@link RemoteRef}.
45   * </ul>
46   *
47   * <li>If the appropriate stub class could not be found, or the stub class
48   * could not be loaded, or a problem occurs creating the stub instance, a
49   * {@link StubNotFoundException} is thrown.
50   *
51   * <p>
52   * <li>For all other means of exporting:
53   * <p><ul>
54   *
55   * <li>If the remote object's stub class (as defined above) could not be
56   * loaded or the system property
57   * <code>java.rmi.server.ignoreStubClasses</code> is set to
58   * <code>"true"</code> (case insensitive), a {@link
59   * java.lang.reflect.Proxy} instance is constructed with the following
60   * properties:
61   *
62   * <ul>
63   *
64   * <li>The proxy's class is defined by the class loader of the remote
65   * object's class.
66   *
67   * <li>The proxy implements all the remote interfaces implemented by the
68   * remote object's class.
69   *
70   * <li>The proxy's invocation handler is a {@link
71   * RemoteObjectInvocationHandler} instance constructed with a
72   * {@link RemoteRef}.
73   *
74   * <li>If the proxy could not be created, a {@link StubNotFoundException}
75   * will be thrown.
76   * </ul>
77   *
78   * <p>
79   * <li>Otherwise, an instance of the remote object's stub class (as
80   * described above) is used as the stub.
81   *
82   * </ul>
83   * </ul>
84   *
85   * @version 1.32, 12/19/03
86   * @author  Ann Wollrath
87   * @author  Peter Jones
88   * @since   JDK1.1
89   **/
90  public class UnicastRemoteObject extends RemoteServer   {
91  
92      /**
93       * @serial port number on which to export object 
94       */
95      private int port = 0;
96  
97      /**
98       * @serial client-side socket factory (if any) 
99       */
100     private RMIClientSocketFactory   csf = null;
101     
102     /** 
103      * @serial server-side socket factory (if any) to use when
104      * exporting object 
105      */
106     private RMIServerSocketFactory   ssf = null;
107 
108     /* indicate compatibility with JDK 1.1.x version of class */
109     private static final long serialVersionUID = 4974527148936298033L;
110 
111     /**
112      * Creates and exports a new UnicastRemoteObject object using an
113      * anonymous port.
114      * @throws RemoteException if failed to export object
115      * @since JDK1.1
116      */
117     protected UnicastRemoteObject() throws RemoteException
118     {
119     this(0);
120     }
121 
122     /**
123      * Creates and exports a new UnicastRemoteObject object using the
124      * particular supplied port.
125      * @param port the port number on which the remote object receives calls
126      * (if <code>port</code> is zero, an anonymous port is chosen)
127      * @throws RemoteException if failed to export object
128      * @since 1.2
129      */
130     protected UnicastRemoteObject(int port) throws RemoteException
131     {
132     this.port = port;
133     exportObject((Remote) this, port);
134     }
135 
136     /**
137      * Creates and exports a new UnicastRemoteObject object using the
138      * particular supplied port and socket factories.
139      * @param port the port number on which the remote object receives calls
140      * (if <code>port</code> is zero, an anonymous port is chosen)
141      * @param csf the client-side socket factory for making calls to the
142      * remote object
143      * @param ssf the server-side socket factory for receiving remote calls
144      * @throws RemoteException if failed to export object
145      * @since 1.2
146      */
147     protected UnicastRemoteObject(int port,
148                   RMIClientSocketFactory   csf,
149                   RMIServerSocketFactory   ssf)
150     throws RemoteException
151     {
152     this.port = port;
153     this.csf = csf;
154     this.ssf = ssf;
155     exportObject((Remote) this, port, csf, ssf);
156     }
157 
158     /**
159      * Re-export the remote object when it is deserialized.
160      */
161     private void readObject(java.io.ObjectInputStream   in) 
162     throws java.io.IOException  , java.lang.ClassNotFoundException  
163     {
164     in.defaultReadObject();
165     reexport();
166     }
167     
168     /**
169      * Returns a clone of the remote object that is distinct from
170      * the original.
171      *
172      * @exception CloneNotSupportedException if clone failed due to
173      * a RemoteException.
174      * @return the new remote object
175      * @since JDK1.1
176      */
177     public Object   clone() throws CloneNotSupportedException  
178     {
179     try {
180         UnicastRemoteObject   cloned = (UnicastRemoteObject  ) super.clone();
181         cloned.reexport();
182         return cloned;
183     } catch (RemoteException e) {
184         throw new ServerCloneException  ("Clone failed", e);
185     }
186     }
187 
188     /*
189      * Exports this UnicastRemoteObject using its initialized fields because
190      * its creation bypassed running its constructors (via deserialization
191      * or cloning, for example).
192      */
193     private void reexport() throws RemoteException
194     {
195     if (csf == null && ssf == null) {
196         exportObject((Remote) this, port);
197     } else {
198         exportObject((Remote) this, port, csf, ssf);
199     }
200     }
201 
202     /** 
203      * Exports the remote object to make it available to receive incoming
204      * calls using an anonymous port.
205      * @param obj the remote object to be exported
206      * @return remote object stub
207      * @exception RemoteException if export fails
208      * @since JDK1.1
209      */
210     public static RemoteStub   exportObject(Remote obj)
211     throws RemoteException
212     {
213     /*
214      * Use UnicastServerRef constructor passing the boolean value true
215      * to indicate that only a generated stub class should be used.  A
216      * generated stub class must be used instead of a dynamic proxy
217      * because the return value of this method is RemoteStub which a
218      * dynamic proxy class cannot extend.
219      */
220     return (RemoteStub  ) exportObject(obj, new UnicastServerRef(true));
221     }
222 
223     /** 
224      * Exports the remote object to make it available to receive incoming
225      * calls, using the particular supplied port.
226      * @param obj the remote object to be exported
227      * @param port the port to export the object on
228      * @return remote object stub
229      * @exception RemoteException if export fails
230      * @since 1.2
231      */
232     public static Remote exportObject(Remote obj, int port)
233     throws RemoteException
234     {
235     return exportObject(obj, new UnicastServerRef(port));
236     }
237 
238     /**
239      * Exports the remote object to make it available to receive incoming
240      * calls, using a transport specified by the given socket factory.
241      * @param obj the remote object to be exported
242      * @param port the port to export the object on
243      * @param csf the client-side socket factory for making calls to the
244      * remote object
245      * @param ssf the server-side socket factory for receiving remote calls
246      * @return remote object stub
247      * @exception RemoteException if export fails
248      * @since 1.2
249      */
250     public static Remote exportObject(Remote obj, int port,
251                       RMIClientSocketFactory   csf,
252                       RMIServerSocketFactory   ssf)
253     throws RemoteException
254     {
255     
256     return exportObject(obj, new UnicastServerRef2(port, csf, ssf));
257     }
258 
259     /**
260      * Removes the remote object, obj, from the RMI runtime. If
261      * successful, the object can no longer accept incoming RMI calls.
262      * If the force parameter is true, the object is forcibly unexported
263      * even if there are pending calls to the remote object or the
264      * remote object still has calls in progress.  If the force
265      * parameter is false, the object is only unexported if there are
266      * no pending or in progress calls to the object.
267      *
268      * @param obj the remote object to be unexported
269      * @param force if true, unexports the object even if there are
270      * pending or in-progress calls; if false, only unexports the object
271      * if there are no pending or in-progress calls
272      * @return true if operation is successful, false otherwise
273      * @exception NoSuchObjectException if the remote object is not
274      * currently exported
275      * @since 1.2
276      */
277     public static boolean unexportObject(Remote obj, boolean force)
278     throws java.rmi.NoSuchObjectException  
279     {
280     return sun.rmi.transport.ObjectTable.unexportObject(obj, force);
281     }
282 
283     /**
284      * Exports the specified object using the specified server ref.
285      */
286     private static Remote exportObject(Remote obj, UnicastServerRef sref)
287     throws RemoteException
288     {
289     // if obj extends UnicastRemoteObject, set its ref.
290     if (obj instanceof UnicastRemoteObject  ) {
291         ((UnicastRemoteObject  ) obj).ref = sref;
292     }
293     return sref.exportObject(obj, null, false);
294     }
295 }
296
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags