001 /*
002 * Copyright 1997-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.rmi.activation;
027
028 import java.rmi.Remote;
029 import java.rmi.RemoteException;
030 import java.rmi.activation.UnknownGroupException;
031 import java.rmi.activation.UnknownObjectException;
032
033 /**
034 * The <code>ActivationSystem</code> provides a means for registering
035 * groups and "activatable" objects to be activated within those groups.
036 * The <code>ActivationSystem</code> works closely with the
037 * <code>Activator</code>, which activates objects registered via the
038 * <code>ActivationSystem</code>, and the <code>ActivationMonitor</code>,
039 * which obtains information about active and inactive objects,
040 * and inactive groups.
041 *
042 * @author Ann Wollrath
043 * @version 1.25, 05/05/07
044 * @see Activator
045 * @see ActivationMonitor
046 * @since 1.2
047 */
048 public interface ActivationSystem extends Remote {
049
050 /** The port to lookup the activation system. */
051 public static final int SYSTEM_PORT = 1098;
052
053 /**
054 * The <code>registerObject</code> method is used to register an
055 * activation descriptor, <code>desc</code>, and obtain an
056 * activation identifier for a activatable remote object. The
057 * <code>ActivationSystem</code> creates an
058 * <code>ActivationID</code> (a activation identifier) for the
059 * object specified by the descriptor, <code>desc</code>, and
060 * records, in stable storage, the activation descriptor and its
061 * associated identifier for later use. When the <code>Activator</code>
062 * receives an <code>activate</code> request for a specific identifier, it
063 * looks up the activation descriptor (registered previously) for
064 * the specified identifier and uses that information to activate
065 * the object. <p>
066 *
067 * @param desc the object's activation descriptor
068 * @return the activation id that can be used to activate the object
069 * @exception ActivationException if registration fails (e.g., database
070 * update failure, etc).
071 * @exception UnknownGroupException if group referred to in
072 * <code>desc</code> is not registered with this system
073 * @exception RemoteException if remote call fails
074 * @since 1.2
075 */
076 public ActivationID registerObject(ActivationDesc desc)
077 throws ActivationException, UnknownGroupException,
078 RemoteException;
079
080 /**
081 * Remove the activation id and associated descriptor previously
082 * registered with the <code>ActivationSystem</code>; the object
083 * can no longer be activated via the object's activation id.
084 *
085 * @param id the object's activation id (from previous registration)
086 * @exception ActivationException if unregister fails (e.g., database
087 * update failure, etc).
088 * @exception UnknownObjectException if object is unknown (not registered)
089 * @exception RemoteException if remote call fails
090 * @since 1.2
091 */
092 public void unregisterObject(ActivationID id)
093 throws ActivationException, UnknownObjectException,
094 RemoteException;
095
096 /**
097 * Register the activation group. An activation group must be
098 * registered with the <code>ActivationSystem</code> before objects
099 * can be registered within that group.
100 *
101 * @param desc the group's descriptor
102 * @return an identifier for the group
103 * @exception ActivationException if group registration fails
104 * @exception RemoteException if remote call fails
105 * @since 1.2
106 */
107 public ActivationGroupID registerGroup(ActivationGroupDesc desc)
108 throws ActivationException, RemoteException;
109
110 /**
111 * Callback to inform activation system that group is now
112 * active. This call is made internally by the
113 * <code>ActivationGroup.createGroup</code> method to inform
114 * the <code>ActivationSystem</code> that the group is now
115 * active.
116 *
117 * @param id the activation group's identifier
118 * @param group the group's instantiator
119 * @param incarnation the group's incarnation number
120 * @return monitor for activation group
121 * @exception UnknownGroupException if group is not registered
122 * @exception ActivationException if a group for the specified
123 * <code>id</code> is already active and that group is not equal
124 * to the specified <code>group</code> or that group has a different
125 * <code>incarnation</code> than the specified <code>group</code>
126 * @exception RemoteException if remote call fails
127 * @since 1.2
128 */
129 public ActivationMonitor activeGroup(ActivationGroupID id,
130 ActivationInstantiator group, long incarnation)
131 throws UnknownGroupException, ActivationException,
132 RemoteException;
133
134 /**
135 * Remove the activation group. An activation group makes this call back
136 * to inform the activator that the group should be removed (destroyed).
137 * If this call completes successfully, objects can no longer be
138 * registered or activated within the group. All information of the
139 * group and its associated objects is removed from the system.
140 *
141 * @param id the activation group's identifier
142 * @exception ActivationException if unregister fails (e.g., database
143 * update failure, etc).
144 * @exception UnknownGroupException if group is not registered
145 * @exception RemoteException if remote call fails
146 * @since 1.2
147 */
148 public void unregisterGroup(ActivationGroupID id)
149 throws ActivationException, UnknownGroupException,
150 RemoteException;
151
152 /**
153 * Shutdown the activation system. Destroys all groups spawned by
154 * the activation daemon and exits the activation daemon.
155 * @exception RemoteException if failed to contact/shutdown the activation
156 * daemon
157 * @since 1.2
158 */
159 public void shutdown() throws RemoteException;
160
161 /**
162 * Set the activation descriptor, <code>desc</code> for the object with
163 * the activation identifier, <code>id</code>. The change will take
164 * effect upon subsequent activation of the object.
165 *
166 * @param id the activation identifier for the activatable object
167 * @param desc the activation descriptor for the activatable object
168 * @exception UnknownGroupException the group associated with
169 * <code>desc</code> is not a registered group
170 * @exception UnknownObjectException the activation <code>id</code>
171 * is not registered
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 descriptor
176 * @see #getActivationDesc
177 * @since 1.2
178 */
179 public ActivationDesc setActivationDesc(ActivationID id,
180 ActivationDesc desc) throws ActivationException,
181 UnknownObjectException, UnknownGroupException,
182 RemoteException;
183
184 /**
185 * Set the activation group descriptor, <code>desc</code> for the object
186 * with the activation group identifier, <code>id</code>. The change will
187 * take effect upon subsequent activation of the group.
188 *
189 * @param id the activation group identifier for the activation group
190 * @param desc the activation group descriptor for the activation group
191 * @exception UnknownGroupException the group associated with
192 * <code>id</code> is not a registered group
193 * @exception ActivationException for general failure (e.g., unable
194 * to update log)
195 * @exception RemoteException if remote call fails
196 * @return the previous value of the activation group descriptor
197 * @see #getActivationGroupDesc
198 * @since 1.2
199 */
200 public ActivationGroupDesc setActivationGroupDesc(
201 ActivationGroupID id, ActivationGroupDesc desc)
202 throws ActivationException, UnknownGroupException,
203 RemoteException;
204
205 /**
206 * Returns the activation descriptor, for the object with the activation
207 * identifier, <code>id</code>.
208 *
209 * @param id the activation identifier for the activatable object
210 * @exception UnknownObjectException if <code>id</code> is not registered
211 * @exception ActivationException for general failure
212 * @exception RemoteException if remote call fails
213 * @return the activation descriptor
214 * @see #setActivationDesc
215 * @since 1.2
216 */
217 public ActivationDesc getActivationDesc(ActivationID id)
218 throws ActivationException, UnknownObjectException,
219 RemoteException;
220
221 /**
222 * Returns the activation group descriptor, for the group
223 * with the activation group identifier, <code>id</code>.
224 *
225 * @param id the activation group identifier for the group
226 * @exception UnknownGroupException if <code>id</code> is not registered
227 * @exception ActivationException for general failure
228 * @exception RemoteException if remote call fails
229 * @return the activation group descriptor
230 * @see #setActivationGroupDesc
231 * @since 1.2
232 */
233 public ActivationGroupDesc getActivationGroupDesc(
234 ActivationGroupID id) throws ActivationException,
235 UnknownGroupException, RemoteException;
236 }
|