libjava/classpath/java/rmi/activation/ActivationSystem.java

   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 }