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 }