Showing the changes to java/pkg/java/rmi/activation/ActivationSystem.java (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,229 @@ | ||
| 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 | + | |
| 26 | +package java.rmi.activation; | |
| 27 | + | |
| 28 | +import java.rmi.Remote; | |
| 29 | +import java.rmi.RemoteException; | |
| 30 | +import java.rmi.activation.UnknownGroupException; | |
| 31 | +import 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 | + */ | |
| 47 | +public 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. <p> | |
| 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 | +} | |