1. /*

  2.  * @(#)ActivationSystem.java	1.18 03/12/19

  3.  *

  4.  * Copyright 2004 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.18, 12/19/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 a group for the specified

  103.      * <code>id</code> is already active and that group is not equal

  104.      * to the specified <code>group</code> or that group has a different

  105.      * <code>incarnation</code> than the specified <code>group</code>

  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.      * @see #getActivationDesc

  156.      * @since 1.2

  157.      */

  158.     public ActivationDesc setActivationDesc(ActivationID id,

  159. 					    ActivationDesc desc)

  160. 	throws ActivationException, UnknownObjectException,

  161. 	    UnknownGroupException, RemoteException;

  162. 

  163.     /**

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

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

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

  167.      * 

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

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

  170.      * @exception UnknownGroupException the group associated with

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

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

  173.      * to update log)

  174.      * @exception RemoteException if remote call fails

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

  176.      * @see #getActivationGroupDesc

  177.      * @since 1.2

  178.      */

  179.     public ActivationGroupDesc setActivationGroupDesc(ActivationGroupID id,

  180. 						      ActivationGroupDesc desc)

  181.        throws ActivationException, UnknownGroupException, RemoteException;

  182. 

  183.     /**

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

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

  186.      * 

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

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

  189.      * @exception ActivationException for general failure

  190.      * @exception RemoteException if remote call fails

  191.      * @return the activation descriptor

  192.      * @see #setActivationDesc

  193.      * @since 1.2

  194.      */

  195.     public ActivationDesc getActivationDesc(ActivationID id)

  196.        throws ActivationException, UnknownObjectException, RemoteException;

  197. 	      

  198.     /**

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

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

  201.      * 

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

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

  204.      * @exception ActivationException for general failure

  205.      * @exception RemoteException if remote call fails

  206.      * @return the activation group descriptor

  207.      * @see #setActivationGroupDesc

  208.      * @since 1.2

  209.      */

  210.     public ActivationGroupDesc getActivationGroupDesc(ActivationGroupID id)

  211.        throws ActivationException, UnknownGroupException, RemoteException;

  212. }