7.4.2 The ActivationSystem Interface

The ActivationSystem provides a means for registering groups and activatable objects to be activated within those groups. The ActivationSystem works closely with both the Activator, which activates objects registered via the ActivationSystem, and the ActivationMonitor, which obtains information about active and inactive objects and inactive groups.

package java.rmi.activation;

public interface ActivationSystem extends java.rmi.Remote

{

	public static final int SYSTEM_PORT = 1098;



	ActivationGroupID registerGroup(ActivationGroupDesc desc)

		throws ActivationException, java.rmi.RemoteException;



	ActivationMonitor activeGroup(ActivationGroupID id,

									ActivationInstantiator group,

									long incarnation)

		throws UnknownGroupException, ActivationException,

			   java.rmi.RemoteException;



	void unregisterGroup(ActivationGroupID id)

		throws ActivationException, UnknownGroupException,

			   java.rmi.RemoteException;



	ActivationID registerObject(ActivationDesc desc)

		throws ActivationException, UnknownGroupException,

			   java.rmi.RemoteException;



	void unregisterObject(ActivationID id)

		throws ActivationException, UnknownObjectException,

			   java.rmi.RemoteException;

}

---

Note - As a security measure, all of the above methods (registerGroup, activeGroup, unregisterGroup, registerObject, and unregisterObject) will throw java.rmi.AccessException, a subclass of java.rmi.RemoteException if called from a client that does not reside on the same host as the activation system.

---

The registerObject method is used to register an activation descriptor, desc, and obtain a activation identifier for an activatable remote object. The ActivationSystem creates an ActivationID (a activation identifier) for the object specified by the descriptor, desc, and records, in stable storage, the activation descriptor and its associated identifier for later use. When the Activator receives an activate request for a specific identifier, it looks up the activation descriptor (registered previously) for the specified identifier and uses that information to activate the object. If the group referred to in desc is not registered with this system, then the method throws UnknownGroupException. If registration fails (e.g., database update failure, etc), then the method throws ActivationException. If the remote call fails, then RemoteException is thrown.

The unregisterObject method removes the activation identifier, id, and associated descriptor previously registered with the ActivationSystem. After the call completes, the object can no longer be activated via the object's activation id. If the object id is unknown (not registered) the method throws UnknownObjectException. If the unregister operation fails (e.g., database update failure, etc), then the method throws ActivationException. If the remote call fails, then RemoteException is thrown.

The registerGroup method registers the activation group specified by the group descriptor, desc, with the activation system and returns the ActivationGroupID assigned to that group. An activation group must be registered with the ActivationSystem before objects can be registered within that group. If group registration fails, the method throws ActivationException. If the remote call fails then RemoteException is thrown.

The activeGroup method is a call back from the ActivationGroup (with the identifier, id), to inform the activation system that group is now active and is the ActivationInstantiator for that VM. This call is made internally by the ActivationGroup.createGroup method to obtain an ActivationMonitor that the group uses to update the system regarding objects' and the group's status (i.e., that the group or objects within that group have become inactive). If the group is not registered, then the method throws UnknownGroupException. If the group is already active, then ActivationException is thrown. If the remote call to the activation system fails, then RemoteException is thrown.

The unregisterGroup method removes the activation group with identifier, id, from the activation system. An activation group makes this call back to inform the activator that the group should be destroyed. If this call completes successfully, objects can no longer be registered or activated within the group. All information of the group and its associated objects is removed from the system. The method throws UnknownGroupException if the group is not registered. If the remote call fails, then RemoteException is thrown. If the unregister fails, ActivationException is thrown (e.g., database update failure, etc.).