Source for java.rmi.activation.ActivationSystem

   1: /* ActivationSystem.java -- registers groups and objects to be activated.
   2:    Copyright (c) 1996, 1997, 1998, 1999, 2004, 2006
   3:    Free Software Foundation, Inc.
   4: 
   5: This file is part of GNU Classpath.
   6: 
   7: GNU Classpath is free software; you can redistribute it and/or modify
   8: it under the terms of the GNU General Public License as published by
   9: the Free Software Foundation; either version 2, or (at your option)
  10: any later version.
  11:  
  12: GNU Classpath is distributed in the hope that it will be useful, but
  13: WITHOUT ANY WARRANTY; without even the implied warranty of
  14: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15: General Public License for more details.
  16: 
  17: You should have received a copy of the GNU General Public License
  18: along with GNU Classpath; see the file COPYING.  If not, write to the
  19: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20: 02110-1301 USA.
  21: 
  22: Linking this library statically or dynamically with other modules is
  23: making a combined work based on this library.  Thus, the terms and
  24: conditions of the GNU General Public License cover the whole
  25: combination.
  26: 
  27: As a special exception, the copyright holders of this library give you
  28: permission to link this library with independent modules to produce an
  29: executable, regardless of the license terms of these independent
  30: modules, and to copy and distribute the resulting executable under
  31: terms of your choice, provided that you also meet, for each linked
  32: independent module, the terms and conditions of the license of that
  33: module.  An independent module is a module which is not derived from
  34: or based on this library.  If you modify this library, you may extend
  35: this exception to your version of the library, but you are not
  36: obligated to do so.  If you do not wish to do so, delete this
  37: exception statement from your version. */
  38: 
  39: 
  40: package java.rmi.activation;
  41: 
  42: import java.rmi.Remote;
  43: import java.rmi.RemoteException;
  44: 
  45: /**
  46:  * <p>
  47:  * The ActivationSystem registers groups and activatable objects to be activated
  48:  * within those groups. The ActivationSystem cooperates with both the Activator,
  49:  * which activates objects registered via the ActivationSystem, and the
  50:  * ActivationMonitor, which obtains information about active and inactive
  51:  * objects and inactive groups.
  52:  * </p>
  53:  * <p>
  54:  * The activation system if frequently a remote object. As a security mean, all
  55:  * methods in this interface throw {@link java.rmi.AccessException} if called
  56:  * from the client that is not reside on the same host as the activation system.
  57:  * </p>
  58:  * @see ActivationGroup#getSystem()
  59:  */
  60: public interface ActivationSystem
  61:     extends Remote
  62: {
  63:   /**
  64:    * The port, used by the activation system. The value is equal to 1098 by
  65:    * default, but it can be changed by putting the system property
  66:    * .
  67:    */
  68:   int SYSTEM_PORT = 1098;
  69:   
  70:   /**
  71:    * Registers the activation descriptor and creates (and returns) its
  72:    * activation identifier. The map entry (identifier to descriptor) is stored
  73:    * in the stable map and used when the {@link Activator} receives the request
  74:    * to activate the object.
  75:    * 
  76:    * @param desc the activation descriptor to register.
  77:    * @return the created activation identifier that is mapped to the passed
  78:    *         descriptor.
  79:    * @throws ActivationException if the registration fails (database update
  80:    *           problems, etc).
  81:    * @throws UnknownGroupException the if group, specified in decriptor, is
  82:    *           unknown.
  83:    * @throws RemoteException if the remote call fails.
  84:    */
  85:   ActivationID registerObject(ActivationDesc desc) throws ActivationException,
  86:       UnknownGroupException, RemoteException;
  87:   
  88:   /**
  89:    * Removes the stored identifier-description map entry. The object will no
  90:    * longer be activable using the passed activation id
  91:    * 
  92:    * @param id the activation id to remove
  93:    * @throws ActivationException if the entry removing operation failed
  94:    *           (database update problems, etc)
  95:    * @throws UnknownObjectException if the passed id is not known to the system
  96:    * @throws RemoteException if the remote call fails
  97:    */
  98:   void unregisterObject(ActivationID id) throws ActivationException,
  99:       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: }