001 /* ActivationSystem.java -- registers groups and objects to be activated. 002 Copyright (c) 1996, 1997, 1998, 1999, 2004, 2006 003 Free Software Foundation, Inc. 004 005 This file is part of GNU Classpath. 006 007 GNU Classpath is free software; you can redistribute it and/or modify 008 it under the terms of the GNU General Public License as published by 009 the Free Software Foundation; either version 2, or (at your option) 010 any later version. 011 012 GNU Classpath is distributed in the hope that it will be useful, but 013 WITHOUT ANY WARRANTY; without even the implied warranty of 014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 015 General Public License for more details. 016 017 You should have received a copy of the GNU General Public License 018 along with GNU Classpath; see the file COPYING. If not, write to the 019 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 020 02110-1301 USA. 021 022 Linking this library statically or dynamically with other modules is 023 making a combined work based on this library. Thus, the terms and 024 conditions of the GNU General Public License cover the whole 025 combination. 026 027 As a special exception, the copyright holders of this library give you 028 permission to link this library with independent modules to produce an 029 executable, regardless of the license terms of these independent 030 modules, and to copy and distribute the resulting executable under 031 terms of your choice, provided that you also meet, for each linked 032 independent module, the terms and conditions of the license of that 033 module. An independent module is a module which is not derived from 034 or based on this library. If you modify this library, you may extend 035 this exception to your version of the library, but you are not 036 obligated to do so. If you do not wish to do so, delete this 037 exception statement from your version. */ 038 039 040 package java.rmi.activation; 041 042 import java.rmi.Remote; 043 import java.rmi.RemoteException; 044 045 /** 046 * <p> 047 * The ActivationSystem registers groups and activatable objects to be activated 048 * within those groups. The ActivationSystem cooperates with both the Activator, 049 * which activates objects registered via the ActivationSystem, and the 050 * ActivationMonitor, which obtains information about active and inactive 051 * objects and inactive groups. 052 * </p> 053 * <p> 054 * The activation system if frequently a remote object. As a security mean, all 055 * methods in this interface throw {@link java.rmi.AccessException} if called 056 * from the client that is not reside on the same host as the activation system. 057 * </p> 058 * @see ActivationGroup#getSystem() 059 */ 060 public interface ActivationSystem 061 extends Remote 062 { 063 /** 064 * The port, used by the activation system. The value is equal to 1098 by 065 * default, but it can be changed by putting the system property 066 * . 067 */ 068 int SYSTEM_PORT = 1098; 069 070 /** 071 * Registers the activation descriptor and creates (and returns) its 072 * activation identifier. The map entry (identifier to descriptor) is stored 073 * in the stable map and used when the {@link Activator} receives the request 074 * to activate the object. 075 * 076 * @param desc the activation descriptor to register. 077 * @return the created activation identifier that is mapped to the passed 078 * descriptor. 079 * @throws ActivationException if the registration fails (database update 080 * problems, etc). 081 * @throws UnknownGroupException the if group, specified in decriptor, is 082 * unknown. 083 * @throws RemoteException if the remote call fails. 084 */ 085 ActivationID registerObject(ActivationDesc desc) throws ActivationException, 086 UnknownGroupException, RemoteException; 087 088 /** 089 * Removes the stored identifier-description map entry. The object will no 090 * longer be activable using the passed activation id 091 * 092 * @param id the activation id to remove 093 * @throws ActivationException if the entry removing operation failed 094 * (database update problems, etc) 095 * @throws UnknownObjectException if the passed id is not known to the system 096 * @throws RemoteException if the remote call fails 097 */ 098 void unregisterObject(ActivationID id) throws ActivationException, 099 UnknownObjectException, RemoteException; 100 101 /** 102 * Register the new activation group. For instance, it can be one activation 103 * group per virtual machine. 104 * 105 * @param groupDesc the activation group descriptor. 106 * @return the created activation group ID for the activation group 107 * @throws ActivationException if the group registration fails 108 * @throws RemoteException if the remote call fails 109 */ 110 ActivationGroupID registerGroup(ActivationGroupDesc groupDesc) 111 throws ActivationException, RemoteException; 112 113 /** 114 * This method is called from the {@link ActivationGroup} to inform the 115 * ActivatinSystem that the group is now active and there is the 116 * {@link ActivationInstantiator} for that group. This call is made internally 117 * from the {@link ActivationGroup#createGroup}. 118 * 119 * @param id the group id 120 * @param group the group activation instantiator 121 * @param incarnation the groups incarnatin number. 122 * @return the activation monitor that should be informed about the group 123 * state changes 124 * @throws UnknownGroupException if this group has not been registered 125 * @throws ActivationException if this group is already active 126 * @throws RemoteException if the remote call fails 127 */ 128 ActivationMonitor activeGroup(ActivationGroupID id, 129 ActivationInstantiator group, long incarnation) 130 throws UnknownGroupException, ActivationException, RemoteException; 131 132 /** 133 * Removes the activation group with the given identifier. The group calls 134 * back, informing the activator about the shutdown. 135 * 136 * @param id the group activation id. 137 * @throws ActivationException if the database update fails 138 * @throws UnknownGroupException if such group is not registered 139 * @throws RemoteException if the remote call fails 140 */ 141 void unregisterGroup(ActivationGroupID id) throws ActivationException, 142 UnknownGroupException, RemoteException; 143 144 /** 145 * Shutdown the activation system and all associated activation groups 146 * 147 * @throws RemoteException if the remote call fails 148 */ 149 void shutdown() throws RemoteException; 150 151 /** 152 * Replace the activation descriptor for the object with the given activation 153 * id. 154 * 155 * @param id the activation id 156 * @param desc the new activation descriptor 157 * @return the previous activation descriptor for that object. 158 * @throws ActivationException if the database update fails 159 * @throws UnknownObjectException if the object with such id is not known 160 * @throws UnknownGroupException if the activation group (in desc) is not 161 * known. 162 * @throws RemoteException if the remote call fails 163 */ 164 ActivationDesc setActivationDesc(ActivationID id, ActivationDesc desc) 165 throws ActivationException, UnknownObjectException, 166 UnknownGroupException, RemoteException; 167 168 /** 169 * Replaces the group descriptor for the group with the given group activation 170 * id. 171 * 172 * @param groupId the group id 173 * @param groupDesc the new group descriptor 174 * @return the previous group descriptor 175 * @throws ActivationException if the database update fails 176 * @throws UnknownGroupException if such group is not known 177 * @throws RemoteException if the remote call fails 178 */ 179 ActivationGroupDesc setActivationGroupDesc(ActivationGroupID groupId, 180 ActivationGroupDesc groupDesc) 181 throws ActivationException, UnknownGroupException, RemoteException; 182 183 /** 184 * Get the activation descriptor for the object with the given activation id. 185 * 186 * @param id the object activation id 187 * @return the activation descriptor for that object 188 * @throws ActivationException if the database access fails 189 * @throws UnknownObjectException if this object is not known 190 * @throws RemoteException if the remote call fails 191 */ 192 ActivationDesc getActivationDesc(ActivationID id) throws ActivationException, 193 UnknownObjectException, RemoteException; 194 195 /** 196 * Get the group descriptor for the group with the given id. 197 * 198 * @param groupId the group id 199 * @return the group descriptor 200 * @throws ActivationException if the database access fails 201 * @throws UnknownGroupException if the group with such id is not known 202 * @throws RemoteException if the remote call fails 203 */ 204 ActivationGroupDesc getActivationGroupDesc(ActivationGroupID groupId) 205 throws ActivationException, UnknownGroupException, RemoteException; 206 }