1. /*
  2. * @(#)ActivationSystem.java 1.13 00/02/02
  3. *
  4. * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.
  5. *
  6. * This software is the proprietary information of Sun Microsystems, Inc.
  7. * Use is subject to license terms.
  8. *
  9. */
  10. package java.rmi.activation;
  11. import java.rmi.Remote;
  12. import java.rmi.RemoteException;
  13. import java.rmi.activation.UnknownGroupException;
  14. import java.rmi.activation.UnknownObjectException;
  15. /**
  16. * The <code>ActivationSystem</code> provides a means for registering
  17. * groups and "activatable" objects to be activated within those groups.
  18. * The <code>ActivationSystem</code> works closely with the
  19. * <code>Activator</code>, which activates objects registered via the
  20. * <code>ActivationSystem</code>, and the <code>ActivationMonitor</code>,
  21. * which obtains information about active and inactive objects,
  22. * and inactive groups.
  23. *
  24. * @author Ann Wollrath
  25. * @version 1.13, 02/02/00
  26. * @see Activator
  27. * @see ActivationMonitor
  28. * @since 1.2
  29. */
  30. public interface ActivationSystem extends Remote {
  31. /** The port to lookup the activation system. */
  32. public static final int SYSTEM_PORT = 1098;
  33. /**
  34. * The <code>registerObject</code> method is used to register an
  35. * activation descriptor, <code>desc</code>, and obtain an
  36. * activation identifier for a activatable remote object. The
  37. * <code>ActivationSystem</code> creates an
  38. * <code>ActivationID</code> (a activation identifier) for the
  39. * object specified by the descriptor, <code>desc</code>, and
  40. * records, in stable storage, the activation descriptor and its
  41. * associated identifier for later use. When the <code>Activator</code>
  42. * receives an <code>activate</code> request for a specific identifier, it
  43. * looks up the activation descriptor (registered previously) for
  44. * the specified identifier and uses that information to activate
  45. * the object. <p>
  46. *
  47. * @param desc the object's activation descriptor
  48. * @return the activation id that can be used to activate the object
  49. * @exception ActivationException if registration fails (e.g., database
  50. * update failure, etc).
  51. * @exception UnknownGroupException if group referred to in
  52. * <code>desc</code> is not registered with this system
  53. * @exception RemoteException if remote call fails
  54. * @since 1.2
  55. */
  56. public ActivationID registerObject(ActivationDesc desc)
  57. throws ActivationException, UnknownGroupException, RemoteException;
  58. /**
  59. * Remove the activation id and associated descriptor previously
  60. * registered with the <code>ActivationSystem</code> the object
  61. * can no longer be activated via the object's activation id.
  62. *
  63. * @param id the object's activation id (from previous registration)
  64. * @exception ActivationException if unregister fails (e.g., database
  65. * update failure, etc).
  66. * @exception UnknownObjectException if object is unknown (not registered)
  67. * @exception RemoteException if remote call fails
  68. * @since 1.2
  69. */
  70. public void unregisterObject(ActivationID id)
  71. throws ActivationException, UnknownObjectException, RemoteException;
  72. /**
  73. * Register the activation group. An activation group must be
  74. * registered with the <code>ActivationSystem</code> before objects
  75. * can be registered within that group.
  76. *
  77. * @param desc the group's descriptor
  78. * @return an identifier for the group
  79. * @exception ActivationException if group registration fails
  80. * @exception RemoteException if remote call fails
  81. * @since 1.2
  82. */
  83. public ActivationGroupID registerGroup(ActivationGroupDesc desc)
  84. throws ActivationException, RemoteException;
  85. /**
  86. * Callback to inform activation system that group is now
  87. * active. This call is made internally by the
  88. * <code>ActivationGroup.createGroup</code> method to inform
  89. * the <code>ActivationSystem</code> that the group is now
  90. * active.
  91. *
  92. * @param id the activation group's identifier
  93. * @param group the group's instantiator
  94. * @param incarnation the group's incarnation number
  95. * @return monitor for activation group
  96. * @exception UnknownGroupException if group is not registered
  97. * @exception ActivationException if group is already active
  98. * @exception RemoteException if remote call fails
  99. * @since 1.2
  100. */
  101. public ActivationMonitor activeGroup(ActivationGroupID id,
  102. ActivationInstantiator group,
  103. long incarnation)
  104. throws UnknownGroupException, ActivationException, RemoteException;
  105. /**
  106. * Remove the activation group. An activation group makes this call back
  107. * to inform the activator that the group should be removed (destroyed).
  108. * If this call completes successfully, objects can no longer be
  109. * registered or activated within the group. All information of the
  110. * group and its associated objects is removed from the system.
  111. *
  112. * @param id the activation group's identifier
  113. * @exception ActivationException if unregister fails (e.g., database
  114. * update failure, etc).
  115. * @exception UnknownGroupException if group is not registered
  116. * @exception RemoteException if remote call fails
  117. * @since 1.2
  118. */
  119. public void unregisterGroup(ActivationGroupID id)
  120. throws ActivationException, UnknownGroupException, RemoteException;
  121. /**
  122. * Shutdown the activation system. Destroys all groups spawned by
  123. * the activation daemon and exits the activation daemon.
  124. * @exception RemoteException if failed to contact/shutdown the activation
  125. * daemon
  126. * @since 1.2
  127. */
  128. public void shutdown() throws RemoteException;
  129. /**
  130. * Set the activation descriptor, <code>desc</code> for the object with
  131. * the activation identifier, <code>id</code>. The change will take
  132. * effect upon subsequent activation of the object.
  133. *
  134. * @param id the activation identifier for the activatable object
  135. * @param desc the activation descriptor for the activatable object
  136. * @exception UnknownGroupException the group associated with
  137. * <code>desc</code> is not a registered group
  138. * @exception UnknownObjectException the activation <code>id</code>
  139. * is not registered
  140. * @exception ActivationException for general failure (e.g., unable
  141. * to update log)
  142. * @exception RemoteException if remote call fails
  143. * @return the previous value of the activation descriptor
  144. * @since 1.2
  145. */
  146. public ActivationDesc setActivationDesc(ActivationID id,
  147. ActivationDesc desc)
  148. throws ActivationException, UnknownObjectException,
  149. UnknownGroupException, RemoteException;
  150. /**
  151. * Set the activation group descriptor, <code>desc</code> for the object
  152. * with the activation group identifier, <code>id</code>. The change will
  153. * take effect upon subsequent activation of the group.
  154. *
  155. * @param id the activation group identifier for the activation group
  156. * @param desc the activation group descriptor for the activation group
  157. * @exception UnknownGroupException the group associated with
  158. * <code>id</code> is not a registered group
  159. * @exception ActivationException for general failure (e.g., unable
  160. * to update log)
  161. * @exception RemoteException if remote call fails
  162. * @return the previous value of the activation group descriptor
  163. * @since 1.2
  164. */
  165. public ActivationGroupDesc setActivationGroupDesc(ActivationGroupID id,
  166. ActivationGroupDesc desc)
  167. throws ActivationException, UnknownGroupException, RemoteException;
  168. /**
  169. * Returns the activation descriptor, for the object with the activation
  170. * identifier, <code>id</code>.
  171. *
  172. * @param id the activation identifier for the activatable object
  173. * @exception UnknownObjectException if <code>id</code> is not registered
  174. * @exception ActivationException for general failure
  175. * @exception RemoteException if remote call fails
  176. * @return the activation descriptor
  177. * @since 1.2
  178. */
  179. public ActivationDesc getActivationDesc(ActivationID id)
  180. throws ActivationException, UnknownObjectException, RemoteException;
  181. /**
  182. * Returns the activation group descriptor, for the group
  183. * with the activation group identifier, <code>id</code>.
  184. *
  185. * @param id the activation group identifier for the group
  186. * @exception UnknownGroupException if <code>id</code> is not registered
  187. * @exception ActivationException for general failure
  188. * @exception RemoteException if remote call fails
  189. * @return the activation group descriptor
  190. * @since 1.2
  191. */
  192. public ActivationGroupDesc getActivationGroupDesc(ActivationGroupID id)
  193. throws ActivationException, UnknownGroupException, RemoteException;
  194. }