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. 

  11. package java.rmi.activation;

  12. 

  13. import java.rmi.Remote;

  14. import java.rmi.RemoteException;

  15. import java.rmi.activation.UnknownGroupException;

  16. import java.rmi.activation.UnknownObjectException;

  17. 

  18. /**

  19.  * The <code>ActivationSystem</code> provides a means for registering

  20.  * groups and "activatable" objects to be activated within those groups.

  21.  * The <code>ActivationSystem</code> works closely with the

  22.  * <code>Activator</code>, which activates objects registered via the

  23.  * <code>ActivationSystem</code>, and the <code>ActivationMonitor</code>,

  24.  * which obtains information about active and inactive objects,

  25.  * and inactive groups.

  26.  *

  27.  * @author 	Ann Wollrath

  28.  * @version	1.13, 02/02/00

  29.  * @see		Activator

  30.  * @see		ActivationMonitor

  31.  * @since	1.2

  32.  */

  33. public interface ActivationSystem extends Remote {

  34. 

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

  36.     public static final int SYSTEM_PORT = 1098;

  37.     

  38.     /**

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

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

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

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

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

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

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

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

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

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

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

  50.      * the object. <p>

  51.      *

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

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

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

  55.      * update failure, etc).

  56.      * @exception UnknownGroupException if group referred to in

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

  58.      * @exception RemoteException if remote call fails

  59.      * @since 1.2

  60.      */

  61.     public ActivationID registerObject(ActivationDesc desc)

  62. 	throws ActivationException, UnknownGroupException, RemoteException;

  63.     

  64.     /**

  65.      * Remove the activation id and associated descriptor previously

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

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

  68.      *

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

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

  71.      * update failure, etc).

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

  73.      * @exception RemoteException if remote call fails

  74.      * @since 1.2

  75.      */

  76.     public void unregisterObject(ActivationID id)

  77. 	throws ActivationException, UnknownObjectException, RemoteException;

  78.     

  79.     /**

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

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

  82.      * can be registered within that group.

  83.      *

  84.      * @param desc the group's descriptor

  85.      * @return an identifier for the group

  86.      * @exception ActivationException if group registration fails

  87.      * @exception RemoteException if remote call fails

  88.      * @since 1.2

  89.      */

  90.     public ActivationGroupID registerGroup(ActivationGroupDesc desc)

  91. 	throws ActivationException, RemoteException;

  92. 

  93.     /**

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

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

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

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

  98.      * active.

  99.      *

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

  101.      * @param group the group's instantiator

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

  103.      * @return monitor for activation group

  104.      * @exception UnknownGroupException if group is not registered

  105.      * @exception ActivationException if group is already active

  106.      * @exception RemoteException if remote call fails

  107.      * @since 1.2

  108.      */

  109.     public ActivationMonitor activeGroup(ActivationGroupID id,

  110. 					 ActivationInstantiator group,

  111. 					 long incarnation)

  112. 	throws UnknownGroupException, ActivationException, RemoteException;

  113.     

  114.     /**

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

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

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

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

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

  120.      *

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

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

  123.      * update failure, etc).

  124.      * @exception UnknownGroupException if group is not registered

  125.      * @exception RemoteException if remote call fails

  126.      * @since 1.2

  127.      */

  128.     public void unregisterGroup(ActivationGroupID id)

  129. 	throws ActivationException, UnknownGroupException, RemoteException;

  130. 

  131.     /**

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

  133.      * the activation daemon and exits the activation daemon.

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

  135.      * daemon

  136.      * @since 1.2

  137.      */

  138.     public void shutdown() throws RemoteException;

  139. 

  140.     /**

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

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

  143.      * effect upon subsequent activation of the object.

  144.      *

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

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

  147.      * @exception UnknownGroupException the group associated with

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

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

  150.      * is not registered

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

  152.      * to update log)

  153.      * @exception RemoteException if remote call fails

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

  155.      * @since 1.2

  156.      */

  157.     public ActivationDesc setActivationDesc(ActivationID id,

  158. 					    ActivationDesc desc)

  159. 	throws ActivationException, UnknownObjectException,

  160. 	    UnknownGroupException, RemoteException;

  161. 

  162.     /**

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

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

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

  166.      * 

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

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

  169.      * @exception UnknownGroupException the group associated with

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

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

  172.      * to update log)

  173.      * @exception RemoteException if remote call fails

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

  175.      * @since 1.2

  176.      */

  177.     public ActivationGroupDesc setActivationGroupDesc(ActivationGroupID id,

  178. 						      ActivationGroupDesc desc)

  179.        throws ActivationException, UnknownGroupException, RemoteException;

  180. 

  181.     /**

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

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

  184.      * 

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

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

  187.      * @exception ActivationException for general failure

  188.      * @exception RemoteException if remote call fails

  189.      * @return the activation descriptor

  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.      * @since 1.2

  205.      */

  206.     public ActivationGroupDesc getActivationGroupDesc(ActivationGroupID id)

  207.        throws ActivationException, UnknownGroupException, RemoteException;

  208. }