1. /*

  2.  * @(#)ActivationSystem.java	1.16 03/01/23

  3.  *

  4.  * Copyright 2003 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.rmi.activation;

  9. 

  10. import java.rmi.Remote;

  11. import java.rmi.RemoteException;

  12. import java.rmi.activation.UnknownGroupException;

  13. import java.rmi.activation.UnknownObjectException;

  14. 

  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.16, 01/23/03

  26.  * @see		Activator

  27.  * @see		ActivationMonitor

  28.  * @since	1.2

  29.  */

  30. public interface ActivationSystem extends Remote {

  31. 

  32.     /** The port to lookup the activation system. */

  33.     public static final int SYSTEM_PORT = 1098;

  34.     

  35.     /**

  36.      * The <code>registerObject</code> method is used to register an

  37.      * activation descriptor, <code>desc</code>, and obtain an

  38.      * activation identifier for a activatable remote object. The

  39.      * <code>ActivationSystem</code> creates an

  40.      * <code>ActivationID</code> (a activation identifier) for the

  41.      * object specified by the descriptor, <code>desc</code>, and

  42.      * records, in stable storage, the activation descriptor and its

  43.      * associated identifier for later use. When the <code>Activator</code>

  44.      * receives an <code>activate</code> request for a specific identifier, it

  45.      * looks up the activation descriptor (registered previously) for

  46.      * the specified identifier and uses that information to activate

  47.      * the object. <p>

  48.      *

  49.      * @param desc the object's activation descriptor

  50.      * @return the activation id that can be used to activate the object

  51.      * @exception ActivationException if registration fails (e.g., database

  52.      * update failure, etc).

  53.      * @exception UnknownGroupException if group referred to in

  54.      * <code>desc</code> is not registered with this system

  55.      * @exception RemoteException if remote call fails

  56.      * @since 1.2

  57.      */

  58.     public ActivationID registerObject(ActivationDesc desc)

  59. 	throws ActivationException, UnknownGroupException, RemoteException;

  60.     

  61.     /**

  62.      * Remove the activation id and associated descriptor previously

  63.      * registered with the <code>ActivationSystem</code> the object

  64.      * can no longer be activated via the object's activation id.

  65.      *

  66.      * @param id the object's activation id (from previous registration)

  67.      * @exception ActivationException if unregister fails (e.g., database

  68.      * update failure, etc).

  69.      * @exception UnknownObjectException if object is unknown (not registered)

  70.      * @exception RemoteException if remote call fails

  71.      * @since 1.2

  72.      */

  73.     public void unregisterObject(ActivationID id)

  74. 	throws ActivationException, UnknownObjectException, RemoteException;

  75.     

  76.     /**

  77.      * Register the activation group. An activation group must be

  78.      * registered with the <code>ActivationSystem</code> before objects

  79.      * can be registered within that group.

  80.      *

  81.      * @param desc the group's descriptor

  82.      * @return an identifier for the group

  83.      * @exception ActivationException if group registration fails

  84.      * @exception RemoteException if remote call fails

  85.      * @since 1.2

  86.      */

  87.     public ActivationGroupID registerGroup(ActivationGroupDesc desc)

  88. 	throws ActivationException, RemoteException;

  89. 

  90.     /**

  91.      * Callback to inform activation system that group is now

  92.      * active. This call is made internally by the

  93.      * <code>ActivationGroup.createGroup</code> method to inform

  94.      * the <code>ActivationSystem</code> that the group is now

  95.      * active.

  96.      *

  97.      * @param id the activation group's identifier

  98.      * @param group the group's instantiator

  99.      * @param incarnation the group's incarnation number

  100.      * @return monitor for activation group

  101.      * @exception UnknownGroupException if group is not registered

  102.      * @exception ActivationException if group is already active

  103.      * @exception RemoteException if remote call fails

  104.      * @since 1.2

  105.      */

  106.     public ActivationMonitor activeGroup(ActivationGroupID id,

  107. 					 ActivationInstantiator group,

  108. 					 long incarnation)

  109. 	throws UnknownGroupException, ActivationException, RemoteException;

  110.     

  111.     /**

  112.      * Remove the activation group. An activation group makes this call back

  113.      * to inform the activator that the group should be removed (destroyed).

  114.      * If this call completes successfully, objects can no longer be

  115.      * registered or activated within the group. All information of the

  116.      * group and its associated objects is removed from the system.

  117.      *

  118.      * @param id the activation group's identifier

  119.      * @exception ActivationException if unregister fails (e.g., database

  120.      * update failure, etc).

  121.      * @exception UnknownGroupException if group is not registered

  122.      * @exception RemoteException if remote call fails

  123.      * @since 1.2

  124.      */

  125.     public void unregisterGroup(ActivationGroupID id)

  126. 	throws ActivationException, UnknownGroupException, RemoteException;

  127. 

  128.     /**

  129.      * Shutdown the activation system. Destroys all groups spawned by

  130.      * the activation daemon and exits the activation daemon.

  131.      * @exception RemoteException if failed to contact/shutdown the activation

  132.      * daemon

  133.      * @since 1.2

  134.      */

  135.     public void shutdown() throws RemoteException;

  136. 

  137.     /**

  138.      * Set the activation descriptor, <code>desc</code> for the object with

  139.      * the activation identifier, <code>id</code>. The change will take

  140.      * effect upon subsequent activation of the object.

  141.      *

  142.      * @param id the activation identifier for the activatable object

  143.      * @param desc the activation descriptor for the activatable object

  144.      * @exception UnknownGroupException the group associated with

  145.      * <code>desc</code> is not a registered group

  146.      * @exception UnknownObjectException the activation <code>id</code>

  147.      * is not registered

  148.      * @exception ActivationException for general failure (e.g., unable

  149.      * to update log)

  150.      * @exception RemoteException if remote call fails

  151.      * @return the previous value of the activation descriptor

  152.      * @see #getActivationDesc

  153.      * @since 1.2

  154.      */

  155.     public ActivationDesc setActivationDesc(ActivationID id,

  156. 					    ActivationDesc desc)

  157. 	throws ActivationException, UnknownObjectException,

  158. 	    UnknownGroupException, RemoteException;

  159. 

  160.     /**

  161.      * Set the activation group descriptor, <code>desc</code> for the object

  162.      * with the activation group identifier, <code>id</code>. The change will

  163.      * take effect upon subsequent activation of the group.

  164.      * 

  165.      * @param id the activation group identifier for the activation group

  166.      * @param desc the activation group descriptor for the activation group

  167.      * @exception UnknownGroupException the group associated with

  168.      * <code>id</code> is not a registered group

  169.      * @exception ActivationException for general failure (e.g., unable

  170.      * to update log)

  171.      * @exception RemoteException if remote call fails

  172.      * @return the previous value of the activation group descriptor

  173.      * @see #getActivationGroupDesc

  174.      * @since 1.2

  175.      */

  176.     public ActivationGroupDesc setActivationGroupDesc(ActivationGroupID id,

  177. 						      ActivationGroupDesc desc)

  178.        throws ActivationException, UnknownGroupException, RemoteException;

  179. 

  180.     /**

  181.      * Returns the activation descriptor, for the object with the activation

  182.      * identifier, <code>id</code>.

  183.      * 

  184.      * @param id the activation identifier for the activatable object

  185.      * @exception UnknownObjectException if <code>id</code> is not registered

  186.      * @exception ActivationException for general failure

  187.      * @exception RemoteException if remote call fails

  188.      * @return the activation descriptor

  189.      * @see #setActivationDesc

  190.      * @since 1.2

  191.      */

  192.     public ActivationDesc getActivationDesc(ActivationID id)

  193.        throws ActivationException, UnknownObjectException, RemoteException;

  194. 	      

  195.     /**

  196.      * Returns the activation group descriptor, for the group

  197.      * with the activation group identifier, <code>id</code>. 

  198.      * 

  199.      * @param id the activation group identifier for the group

  200.      * @exception UnknownGroupException if <code>id</code> is not registered

  201.      * @exception ActivationException for general failure

  202.      * @exception RemoteException if remote call fails

  203.      * @return the activation group descriptor

  204.      * @see #setActivationGroupDesc

  205.      * @since 1.2

  206.      */

  207.     public ActivationGroupDesc getActivationGroupDesc(ActivationGroupID id)

  208.        throws ActivationException, UnknownGroupException, RemoteException;

  209. }