1/*
2 * Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package java.rmi.activation;
27
28import java.rmi.Remote;
29import java.rmi.RemoteException;
30import java.rmi.activation.UnknownGroupException;
31import java.rmi.activation.UnknownObjectException;
32
33/**
34 * The <code>ActivationSystem</code> provides a means for registering
35 * groups and "activatable" objects to be activated within those groups.
36 * The <code>ActivationSystem</code> works closely with the
37 * <code>Activator</code>, which activates objects registered via the
38 * <code>ActivationSystem</code>, and the <code>ActivationMonitor</code>,
39 * which obtains information about active and inactive objects,
40 * and inactive groups.
41 *
42 * @author      Ann Wollrath
43 * @see         Activator
44 * @see         ActivationMonitor
45 * @since       1.2
46 */
47public interface ActivationSystem extends Remote {
48
49    /** The port to lookup the activation system. */
50    public static final int SYSTEM_PORT = 1098;
51
52    /**
53     * The <code>registerObject</code> method is used to register an
54     * activation descriptor, <code>desc</code>, and obtain an
55     * activation identifier for a activatable remote object. The
56     * <code>ActivationSystem</code> creates an
57     * <code>ActivationID</code> (a activation identifier) for the
58     * object specified by the descriptor, <code>desc</code>, and
59     * records, in stable storage, the activation descriptor and its
60     * associated identifier for later use. When the <code>Activator</code>
61     * receives an <code>activate</code> request for a specific identifier, it
62     * looks up the activation descriptor (registered previously) for
63     * the specified identifier and uses that information to activate
64     * the object.
65     *
66     * @param desc the object's activation descriptor
67     * @return the activation id that can be used to activate the object
68     * @exception ActivationException if registration fails (e.g., database
69     * update failure, etc).
70     * @exception UnknownGroupException if group referred to in
71     * <code>desc</code> is not registered with this system
72     * @exception RemoteException if remote call fails
73     * @since 1.2
74     */
75    public ActivationID registerObject(ActivationDesc desc)
76        throws ActivationException, UnknownGroupException, RemoteException;
77
78    /**
79     * Remove the activation id and associated descriptor previously
80     * registered with the <code>ActivationSystem</code>; the object
81     * can no longer be activated via the object's activation id.
82     *
83     * @param id the object's activation id (from previous registration)
84     * @exception ActivationException if unregister fails (e.g., database
85     * update failure, etc).
86     * @exception UnknownObjectException if object is unknown (not registered)
87     * @exception RemoteException if remote call fails
88     * @since 1.2
89     */
90    public void unregisterObject(ActivationID id)
91        throws ActivationException, UnknownObjectException, RemoteException;
92
93    /**
94     * Register the activation group. An activation group must be
95     * registered with the <code>ActivationSystem</code> before objects
96     * can be registered within that group.
97     *
98     * @param desc the group's descriptor
99     * @return an identifier for the group
100     * @exception ActivationException if group registration fails
101     * @exception RemoteException if remote call fails
102     * @since 1.2
103     */
104    public ActivationGroupID registerGroup(ActivationGroupDesc desc)
105        throws ActivationException, RemoteException;
106
107    /**
108     * Callback to inform activation system that group is now
109     * active. This call is made internally by the
110     * <code>ActivationGroup.createGroup</code> method to inform
111     * the <code>ActivationSystem</code> that the group is now
112     * active.
113     *
114     * @param id the activation group's identifier
115     * @param group the group's instantiator
116     * @param incarnation the group's incarnation number
117     * @return monitor for activation group
118     * @exception UnknownGroupException if group is not registered
119     * @exception ActivationException if a group for the specified
120     * <code>id</code> is already active and that group is not equal
121     * to the specified <code>group</code> or that group has a different
122     * <code>incarnation</code> than the specified <code>group</code>
123     * @exception RemoteException if remote call fails
124     * @since 1.2
125     */
126    public ActivationMonitor activeGroup(ActivationGroupID id,
127                                         ActivationInstantiator group,
128                                         long incarnation)
129        throws UnknownGroupException, ActivationException, RemoteException;
130
131    /**
132     * Remove the activation group. An activation group makes this call back
133     * to inform the activator that the group should be removed (destroyed).
134     * If this call completes successfully, objects can no longer be
135     * registered or activated within the group. All information of the
136     * group and its associated objects is removed from the system.
137     *
138     * @param id the activation group's identifier
139     * @exception ActivationException if unregister fails (e.g., database
140     * update failure, etc).
141     * @exception UnknownGroupException if group is not registered
142     * @exception RemoteException if remote call fails
143     * @since 1.2
144     */
145    public void unregisterGroup(ActivationGroupID id)
146        throws ActivationException, UnknownGroupException, RemoteException;
147
148    /**
149     * Shutdown the activation system. Destroys all groups spawned by
150     * the activation daemon and exits the activation daemon.
151     * @exception RemoteException if failed to contact/shutdown the activation
152     * daemon
153     * @since 1.2
154     */
155    public void shutdown() throws RemoteException;
156
157    /**
158     * Set the activation descriptor, <code>desc</code> for the object with
159     * the activation identifier, <code>id</code>. The change will take
160     * effect upon subsequent activation of the object.
161     *
162     * @param id the activation identifier for the activatable object
163     * @param desc the activation descriptor for the activatable object
164     * @exception UnknownGroupException the group associated with
165     * <code>desc</code> is not a registered group
166     * @exception UnknownObjectException the activation <code>id</code>
167     * is not registered
168     * @exception ActivationException for general failure (e.g., unable
169     * to update log)
170     * @exception RemoteException if remote call fails
171     * @return the previous value of the activation descriptor
172     * @see #getActivationDesc
173     * @since 1.2
174     */
175    public ActivationDesc setActivationDesc(ActivationID id,
176                                            ActivationDesc desc)
177        throws ActivationException, UnknownObjectException,
178            UnknownGroupException, RemoteException;
179
180    /**
181     * Set the activation group descriptor, <code>desc</code> for the object
182     * with the activation group identifier, <code>id</code>. The change will
183     * take effect upon subsequent activation of the group.
184     *
185     * @param id the activation group identifier for the activation group
186     * @param desc the activation group descriptor for the activation group
187     * @exception UnknownGroupException the group associated with
188     * <code>id</code> is not a registered group
189     * @exception ActivationException for general failure (e.g., unable
190     * to update log)
191     * @exception RemoteException if remote call fails
192     * @return the previous value of the activation group descriptor
193     * @see #getActivationGroupDesc
194     * @since 1.2
195     */
196    public ActivationGroupDesc setActivationGroupDesc(ActivationGroupID id,
197                                                      ActivationGroupDesc desc)
198       throws ActivationException, UnknownGroupException, RemoteException;
199
200    /**
201     * Returns the activation descriptor, for the object with the activation
202     * identifier, <code>id</code>.
203     *
204     * @param id the activation identifier for the activatable object
205     * @exception UnknownObjectException if <code>id</code> is not registered
206     * @exception ActivationException for general failure
207     * @exception RemoteException if remote call fails
208     * @return the activation descriptor
209     * @see #setActivationDesc
210     * @since 1.2
211     */
212    public ActivationDesc getActivationDesc(ActivationID id)
213       throws ActivationException, UnknownObjectException, RemoteException;
214
215    /**
216     * Returns the activation group descriptor, for the group
217     * with the activation group identifier, <code>id</code>.
218     *
219     * @param id the activation group identifier for the group
220     * @exception UnknownGroupException if <code>id</code> is not registered
221     * @exception ActivationException for general failure
222     * @exception RemoteException if remote call fails
223     * @return the activation group descriptor
224     * @see #setActivationGroupDesc
225     * @since 1.2
226     */
227    public ActivationGroupDesc getActivationGroupDesc(ActivationGroupID id)
228       throws ActivationException, UnknownGroupException, RemoteException;
229}
230