Activatable


1   /*
2    * @(#)Activatable.java 1.34 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   
8   package java.rmi.activation;
9   
10  import java.lang.reflect.Constructor  ;
11  
12  import java.rmi.activation.UnknownGroupException  ;
13  import java.rmi.activation.UnknownObjectException  ;
14  import java.rmi.Remote  ;
15  import java.rmi.RemoteException  ;
16  import java.rmi.MarshalledObject  ;
17  import java.rmi.NoSuchObjectException  ;
18  
19  import java.rmi.server.*;
20  
21  import sun.rmi.server.ActivatableServerRef;
22  
23  /**
24   * The <code>Activatable</code> class provides support for remote
25   * objects that require persistent access over time and that
26   * can be activated by the system.
27   *
28   * <p>For the constructors and static <code>exportObject</code> methods,
29   * the stub for a remote object being exported is obtained as described in
30   * {@link java.rmi.server.UnicastRemoteObject}.
31   *
32   * @author  Ann Wollrath
33   * @version 1.34, 03/12/19
34   * @since   1.2
35   */
36  public abstract class Activatable extends RemoteServer {
37  
38      /** 
39       * @serial Activation Identifier for this object.
40       */
41      private ActivationID   id;
42      /** indicate compatibility with the Java 2 SDK v1.2 version of class */
43      private static final long serialVersionUID = -3120617863591563455L;
44      
45      /**
46       * Constructor used to register and export the object on a
47       * specified port (an anonymous port is chosen if port=0) .
48       *
49       * A concrete subclass of this class must call this constructor to
50       * register and export the object during <i>initial</i> construction.  As
51       * a side-effect of activatable object construction, the remote
52       * object is both "registered" with the activation system and
53       * "exported" (on an anonymous port if port=0) to the RMI runtime
54       * so that it is available to accept incoming calls from clients.
55       *
56       * @param location the location for classes for this object
57       * @param data the object's initialization data
58       * @param port the port on which the object is exported (an anonymous
59       * port is used if port=0)
60       * @param restart if true, the object is restarted (reactivated) when
61       * either the activator is restarted or the object's activation group
62       * is restarted after an unexpected crash; if false, the object is only
63       * activated on demand.  Specifying <code>restart</code> to be
64       * <code>true</code> does not force an initial immediate activation of
65       * a newly registered object;  initial activation is lazy.
66       * @exception ActivationException if object registration fails.
67       * @exception RemoteException if either of the following fails:
68       * a) registering the object with the activation system or b) exporting
69       * the object to the RMI runtime.
70       * @since 1.2
71       */
72      protected Activatable(String   location,
73                MarshalledObject   data,
74                boolean restart,
75                int port)
76      throws ActivationException  , RemoteException  
77      {
78      super();
79      id = exportObject(this, location, data, restart, port);
80      }
81      
82      /**
83       * Constructor used to register and export the object on a
84       * specified port (an anonymous port is chosen if port=0) . <p>
85       *
86       * A concrete subclass of this class must call this constructor to
87       * register and export the object during <i>initial</i> construction.  As
88       * a side-effect of activatable object construction, the remote
89       * object is both "registered" with the activation system and
90       * "exported" (on an anonymous port if port=0) to the RMI runtime
91       * so that it is available to accept incoming calls from clients.
92       *
93       * @param location the location for classes for this object
94       * @param data the object's initialization data
95       * @param restart if true, the object is restarted (reactivated) when
96       * either the activator is restarted or the object's activation group
97       * is restarted after an unexpected crash; if false, the object is only
98       * activated on demand.  Specifying <code>restart</code> to be
99       * <code>true</code> does not force an initial immediate activation of
100      * a newly registered object;  initial activation is lazy.
101      * @param port the port on which the object is exported (an anonymous
102      * port is used if port=0)
103      * @param csf the client-side socket factory for making calls to the
104      * remote object
105      * @param ssf the server-side socket factory for receiving remote calls
106      * @exception ActivationException if object registration fails.
107      * @exception RemoteException if either of the following fails:
108      * a) registering the object with the activation system or b) exporting
109      * the object to the RMI runtime.
110      * @since 1.2
111      */
112     protected Activatable(String   location,
113               MarshalledObject   data,
114               boolean restart,
115               int port,
116               RMIClientSocketFactory csf,
117               RMIServerSocketFactory ssf)
118     throws ActivationException  , RemoteException  
119     {
120     super();
121     id = exportObject(this, location, data, restart, port, csf, ssf);
122     }
123 
124     /**
125      * Constructor used to activate/export the object on a specified
126      * port. An "activatable" remote object must have a constructor that
127      * takes two arguments: <ul>
128      * <li>the object's activation identifier (<code>ActivationID</code>), and
129      * <li>the object's initialization data (a <code>MarshalledObject</code>).
130      * </ul><p>
131      *
132      * A concrete subclass of this class must call this constructor when it is
133      * <i>activated</i> via the two parameter constructor described above. As
134      * a side-effect of construction, the remote object is "exported"
135      * to the RMI runtime (on the specified <code>port</code>) and is
136      * available to accept incoming calls from clients.
137      *
138      * @param id activation identifier for the object
139      * @param port the port number on which the object is exported
140      * @exception RemoteException if exporting the object to the RMI
141      * runtime fails
142      * @since 1.2
143      */
144     protected Activatable(ActivationID   id, int port)
145     throws RemoteException   
146     {
147     super();
148     this.id = id;
149     exportObject(this, id, port);
150     }
151 
152     /**
153      * Constructor used to activate/export the object on a specified
154      * port. An "activatable" remote object must have a constructor that
155      * takes two arguments: <ul>
156      * <li>the object's activation identifier (<code>ActivationID</code>), and
157      * <li>the object's initialization data (a <code>MarshalledObject</code>).
158      * </ul><p>
159      *
160      * A concrete subclass of this class must call this constructor when it is
161      * <i>activated</i> via the two parameter constructor described above. As
162      * a side-effect of construction, the remote object is "exported"
163      * to the RMI runtime (on the specified <code>port</code>) and is
164      * available to accept incoming calls from clients.
165      *
166      * @param id activation identifier for the object
167      * @param port the port number on which the object is exported
168      * @param csf the client-side socket factory for making calls to the
169      * remote object
170      * @param ssf the server-side socket factory for receiving remote calls
171      * @exception RemoteException if exporting the object to the RMI
172      * runtime fails
173      * @since 1.2
174      */
175     protected Activatable(ActivationID   id, int port,
176               RMIClientSocketFactory csf,
177               RMIServerSocketFactory ssf)
178     throws RemoteException   
179     {
180     super();
181     this.id = id;
182     exportObject(this, id, port, csf, ssf);
183     }
184     
185     /**
186      * Returns the object's activation identifier.  The method is
187      * protected so that only subclasses can obtain an object's
188      * identifier.
189      * @return the object's activation identifier
190      * @since 1.2
191      */
192     protected ActivationID   getID() {
193     return id;
194     }
195 
196     /** 
197      * Register an object descriptor for an activatable remote
198      * object so that is can be activated on demand.
199      *
200      * @param desc  the object's descriptor
201      * @return the stub for the activatable remote object
202      * @exception UnknownGroupException if group id in <code>desc</code>
203      * is not registered with the activation system
204      * @exception ActivationException if activation system is not running
205      * @exception RemoteException if remote call fails
206      * @since 1.2
207      */
208     public static Remote   register(ActivationDesc   desc)
209     throws UnknownGroupException  , ActivationException  , RemoteException  
210     {
211     // register object with activator.
212     ActivationID   id =
213         ActivationGroup.getSystem().registerObject(desc);
214     return sun.rmi.server.ActivatableRef.getStub(desc, id);
215     }
216     
217     /**
218      * Informs the system that the object with the corresponding activation
219      * <code>id</code> is currently inactive. If the object is currently
220      * active, the object is "unexported" from the RMI runtime (only if
221      * there are no pending or in-progress calls)
222      * so the that it can no longer receive incoming calls. This call
223      * informs this VM's ActivationGroup that the object is inactive,
224      * that, in turn, informs its ActivationMonitor. If this call
225      * completes successfully, a subsequent activate request to the activator
226      * will cause the object to reactivate. The operation may still
227      * succeed if the object is considered active but has already
228      * unexported itself.
229      *
230      * @param id the object's activation identifier
231      * @return true if the operation succeeds (the operation will
232      * succeed if the object in currently known to be active and is
233      * either already unexported or is currently exported and has no
234      * pending/executing calls); false is returned if the object has
235      * pending/executing calls in which case it cannot be deactivated
236      * @exception UnknownObjectException if object is not known (it may
237      * already be inactive)
238      * @exception ActivationException if group is not active
239      * @exception RemoteException if call informing monitor fails
240      * @since 1.2
241      */
242     public static boolean inactive(ActivationID   id)
243     throws UnknownObjectException  , ActivationException  , RemoteException  
244     {
245     return ActivationGroup.currentGroup().inactiveObject(id);
246     }
247 
248     /**
249      * Revokes previous registration for the activation descriptor
250      * associated with <code>id</code>. An object can no longer be
251      * activated via that <code>id</code>.
252      *
253      * @param id the object's activation identifier
254      * @exception UnknownObjectException if object (<code>id</code>) is unknown
255      * @exception ActivationException if activation system is not running
256      * @exception RemoteException if remote call to activation system fails
257      * @since 1.2
258      */
259     public static void unregister(ActivationID   id)
260     throws UnknownObjectException  , ActivationException  , RemoteException  
261     {
262     ActivationGroup.getSystem().unregisterObject(id);
263     }
264 
265     /**
266      * This <code>exportObject</code> method may be invoked explicitly
267      * by an "activatable" object, that does not extend the
268      * <code>Activatable</code> class, in order to both a) register
269      * the object's activation descriptor, constructed from the supplied
270      * <code>location</code>, and <code>data</code>, with
271      * the activation system (so the object can be activated), and
272      * b) export the remote object, <code>obj</code>, on a specific
273      * port (if port=0, then an anonymous port is chosen). Once the
274      * object is exported, it can receive incoming RMI calls.<p>
275      *
276      * This method does not need to be called if <code>obj</code>
277      * extends <code>Activatable</code>, since the first constructor
278      * calls this method.
279      *
280      * @param obj the object being exported
281      * @param location the object's code location
282      * @param data the object's bootstrapping data
283      * @param restart if true, the object is restarted (reactivated) when
284      * either the activator is restarted or the object's activation group
285      * is restarted after an unexpected crash; if false, the object is only
286      * activated on demand.  Specifying <code>restart</code> to be
287      * <code>true</code> does not force an initial immediate activation of
288      * a newly registered object;  initial activation is lazy.
289      * @param port the port on which the object is exported (an anonymous
290      * port is used if port=0)
291      * @return the activation identifier obtained from registering the
292      * descriptor, <code>desc</code>, with the activation system
293      * the wrong group
294      * @exception ActivationException if activation group is not active
295      * @exception RemoteException if object registration or export fails
296      * @since 1.2
297      */
298     public static ActivationID   exportObject(Remote   obj,
299                         String   location,
300                         MarshalledObject   data,
301                         boolean restart,
302                         int port)
303     throws ActivationException  , RemoteException  
304     {
305     ActivationDesc   desc = new ActivationDesc  (obj.getClass().getName(),
306                          location, data, restart);
307     ActivationID   id = ActivationGroup.getSystem().registerObject(desc);
308     Remote   stub = exportObject(obj, id, port);
309     ActivationGroup.currentGroup().activeObject(id, obj); 
310     return id;
311     }
312 
313     /**
314      * This <code>exportObject</code> method may be invoked explicitly
315      * by an "activatable" object, that does not extend the
316      * <code>Activatable</code> class, in order to both a) register
317      * the object's activation descriptor, constructed from the supplied
318      * <code>location</code>, and <code>data</code>, with
319      * the activation system (so the object can be activated), and
320      * b) export the remote object, <code>obj</code>, on a specific
321      * port (if port=0, then an anonymous port is chosen). Once the
322      * object is exported, it can receive incoming RMI calls.<p>
323      *
324      * This method does not need to be called if <code>obj</code>
325      * extends <code>Activatable</code>, since the first constructor
326      * calls this method.
327      *
328      * @param obj the object being exported
329      * @param location the object's code location
330      * @param data the object's bootstrapping data
331      * @param restart if true, the object is restarted (reactivated) when
332      * either the activator is restarted or the object's activation group
333      * is restarted after an unexpected crash; if false, the object is only
334      * activated on demand.  Specifying <code>restart</code> to be
335      * <code>true</code> does not force an initial immediate activation of
336      * a newly registered object;  initial activation is lazy.
337      * @param port the port on which the object is exported (an anonymous
338      * port is used if port=0)
339      * @param csf the client-side socket factory for making calls to the
340      * remote object
341      * @param ssf the server-side socket factory for receiving remote calls
342      * @return the activation identifier obtained from registering the
343      * descriptor, <code>desc</code>, with the activation system
344      * the wrong group
345      * @exception ActivationException if activation group is not active
346      * @exception RemoteException if object registration or export fails
347      * @since 1.2
348      */
349     public static ActivationID   exportObject(Remote   obj,
350                         String   location,
351                         MarshalledObject   data,
352                         boolean restart,
353                         int port,
354                         RMIClientSocketFactory csf,
355                         RMIServerSocketFactory ssf)
356     throws ActivationException  , RemoteException  
357     {
358     ActivationDesc   desc = new ActivationDesc  (obj.getClass().getName(),
359                          location, data, restart);
360     ActivationID   id = ActivationGroup.getSystem().registerObject(desc);
361     Remote   stub = exportObject(obj, id, port, csf, ssf);
362     ActivationGroup.currentGroup().activeObject(id, obj); 
363     return id;
364     }
365 
366     /** 
367      * Export the activatable remote object to the RMI runtime to make
368      * the object available to receive incoming calls. The object is
369      * exported on an anonymous port, if <code>port</code> is zero. <p>
370      *
371      * During activation, this <code>exportObject</code> method should
372      * be invoked explicitly by an "activatable" object, that does not
373      * extend the <code>Activatable</code> class. There is no need for objects
374      * that do extend the <code>Activatable</code> class to invoke this
375      * method directly; this method is called by the second constructor
376      * above (which a subclass should invoke from its special activation
377      * constructor).
378      * 
379      * @return the stub for the activatable remote object
380      * @param obj the remote object implementation
381      * @param id the object's  activation identifier
382      * @param port the port on which the object is exported (an anonymous
383      * port is used if port=0)
384      * @exception RemoteException if object export fails
385      * @since 1.2
386      */
387     public static Remote   exportObject(Remote   obj,
388                       ActivationID   id,
389                       int port)
390     throws RemoteException  
391     {
392     return exportObject(obj, new ActivatableServerRef(id, port));
393     }
394 
395     /** 
396      * Export the activatable remote object to the RMI runtime to make
397      * the object available to receive incoming calls. The object is
398      * exported on an anonymous port, if <code>port</code> is zero. <p>
399      *
400      * During activation, this <code>exportObject</code> method should
401      * be invoked explicitly by an "activatable" object, that does not
402      * extend the <code>Activatable</code> class. There is no need for objects
403      * that do extend the <code>Activatable</code> class to invoke this
404      * method directly; this method is called by the second constructor
405      * above (which a subclass should invoke from its special activation
406      * constructor).
407      * 
408      * @return the stub for the activatable remote object
409      * @param obj the remote object implementation
410      * @param id the object's  activation identifier
411      * @param port the port on which the object is exported (an anonymous
412      * port is used if port=0)
413      * @param csf the client-side socket factory for making calls to the
414      * remote object
415      * @param ssf the server-side socket factory for receiving remote calls
416      * @exception RemoteException if object export fails
417      * @since 1.2
418      */
419     public static Remote   exportObject(Remote   obj,
420                       ActivationID   id,
421                       int port,
422                       RMIClientSocketFactory csf,
423                       RMIServerSocketFactory ssf)
424     throws RemoteException  
425     {
426     return exportObject(obj, new ActivatableServerRef(id, port, csf, ssf));
427     }
428     
429     /**
430      * Remove the remote object, obj, from the RMI runtime. If
431      * successful, the object can no longer accept incoming RMI calls.
432      * If the force parameter is true, the object is forcibly unexported
433      * even if there are pending calls to the remote object or the
434      * remote object still has calls in progress.  If the force
435      * parameter is false, the object is only unexported if there are
436      * no pending or in progress calls to the object.
437      *
438      * @param obj the remote object to be unexported
439      * @param force if true, unexports the object even if there are
440      * pending or in-progress calls; if false, only unexports the object
441      * if there are no pending or in-progress calls
442      * @return true if operation is successful, false otherwise
443      * @exception NoSuchObjectException if the remote object is not
444      * currently exported
445      * @since 1.2
446      */
447     public static boolean unexportObject(Remote   obj, boolean force)
448     throws NoSuchObjectException  
449     {
450     return sun.rmi.transport.ObjectTable.unexportObject(obj, force);
451     }
452 
453     /**
454      * Exports the specified object using the specified server ref.
455      */
456     private static Remote   exportObject(Remote   obj, ActivatableServerRef sref)
457     throws RemoteException  
458     {
459     // if obj extends Activatable, set its ref.
460     if (obj instanceof Activatable  ) {
461         ((Activatable  ) obj).ref = sref;
462 
463     }
464     return sref.exportObject(obj, null, false);
465     }
466 }
467
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags