Activator


1   /*
2    * @(#)Activator.java   1.18 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.rmi.MarshalledObject  ;
11  import java.rmi.Remote  ;
12  import java.rmi.RemoteException  ;
13  import java.rmi.activation.UnknownObjectException  ;
14  
15  /**
16   * The <code>Activator</code> facilitates remote object activation. A
17   * "faulting" remote reference calls the activator's
18   * <code>activate</code> method to obtain a "live" reference to a
19   * "activatable" remote object. Upon receiving a request for activation,
20   * the activator looks up the activation descriptor for the activation
21   * identifier, <code>id</code>, determines the group in which the
22   * object should be activated initiates object re-creation via the
23   * group's <code>ActivationInstantiator</code> (via a call to the
24   * <code>newInstance</code> method). The activator initiates the
25   * execution of activation groups as necessary. For example, if an
26   * activation group for a specific group identifier is not already
27   * executing, the activator initiates the execution of a VM for the
28   * group. <p>
29   *
30   * The <code>Activator</code> works closely with
31   * <code>ActivationSystem</code>, which provides a means for registering
32   * groups and objects within those groups, and <code>ActivationMonitor</code>,
33   * which recives information about active and inactive objects and inactive
34   * groups. <p>
35   *
36   * The activator is responsible for monitoring and detecting when
37   * activation groups fail so that it can remove stale remote references
38   * to groups and active object's within those groups.<p>
39   *
40   * @author  Ann Wollrath
41   * @version 1.18, 12/19/03
42   * @see     ActivationInstantiator
43   * @see     ActivationGroupDesc
44   * @see     ActivationGroupID
45   * @since   1.2
46   */
47  public interface Activator extends Remote   {
48      /**
49       * Activate the object associated with the activation identifier,
50       * <code>id</code>. If the activator knows the object to be active
51       * already, and <code>force</code> is false , the stub with a
52       * "live" reference is returned immediately to the caller;
53       * otherwise, if the activator does not know that corresponding
54       * the remote object is active, the activator uses the activation
55       * descriptor information (previously registered) to determine the
56       * group (VM) in which the object should be activated. If an
57       * <code>ActivationInstantiator</code> corresponding to the
58       * object's group descriptor already exists, the activator invokes
59       * the activation group's <code>newInstance</code> method passing
60       * it the object's id and descriptor. <p>
61       *
62       * If the activation group for the object's group descriptor does
63       * not yet exist, the activator starts an
64       * <code>ActivationInstantiator</code> executing (by spawning a
65       * child process, for example). When the activator receives the
66       * activation group's call back (via the
67       * <code>ActivationSystem</code>'s <code>activeGroup</code>
68       * method) specifying the activation group's reference, the
69       * activator can then invoke that activation instantiator's
70       * <code>newInstance</code> method to forward each pending
71       * activation request to the activation group and return the
72       * result (a marshalled remote object reference, a stub) to the
73       * caller.<p>
74       *
75       * Note that the activator receives a "marshalled" object instead of a
76       * Remote object so that the activator does not need to load the
77       * code for that object, or participate in distributed garbage
78       * collection for that object. If the activator kept a strong
79       * reference to the remote object, the activator would then
80       * prevent the object from being garbage collected under the
81       * normal distributed garbage collection mechanism. <p>
82       *
83       * @param id the activation identifier for the object being activated
84       * @param force if true, the activator contacts the group to obtain
85       * the remote object's reference; if false, returning the cached value
86       * is allowed.
87       * @return the remote object (a stub) in a marshalled form
88       * @exception ActivationException if object activation fails
89       * @exception UnknownObjectException if object is unknown (not registered)
90       * @exception RemoteException if remote call fails
91       * @since 1.2
92       */
93      public MarshalledObject   activate(ActivationID   id, boolean force)
94      throws ActivationException  , UnknownObjectException  , RemoteException  ;
95  
96  }
97
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags