7.4.7 The ActivationGroup Class

An ActivationGroup is responsible for creating new instances of "activatable" objects in its group, informing its ActivationMonitor when either: its objects become active or inactive, or the group as a whole becomes inactive.

An ActivationGroup is initially created in one of several ways:

• as a side-effect of creating a "default" ActivationDesc for an object, or
• by an explicit call to the ActivationGroup.createGroup method, or
• as a side-effect of activating the first object in a group whose ActivationGroupDesc was only registered.

Only the activator can recreate an ActivationGroup. The activator spawns, as needed, a separate VM (as a child process, for example) for each registered activation group and directs activation requests to the appropriate group. It is implementation specific how VMs are spawned. An activation group is created via the ActivationGroup.createGroup static method. The createGroup method has two requirements on the group to be created: 1) the group must be a concrete subclass of ActivationGroup, and 2) the group must have a constructor that takes two arguments:

• the group's ActivationGroupID, and
• the group's initialization data (in a MarshalledObject)

When created, the default implementation of ActivationGroup will set the system properties to the system properties in force when it ActivationGroupDesc was created, and will set the security manager to the java.rmi.RMISecurityManager. If your application requires some specific properties to be set when objects are activated in the group, the application should set the properties before creating any ActivationDescs (before the default ActivationGroupDesc is created).

If your application requires the use of a security manager other than the RMISecurityManager, you must set the following two properties to specify the SecurityManager class and codebase:

• java.rmi.activation.security.class
• java.rmi.activation.security.codebase

package java.rmi.activation;

public class ActivationGroup 

	extends UnicastRemoteObject

	implements ActivationInstantiator

{

	protected ActivationGroup(ActivationGroupID groupID)

		throws java.rmi.RemoteException;



	public abstract MarshalledObject newInstance(ActivationID id,

													            ActivationDesc desc)

		throws ActivationException, java.rmi.RemoteException;



	public abstract void inactiveObject(ActivationID id)

		throws ActivationException, UnknownObjectException,

			   java.rmi.RemoteException;



	public static ActivationGroup createGroup(ActivationGroupID id,

												      ActivationGroupDesc desc,

											     long incarnation)

			throws ActivationException;

 

	public static ActivationGroupID currentGroupID();



	public static void setSystem(ActivationSystem system)

		throws ActivationException;



	public static ActivationSystem getSystem()

		throws ActivationException;



	protected void activeObject(ActivationID id, 

								  java.rmi.MarshalledObject mobj)      	

		throws ActivationException, UnknownObjectException,

			   java.rmi.RemoteException;



	protected void inactiveGroup()

		throws UnknownGroupException, java.rmi.RemoteException;

										

}

The activator calls an activation group's newInstance method in order to activate an object with the activation descriptor, desc. The activation group is responsible for:

• determining the class for the object using the descriptor's getClassName method,
• loading the class from the URL obtained from the descriptor (using the getCodeSource method),
• creating an instance of the class by invoking the special constructor of the object's class that takes two arguments: the object's ActivationID, and a MarshalledObject containing the object's initialization data, and
• returning a serialized version of the remote object it just created to the activator.

The method throws ActivationException if the instance for the given descriptor could not be created.

The group's inactiveObject method is called indirectly via a call to the Activatable.inactive method. A remote object implementation must call Activatable's inactive method when that object deactivates (the object deems that it is no longer active). If the object does not call Activatable.inactive when it deactivates, the object will never be garbage collected since the group keeps strong references to the objects it creates.

The group's inactiveObject method forcibly unexports the remote object, associated with id, from the RMI runtime so that the object can no longer receive incoming RMI calls. After removing the object from the RMI runtime, the group informs its ActivationMonitor (via the monitor's inactiveObject method) that the remote object is not currently active so that the remote object will be re-activated by the activator upon a subsequent activation request.

The inactiveObject method throws an UnknownObjectException if the activation group is has no knowledge of this object (e.g., the object was previously reported as inactive, or the object was never activated via the activation group). If the inactive operation fails (e.g., If the remote call to the activator (or activation group) fails, RemoteException is thrown.

The createGroup method creates and sets the activation group for the current VM. The activation group can only be set if it is not currently set. An activation group is set using the createGroup method when the Activator initiates the re-creation of an activation group in order to carry out incoming activate requests. A group must first register a group descriptor with the ActivationSystem before it can be created via this method (passing it the ActivationID obtained from previous registration).

The group specified by the ActivationGroupDesc, desc, must be a concrete subclass of ActivationGroup and have a public constructor that takes two arguments; the ActivationGroupID for the group and a MarshalledObject containing the group's initialization data (obtained from its ActivationGroupDesc). Note: if your application creates its own custom activation group, the group must set a security manager in the constructor, or objects cannot be activated in the group.

After the group is created, the ActivationSystem is informed that the group is active by calling the activeGroup method which returns the ActivationMonitor for the group. The application need not call activeGroup independently since that call back is taken care of by the createGroup method.

Once a group is created, subsequent calls to the currentGroupID method will return the identifier for this group until the group becomes inactive, at which point the currentGroupID method will return null.

The parameter incarnation indicates the current group incarnation, i.e., the number of times the group has been activated. The incarnation number is used as a parameter to the activeGroup method, once the group has been successfully created. The incarnation number is zero-based. If the group already exists, or if an error occurs during group creation, the createGroup method throws ActivationException.

The setSystem method sets the ActivationSystem, system, for the VM. The activation system can only be set if no group is currently active. If the activation system is not set via an explicit call to setSystem, then the getSystem method will attempt to obtain a reference to the ActivationSystem by looking up the name java.rmi.activation.ActivationSystem in the Activator's registry. By default, the port number used to look up the activation system is defined by ActivationSystem.SYSTEM_PORT. This port can be overridden by setting the property java.rmi.activation.port. If the activation system is already set when setSystem is called, the method throws ActivationException.

The getSystem method returns the activation system for the VM. The activation system may be set by the setSystem method (described above).

The activeObject method is a protected method used by subclasses to make the activeObject call back to the group's monitor to inform the monitor that the remote object with the specified activation id and whose stub is contained in mobj is now active. The call is simply forwarded to the group's ActivationMonitor.

The inactiveGroup method is a protected method used by subclasses to inform the group's monitor that the group has become inactive. A subclass makes this call when each object the group participated in activating in the VM has become inactive.