ActivationSystem


1   /*
2    * @(#)ActivationSystem.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.Remote  ;
11  import java.rmi.RemoteException  ;
12  import java.rmi.activation.UnknownGroupException  ;
13  import java.rmi.activation.UnknownObjectException  ;
14  
15  /**
16   * The <code>ActivationSystem</code> provides a means for registering
17   * groups and "activatable" objects to be activated within those groups.
18   * The <code>ActivationSystem</code> works closely with the
19   * <code>Activator</code>, which activates objects registered via the
20   * <code>ActivationSystem</code>, and the <code>ActivationMonitor</code>,
21   * which obtains information about active and inactive objects,
22   * and inactive groups.
23   *
24   * @author  Ann Wollrath
25   * @version 1.18, 12/19/03
26   * @see     Activator
27   * @see     ActivationMonitor
28   * @since   1.2
29   */
30  public interface ActivationSystem extends Remote   {
31  
32      /** The port to lookup the activation system. */
33      public static final int SYSTEM_PORT = 1098;
34      
35      /**
36       * The <code>registerObject</code> method is used to register an
37       * activation descriptor, <code>desc</code>, and obtain an
38       * activation identifier for a activatable remote object. The
39       * <code>ActivationSystem</code> creates an
40       * <code>ActivationID</code> (a activation identifier) for the
41       * object specified by the descriptor, <code>desc</code>, and
42       * records, in stable storage, the activation descriptor and its
43       * associated identifier for later use. When the <code>Activator</code>
44       * receives an <code>activate</code> request for a specific identifier, it
45       * looks up the activation descriptor (registered previously) for
46       * the specified identifier and uses that information to activate
47       * the object. <p>
48       *
49       * @param desc the object's activation descriptor
50       * @return the activation id that can be used to activate the object
51       * @exception ActivationException if registration fails (e.g., database
52       * update failure, etc).
53       * @exception UnknownGroupException if group referred to in
54       * <code>desc</code> is not registered with this system
55       * @exception RemoteException if remote call fails
56       * @since 1.2
57       */
58      public ActivationID   registerObject(ActivationDesc   desc)
59      throws ActivationException  , UnknownGroupException  , RemoteException  ;
60      
61      /**
62       * Remove the activation id and associated descriptor previously
63       * registered with the <code>ActivationSystem</code>; the object
64       * can no longer be activated via the object's activation id.
65       *
66       * @param id the object's activation id (from previous registration)
67       * @exception ActivationException if unregister fails (e.g., database
68       * update failure, etc).
69       * @exception UnknownObjectException if object is unknown (not registered)
70       * @exception RemoteException if remote call fails
71       * @since 1.2
72       */
73      public void unregisterObject(ActivationID   id)
74      throws ActivationException  , UnknownObjectException  , RemoteException  ;
75      
76      /**
77       * Register the activation group. An activation group must be
78       * registered with the <code>ActivationSystem</code> before objects
79       * can be registered within that group.
80       *
81       * @param desc the group's descriptor
82       * @return an identifier for the group
83       * @exception ActivationException if group registration fails
84       * @exception RemoteException if remote call fails
85       * @since 1.2
86       */
87      public ActivationGroupID   registerGroup(ActivationGroupDesc   desc)
88      throws ActivationException  , RemoteException  ;
89  
90      /**
91       * Callback to inform activation system that group is now
92       * active. This call is made internally by the
93       * <code>ActivationGroup.createGroup</code> method to inform
94       * the <code>ActivationSystem</code> that the group is now
95       * active.
96       *
97       * @param id the activation group's identifier
98       * @param group the group's instantiator
99       * @param incarnation the group's incarnation number
100      * @return monitor for activation group
101      * @exception UnknownGroupException if group is not registered
102      * @exception ActivationException if a group for the specified
103      * <code>id</code> is already active and that group is not equal
104      * to the specified <code>group</code> or that group has a different
105      * <code>incarnation</code> than the specified <code>group</code>
106      * @exception RemoteException if remote call fails
107      * @since 1.2
108      */
109     public ActivationMonitor   activeGroup(ActivationGroupID   id,
110                      ActivationInstantiator   group,
111                      long incarnation)
112     throws UnknownGroupException  , ActivationException  , RemoteException  ;
113     
114     /**
115      * Remove the activation group. An activation group makes this call back
116      * to inform the activator that the group should be removed (destroyed).
117      * If this call completes successfully, objects can no longer be
118      * registered or activated within the group. All information of the
119      * group and its associated objects is removed from the system.
120      *
121      * @param id the activation group's identifier
122      * @exception ActivationException if unregister fails (e.g., database
123      * update failure, etc).
124      * @exception UnknownGroupException if group is not registered
125      * @exception RemoteException if remote call fails
126      * @since 1.2
127      */
128     public void unregisterGroup(ActivationGroupID   id)
129     throws ActivationException  , UnknownGroupException  , RemoteException  ;
130 
131     /**
132      * Shutdown the activation system. Destroys all groups spawned by
133      * the activation daemon and exits the activation daemon.
134      * @exception RemoteException if failed to contact/shutdown the activation
135      * daemon
136      * @since 1.2
137      */
138     public void shutdown() throws RemoteException  ;
139 
140     /**
141      * Set the activation descriptor, <code>desc</code> for the object with
142      * the activation identifier, <code>id</code>. The change will take
143      * effect upon subsequent activation of the object.
144      *
145      * @param id the activation identifier for the activatable object
146      * @param desc the activation descriptor for the activatable object
147      * @exception UnknownGroupException the group associated with
148      * <code>desc</code> is not a registered group
149      * @exception UnknownObjectException the activation <code>id</code>
150      * is not registered
151      * @exception ActivationException for general failure (e.g., unable
152      * to update log)
153      * @exception RemoteException if remote call fails
154      * @return the previous value of the activation descriptor
155      * @see #getActivationDesc
156      * @since 1.2
157      */
158     public ActivationDesc   setActivationDesc(ActivationID   id,
159                         ActivationDesc   desc)
160     throws ActivationException  , UnknownObjectException  ,
161         UnknownGroupException  , RemoteException  ;
162 
163     /**
164      * Set the activation group descriptor, <code>desc</code> for the object
165      * with the activation group identifier, <code>id</code>. The change will
166      * take effect upon subsequent activation of the group.
167      * 
168      * @param id the activation group identifier for the activation group
169      * @param desc the activation group descriptor for the activation group
170      * @exception UnknownGroupException the group associated with
171      * <code>id</code> is not a registered group
172      * @exception ActivationException for general failure (e.g., unable
173      * to update log)
174      * @exception RemoteException if remote call fails
175      * @return the previous value of the activation group descriptor
176      * @see #getActivationGroupDesc
177      * @since 1.2
178      */
179     public ActivationGroupDesc   setActivationGroupDesc(ActivationGroupID   id,
180                               ActivationGroupDesc   desc)
181        throws ActivationException  , UnknownGroupException  , RemoteException  ;
182 
183     /**
184      * Returns the activation descriptor, for the object with the activation
185      * identifier, <code>id</code>.
186      * 
187      * @param id the activation identifier for the activatable object
188      * @exception UnknownObjectException if <code>id</code> is not registered
189      * @exception ActivationException for general failure
190      * @exception RemoteException if remote call fails
191      * @return the activation descriptor
192      * @see #setActivationDesc
193      * @since 1.2
194      */
195     public ActivationDesc   getActivationDesc(ActivationID   id)
196        throws ActivationException  , UnknownObjectException  , RemoteException  ;
197           
198     /**
199      * Returns the activation group descriptor, for the group
200      * with the activation group identifier, <code>id</code>. 
201      * 
202      * @param id the activation group identifier for the group
203      * @exception UnknownGroupException if <code>id</code> is not registered
204      * @exception ActivationException for general failure
205      * @exception RemoteException if remote call fails
206      * @return the activation group descriptor
207      * @see #setActivationGroupDesc
208      * @since 1.2
209      */
210     public ActivationGroupDesc   getActivationGroupDesc(ActivationGroupID   id)
211        throws ActivationException  , UnknownGroupException  , RemoteException  ;
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags