7 Remote Object Activation

7.1 Overview

Deprecation Notice: The RMI Activation mechanism has been deprecated and may be removed from a future version of the platform. See JEP 385 for further information.

Distributed object systems are designed to support long-lived persistent objects. Given that these systems will be made up of many thousands (perhaps millions) of such objects, it would be unreasonable for object implementations to become active and remain active, taking up valuable system resources, for indefinite periods of time. In addition, clients need the ability to store persistent references to objects so that communication among objects can be re-established after a system crash, since typically a reference to a distributed object is valid only while the object is active.

Object activation is a mechanism for providing persistent references to objects and managing the execution of object implementations. In RMI, activation allows objects to begin execution on an as-needed basis. When an activatable remote object is accessed (via a method invocation) if that remote object is not currently executing, the system initiates the object's execution inside an appropriate JVM.

7.1.1 Terminology

An active object is a remote object that is instantiated and exported in a JVM on some system. A passive object is one that is not yet instantiated (or exported) in a JVM, but which can be brought into an active state. Transforming a passive object into an active object is a process known as activation. Activation requires that an object be associated with a JVM, which may entail loading the class for that object into a JVM and the object restoring its persistent state (if any).

In the RMI system, we use lazy activation. Lazy activation defers activating an object until a client's first use (i.e., the first method invocation).

7.1.2 Lazy Activation

Lazy activation of remote objects is implemented using a faulting remote reference (sometimes referred to as a fault block). A faulting remote reference to a remote object "faults in" the active object's reference upon the first method invocation to the object. Each faulting reference maintains both a persistent handle (an activation identifier) and a transient remote reference to the target remote object. The remote object's activation identifier contains enough information to engage a third party in activating the object. The transient reference is the actual "live" reference to the active remote object that can be used to contact the executing object.

In a faulting reference, if the live reference to a remote object is null, the target object is not known to be active. Upon method invocation, the faulting reference (for that object) engages in the activation protocol to obtain a "live" reference, which is a remote reference (such as a unicast remote reference) for the newly-activated object. Once the faulting reference obtains the live reference, the faulting reference forwards method invocations to the underlying remote reference which, in turn, forwards the method invocation to the remote object.

In more concrete terms, a remote object's stub contains a "faulting" remote reference type that contains both:

Note: The RMI system preserves "at most once" semantics for remote calls. In other words, a call to an activatable or unicast remote object is sent at most once. Thus, if a call to a remote object fails (indicated by a RemoteException being thrown), the client can be guaranteed that the remote method executed no more than once (and perhaps not at all).

7.2 Activation Protocol

During a remote method invocation, if the "live" reference for a target object is unknown, the faulting reference engages in the activation protocol. The activation protocol involves several entities: the faulting reference, the activator, an activation group, and the remote object being activated.

The activator (usually one per host) is the entity which supervises activation by being both:

Note that the activator keeps the current mapping of activation identifiers to active objects as a cache, so that the group does not need to be consulted on each activation request.

An activation group (one per JVM) is the entity which receives a request to activate an object in the JVM and returns the activated object back to the activator.

The activation protocol is as follows. A faulting reference uses an activation identifier and calls the activator (an internal RMI interface) to activate the object associated with the identifier. The activator looks up the object's activation descriptor (registered previously). The object's descriptor contains:

If the activation group in which this object should reside exists, the activator forwards the activation request to that group. If the activation group does not exist, the activator initiates a JVM executing an activation group and then forwards the activation request to that group.

The activation group loads the class for the object and instantiates the object using a special constructor that takes several arguments, including the activation descriptor registered previously.

When the object is finished activating, the activation group passes back a marshalled object reference to the activator that then records the activation identifier and active reference pairing and returns the active (live) reference to the faulting reference. The faulting reference (inside the stub) then forwards method invocations via the live reference directly to the remote object.

Note: In Java 2 SDK, Standard Edition, v 1.2, RMI provides an implementation of the activation system interfaces. In order to use activation, you must first run the activation system daemon rmid.

7.3 Implementation Model for an "Activatable" Remote Object

In order to make a remote object that can be accessed via an activation identifier over time, a developer needs to:

An activation descriptor (ActivationDesc) can be registered in one of several ways:

For a specific object, only one of the above methods should be used to register the object for activation. See the section below on "Constructing an Activatable Remote Object" for examples on how to implement activatable objects.

7.3.1 The ActivationDesc Class

An ActivationDesc contains the information necessary to activate an object. It contains the object's activation group identifier, the class name for the object, a codebase path (or URLs) from which the object's code can be loaded, and a MarshalledObject that may contain object-specific initialization data used during each activation.

A descriptor registered with the activation system is consulted (during the activation process) to obtain information in order to re-create or activate an object. The MarshalledObject in the object's descriptor is passed as the second argument to the remote object's constructor for the object to use during activation.

package java.rmi.activation;
public final class ActivationDesc implements java.io.Serializable
{

        public ActivationDesc(String className,
                              String codebase,
                              java.rmi.MarshalledObject data)
                throws ActivationException;

        public ActivationDesc(String className,
                              String codebase,
                              java.rmi.MarshalledObject data,
                              boolean restart)
                throws ActivationException;

        public ActivationDesc(ActivationGroupID groupID,
                              String className,
                              String codebase,
                              java.rmi.MarshalledObject data,
                              boolean restart);

        public ActivationDesc(ActivationGroupID groupID,
                              String className,
                              String codebase,
                              java.rmi.MarshalledObject data);

        public ActivationGroupID getGroupID();

        public String getClassName();

        public String getLocation();

        public java.rmi.MarshalledObject getData()

        public boolean getRestartMode();
}

The first constructor for ActivationDesc constructs an object descriptor for an object whose class is className, that can be loaded from codebase path, and whose initialization information, in marshalled form, is data. If this form of the constructor is used, the object's group identifier defaults to the current identifier for ActivationGroup for this JVM. All objects with the same ActivationGroupID are activated in the same JVM. If the current group is inactive an ActivationException is thrown. If the groupID is null, an IllegalArgumentException is thrown.

The second constructor for ActivationDesc constructs an object descriptor in the same manner as the first constructor except an additional parameter, restart, must be supplied. If the object requires restart service, meaning that the object will be restarted automatically when the activator is restarted (as opposed to being activated lazily upon demand), restart should be true. If restart is false, the object is simply activated upon demand (via a remote method call).

The third constructor for ActivationDesc constructs an object descriptor for an object whose group identifier is groupID, whose class name is className that can be loaded from the codebase path, and whose initialization information is data. All objects with the same groupID are activated in the same JVM.

The fourth constructor for ActivationDesc constructs an object descriptor in the same manner as the third constructor, but allows a restart mode to be specified. If an object requires restart service (as defined above), restart should be true.

The getGroupID method returns the group identifier for the object specified by the descriptor. A group provides a way to aggregate objects into a single Java virtual machine.

The getClassName method returns the class name for the object specified by the activation descriptor.

The getLocation method returns the codebase path from where the object's class can be downloaded.

The getData method returns a "marshalled object" containing initialization (activation) data for the object specified by the descriptor.

The getRestartMode method returns true if the restart mode is enabled for this object, otherwise it returns false.

7.3.2 The ActivationID Class

The activation protocol makes use of activation identifiers to denote remote objects that can be activated over time. An activation identifier (an instance of the class ActivationID) contains several pieces of information needed for activating an object:

An activation identifier for an object can be obtained by registering an object with the activation system. Registration is accomplished in a few ways (also noted above):

package java.rmi.activation;
public class ActivationID implements java.io.Serializable
{
        public ActivationID(Activator activator);

        public Remote activate(boolean force)
                throws ActivationException, UnknownObjectException,
                       java.rmi.RemoteException;

        public boolean equals(Object obj);

        public int hashCode();
}

The constructor for ActivationID takes a single argument, activator, that specifies a remote reference to the activator responsible for activating the object associated with this activation identifier. An instance of ActivationID is globally unique.

The activate method activates the object associated with the activation identifier. If the force parameter is true, the activator considers any cached reference for the remote object as stale, thus forcing the activator to contact the group when activating the object. If force is false, then returning the cached value is acceptable. If activation fails, ActivationException is thrown. If the object identifier is not known to the activator, then the method throws UnknownObjectException. If the remote call to the activator fails, then RemoteException is thrown.

The equals method implements content equality. It returns true if all fields are equivalent (either identical or equivalent according to each field's Object.equals semantics). If p1 and p2 are instances of the class ActivationID, the hashCode method will return the same value if p1.equals(p2) returns true.

7.3.3 The Activatable Class

The Activatable class provides support for remote objects that require persistent access over time and that can be activated by the system. The class Activatable is the main API that developers need to use to implement and manage activatable objects. Note that you must first run the activation system daemon, rmid, before objects can be registered and/or activated.

package java.rmi.activation;
public abstract class Activatable
        extends java.rmi.server.RemoteServer
{
        protected Activatable(String codebase,
                              java.rmi.MarshalledObject data,
                              boolean restart,
                              int port)
                throws ActivationException, java.rmi.RemoteException;

        protected Activatable(String codebase,
                              java.rmi.MarshalledObject data,
                              boolean restart, int port,
                              RMIClientSocketFactory csf,
                              RMIServerSocketFactory ssf)
                throws ActivationException, java.rmi.RemoteException;

        protected Activatable(ActivationID id, int port)
                throws java.rmi.RemoteException;

        protected Activatable(ActivationID id, int port,
                              RMIClientSocketFactory csf,
                              RMIServerSocketFactory ssf)
                throws java.rmi.RemoteException;

        protected ActivationID getID();

        public static Remote register(ActivationDesc desc)
                throws UnknownGroupException, ActivationException,
                       java.rmi.RemoteException;

        public static boolean inactive(ActivationID id)
                throws UnknownObjectException, ActivationException,
                       java.rmi.RemoteException;

        public static void unregister(ActivationID id)
                throws UnknownObjectException, ActivationException,
                       java.rmi.RemoteException;

        public static ActivationID exportObject(Remote obj,
                                                String codebase,
                                                MarshalledObject data,
                                                boolean restart,
                                                int port)
                throws ActivationException, java.rmi.RemoteException;

        public static ActivationID exportObject(Remote obj,
                                                String codebase,
                                                MarshalledObject data,
                                                boolean restart,
                                                int port,
                                                RMIClientSocketFactory csf,
                                                RMIServerSocketFactory ssf)
                throws ActivationException, java.rmi.RemoteException;

        public static Remote exportObject(Remote obj,
                                          ActivationID id,
                                          int port)
                throws java.rmi.RemoteException;

        public static Remote exportObject(Remote obj,
                                          ActivationID id,
                                          int port,
                                          RMIClientSocketFactory csf,
                                          RMIServerSocketFactory ssf)
                throws java.rmi.RemoteException;

        public static boolean unexportObject(Remote obj, boolean force)
                throws java.rmi.NoSuchObjectException;
}

An implementation for an activatable remote object may or may not extend the class Activatable. A remote object implementation that does extend the Activatable class inherits the appropriate definitions of the hashCode and equals methods from the superclass java.rmi.server.RemoteObject. So, two remote object references that refer to the same Activatable remote object will be equivalent (the equals method will return true). Also, an instance of the class Activatable will be "equals" to the appropriate stub object for the instance (i.e., the Object.equals method will return true if called with the matching stub object for the implementation as an argument, and vice versa).

Activatable Class Methods

The first constructor for the Activatable class is used to register and export the object on a specified port (an anonymous port is chosen if port is zero). The object's URL path for downloading its class code is codebase, and its initialization data is data. If restart is true, the object will be restarted automatically when the activator is restarted and if the group crashes. If restart is false, the object will be activated on demand (via a remote method call to the object).

A concrete subclass of the Activatable class must call this constructor to register and export the object during initial construction. As a side-effect of activatable object construction, the remote object is both "registered" with the activation system and "exported" (on an anonymous port, if port is zero) to the RMI runtime so that it is available to accept incoming calls from clients.

The constructor throws ActivationException if registering the object with the activation system fails. RemoteException is thrown if exporting the object to the RMI runtime fails.

The second constructor is the same as the first Activatable constructor but allows the specification of the client and server socket factories used to communicate with this activatable object. See the section in about "RMI Socket Factories" for details.

The third constructor is used to activate and export the object (with the ActivationID, id) on a specified port. A concrete subclass of the Activatable class must call this constructor when the object itself is activated via its special "activation" constructor whose parameters must be:

As a side-effect of construction, the remote object is "exported" to the RMI runtime (on the specified port) and is available to accept incoming calls from clients. The constructor throws RemoteException if exporting the object to the RMI runtime fails.

The fourth constructor is the same as the third constructor, but allows the specification of the client and server socket factories used to communicate with this activatable object.

The getID method returns the object's activation identifier. The method is protected so that only subclasses can obtain an object's identifier. The object's identifier is used to report the object as inactive or to unregister the object's activation descriptor.

The register method registers, with the activation system, an object descriptor, desc, for an activatable remote object so that it can be activated on demand. This method is used to register an activatable object without having to first create the object. This method returns the Remote stub for the activatable object so that it can be saved and called at a later time thus forcing the object to be created/activated for the first time. The method throws UnknownGroupException if the group identifier in desc is not registered with the activation system. ActivationException is thrown if the activation system is not running. Finally, RemoteException is thrown if the remote call to the activation system fails.

The inactive method is used to inform the system that the object with the corresponding activation id is currently inactive. If the object is currently known to be active, the object is unexported from the RMI runtime (only if there are no pending or executing calls) so the that it can no longer receive incoming calls. This call also informs this JVM's ActivationGroup that the object is inactive; the group, in turn, informs its ActivationMonitor. If the call completes successfully, subsequent activate requests to the activator will cause the object to reactivate. The inactive method returns true if the object was successfully unexported (meaning that it had no pending or executing calls at the time) and returns false if the object could not be unexported due to pending or in-progress calls. The method throws UnknownObjectException if the object is not known (it may already be inactive); an ActivationException is thrown if the group is not active; a RemoteException is thrown if the call informing the monitor fails. The operation may still succeed if the object is considered active but has already unexported itself.

The unregister method revokes previous registration for the activation descriptor associated with id. An object can no longer be activated via that id. If the object id is unknown to the activation system, an UnknownObjectException is thrown. If the activation system is not running, an ActivationException is thrown. If the remote call to the activation system fails, then a RemoteException is thrown.

The first exportObject method may be invoked explicitly by an "activatable" object that does not extend the Activatable class, in order to both

Once the object is exported, it can receive incoming RMI calls.

This exportObject method returns the activation identifier obtained from registering the descriptor, desc, with the activation system. If the activation group is not active in the JVM, then ActivationException is thrown. If the object registration or export fails, then RemoteException is thrown.

This method does not need to be called if obj extends Activatable, since the first Activatable constructor calls this method.

The second exportObject method is the same as the first except it allows the specification of client and server socket factories used to communicate with the activatable object.

The third exportObject method exports an "activatable" remote object (not necessarily of type Activatable) with the identifier, id, to the RMI runtime to make the object, obj, available to receive incoming calls. The object is exported on an anonymous port, if port is zero.

During activation, this exportObject method should be invoked explicitly by an "activatable" object, that does not extend the Activatable class. There is no need for objects that do extend the Activatable class to invoke this method directly; this method is called by the third constructor above (which a subclass should invoke from its special activation constructor).

This exportObject method returns the Remote stub for the activatable object. If the object export fails, then the method throws RemoteException.

The fourth exportObject method is the same as the third but allows the specification of the client and server socket factories used to communicate with this activatable object.

The unexportObject method makes the remote object, obj, unavailable for incoming calls. If the force parameter is true, the object is forcibly unexported even if there are pending calls to the remote object or the remote object still has calls in progress. If the force parameter is false, the object is only unexported if there are no pending or in progress calls to the object. If the object is successfully unexported, the RMI runtime removes the object from its internal tables. Removing the object from RMI use in this forcible manner may leave clients holding stale remote references to the remote object. This method throws java.rmi.NoSuchObjectException if the object was not previously exported to the RMI runtime.

Constructing an Activatable Remote Object

In order for an object to be activated, the "activatable" object implementation class (whether or not it extends the Activatable class) must define a special public constructor that takes two arguments, its activation identifier of type ActivationID, and its activation data, a java.rmi.MarshalledObject, supplied in the activation descriptor used during registration. When an activation group activates a remote object inside its JVM, it constructs the object via this special constructor (described in more detail below). The remote object implementation may use the activation data to initialize itself in a suitable manner. The remote object may also wish to retain its activation identifier, so that it can inform the activation group when it becomes inactive (via a call to the Activatable.inactive method).

The first and second constructor forms for Activatable are used to both register and export an activatable object on a specified port. This constructor should be used when initially constructing the object; the third form of the constructor is used when re-activating the object.

A concrete subclass of Activatable must call the first or second constructor form to register and export the object during initial construction. This constructor first creates an activation descriptor (ActivationDesc) with the object's class name, the object's supplied codebase and data, and whose activation group is the default group for the JVM. Next, the constructor registers this descriptor with the default ActivationSystem. Finally, the constructor exports the activatable object to the RMI runtime on the specific port (if port is zero, then an anonymous port is chosen) and reports the object as an activeObject to the local ActivationGroup. If an error occurs during registration or export, the constructor throws RemoteException. Note that the constructor also initializes its ActivationID (obtained via registration), so that subsequent calls to the protected method getID will return the object's activation identifier.

The third constructor form for Activatable is used to export the object on a specified port. A concrete subclass of Activatable must call the third constructor form when it is activated via the object's own "activation" constructor, which takes two arguments:

This constructor only exports the activatable object to the RMI runtime on the specific port (if port is 0, then an anonymous port is chosen). It does not inform the ActivationGroup that the object is active, since it is the ActivationGroup that is activating the object and knows it to be active already.

The following is an example of a remote object interface, Server, and an implementation, ServerImpl, that extends the Activatable class:

package examples;

public interface Server extends java.rmi.Remote {
        public void doImportantStuff()
                throws java.rmi.RemoteException;
}

public class ServerImpl extends Activatable implements Server
{
        // Constructor for initial construction, registration and export
        public ServerImpl(String codebase, MarshalledObject data)
                throws ActivationException, java.rmi.RemoteException
        {
                // register object with activation system, then
                // export on anonymous port
                super(codebase, data, false, 0);
        }

        // Constructor for activation and export; this constructor
        // is called by the ActivationInstantiator.newInstance
        // method during activation in order to construct the object.
        public ServerImpl(ActivationID id, MarshalledObject data)
                throws java.rmi.RemoteException
        {
                // call the superclass's constructor in order to
                // export the object to the RMI runtime.
                super(id, 0);
                // initialize object (using data, for example)
        }

        public void doImportantStuff() { ... }
}

An object is responsible for exporting itself. The constructors for Activatable take care of exporting the object to the RMI runtime with the live reference type of a UnicastRemoteObject, so the object implementation extending Activatable does not need to worry about the detail of exporting the object explicitly (other than invoking the appropriate superclasses constructor). If an object implementation does not extend the class Activatable, the object must export the object explicitly via a call to one of the Activatable.exportObject static methods.

In the following example, ServerImpl does not extend Activatable, but rather another class, so ServerImpl is responsible for exporting itself during initial construction and activation. The following class definition shows ServerImpl's initialization constructor and its special "activation" constructor and the appropriate call to export the object within each constructor:

package examples;
public class ServerImpl extends SomeClass implements Server
{
        // constructor for initial creation
        public ServerImpl(String codebase, MarshalledObject data)
                throws ActivationException, java.rmi.RemoteException
        {
                // register and export the object
                Activatable.exportObject(this, codebase, data, false, 0);
        }

        // constructor for activation
        public ServerImpl(ActivationID id, MarshalledObject data)
                throws java.rmi.RemoteException
        {
                // export the object
                Activatable.exportObject(this, id, 0);
        }

        public void doImportantStuff() { ... }
}

Registering an Activation Descriptor Without Creating the Object

To register an activatable remote object with the activation system without first creating the object, the programmer can simply register an activation descriptor (an instance of the class ActivationDesc) for the object. An activation descriptor contains all the necessary information so that the activation system can activate the object when needed. An activation descriptor for an instance of the class examples.ServerImpl can be registered in the following manner (exception handling elided):

Server server;
ActivationDesc desc;
String codebase = "http://zaphod/codebase/";

MarshalledObject data = new MarshalledObject("some data");
desc = new ActivationDesc( "examples.ServerImpl", codebase, data);
server = (Server)Activatable.register(desc);

The register call returns a Remote stub that is the stub for the examples.ServerImpl object and implements the same set of remote interfaces that examples.ServerImpl implements (i.e, the stub implements the remote interface Server). This stub object (above, cast and assigned to server) can be passed as a parameter in any method call expecting an object that implements the examples.Server remote interface.

7.4 Activation Interfaces

In the RMI activation protocol, there are two guarantees that the activator must make for the system to function properly:

The activator maintains a database of appropriate information for the groups and objects that it participates in activating.

7.4.1 The Activator Interface

The activator is one of the entities that participates during the activation process. As described earlier, a faulting reference (inside a stub) calls the activator's activate method to obtain a "live" reference to an activatable remote object. Upon receiving a request for activation, the activator looks up the activation descriptor for the activation identifier, id, determines the group in which the object should be activated, and invokes the newInstance method on the activation group's instantiator (the remote interface ActivationGroup is described below). The activator initiates the execution of activation groups as necessary. For example, if an activation group for a specific group descriptor is not already executing, the activator will spawn a child JVM for the activation group to establish the group in the new JVM.

The activator is responsible for monitoring and detecting when activation groups fail so that it can remove stale remote references from its internal tables.

package java.rmi.activation;
public interface Activator extends java.rmi.Remote
{
        java.rmi.MarshalledObject activate(ActivationID id,
                                           boolean force)
                throws UnknownObjectException, ActivationException,
                       java.rmi.RemoteException;
}

The activate method activates the object associated with the activation identifier, id. If the activator knows the object to be active already and the force parameter is false, the stub with a "live" reference is returned immediately to the caller; otherwise, if the activator does not know that the corresponding remote object is active or the force parameter is true, the activator uses the activation descriptor information (previously registered to obtain the id) to determine the group (JVM) in which the object should be activated. If an ActivationInstantiator corresponding to the object's group already exists, the activator invokes the activation instantiator's newInstance method, passing it the id and the object's activation descriptor.

If the activation instantiator (group) for the object's group descriptor does not yet exist, the activator starts a new incarnation of an ActivationInstantiator executing (by spawning a child process, for example). When the activator re-creates an ActivationInstantiator for a group, it must increment the group's incarnation number. Note that the incarnation number is zero-based. The activation system uses incarnation numbers to detect late ActivationSystem.activeGroup and ActivationMonitor.inactiveGroup calls. The activation system discards calls with an earlier incarnation number than the current number for the group.

Note: The activator must communicate both the activation group's identifier, descriptor, and incarnation number when it starts up a new activation group. The activator spawns an activation group in a separate JVM (as a separate or child process, for example), and therefore must pass information specifying the information necessary to create the group via the ActivationGroup.createGroup method. How the activator sends this information to the spawned process is unspecified, however, this information could be sent in the form of marshalled objects to the child process's standard input.

When the activator receives the activation group's call back (via the ActivationSystem.activeGroup method) specifying the activation group's reference and incarnation number, the activator can then invoke that activation instantiator's newInstance method to forward each pending activation request to the activation instantiator and return the result (a marshalled remote object reference, a stub) to each caller.

Note that the activator receives a MarshalledObject instead of a Remote object so that the activator does not need to load the code for that object, or participate in distributed garbage collection for that object. If the activator kept a strong reference to the remote object, the activator would then prevent the object from being garbage collected under the normal distributed garbage collection mechanism.

The activate method throws ActivationException if activation fails. Activation may fail for a variety of reasons: the class could not be found, the activation group could not be contacted, etc. The activate method throws UnknownObjectException if no activation descriptor for the activation identifier, id, has been previously registered with this activator. RemoteException is thrown if the remote call to the activator fails.

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;

        void shutdown() throws java.rmi.RemoteException;
}

Note: As a security measure, all of the above methods (registerGroup, activeGroup, unregisterGroup, registerObject, unregisterObject, and shutdown) 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 an activation identifier for an activatable remote object. The ActivationSystem creates an ActivationID (an 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 JVM. 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.).

The shutdown method gracefully terminates (asynchronously) the activation system and all related activation processes (activator, monitors and groups). All groups spawned by the activation daemon will be destroyed and the activation daemon will exit. In order to shut down the activation system daemon, rmid, execute the command:

rmid -stop [-port num]

This command will shut down the activation daemon on the specified port (if no port is specified, the daemon on the default port will be shut down).

7.4.3 The ActivationMonitor Class

An ActivationMonitor is specific to an ActivationGroup and is obtained when a group is reported via a call to ActivationSystem.activeGroup (this is done internally by the ActivationGroup.createGroup method). An activation group is responsible for informing its ActivationMonitor when:

  1. its objects become active,
  2. its objects become inactive, or
  3. the group as a whole becomes inactive.
package java.rmi.activation;
public interface ActivationMonitor
        extends java.rmi.Remote
{

        public abstract void inactiveObject(ActivationID id)
                throws UnknownObjectException, RemoteException;

        public void activeObject(ActivationID id,
                                 java.rmi.MarshalledObject mobj)
                throws UnknownObjectException, java.rmi.RemoteException;

        public void inactiveGroup(ActivationGroupID id,
                                  long incarnation)
                throws UnknownGroupException, java.rmi.RemoteException;
}

An activation group calls its monitor's inactiveObject method when an object in its group becomes inactive (deactivates). An activation group discovers that an object (that it participated in activating) in its JVM is no longer active via a call to the activation group's inactiveObject method.

The inactiveObject call informs the ActivationMonitor that the remote object reference it holds for the object with the activation identifier, id, is no longer valid. The monitor considers the reference associated with id as a stale reference. Since the reference is considered stale, a subsequent activate call for the same activation identifier results in re-activating the remote object. If the object is not known to the ActivationMonitor, the method throws UnknownObjectException. If the remote call fails, then RemoteException is thrown.

The activeObject call informs the ActivationMonitor that the object associated with id is now active. The parameter obj is the marshalled representation of the object's stub. An ActivationGroup must inform its monitor if an object in its group becomes active by other means than being activated directly by the system (i.e., the object is registered and "activated" itself). If the object id is not previously registered, then the method throws UnknownObjectException. If the remote call fails, then RemoteException is thrown.

The inactiveGroup call informs the monitor that the group specified by id and incarnation is now inactive. The group will be re-created with a greater incarnation number upon a subsequent request to activate an object within the group. A group becomes inactive when all objects in the group report that they are inactive. If either the group id is not registered or the incarnation number is smaller than the current incarnation for the group, then the method throws UnknownGroupException. If the remote call fails, then RemoteException is thrown.

7.4.4 The ActivationInstantiator Class

The ActivationInstantiator is responsible for creating instances of activatable objects. A concrete subclass of ActivationGroup implements the newInstance method to handle creating objects within the group.

package java.rmi.activation;
public interface ActivationInstantiator
        extends java.rmi.Remote
{
        public MarshalledObject newInstance(ActivationID id,
                                            ActivationDesc desc)
                throws ActivationException, java.rmi.RemoteException;

}

The activator calls an instantiator's newInstance method in order to re-create in that group an object with the activation identifier, id, and descriptor, desc. The instantiator is responsible for:

An instantiator is also responsible for reporting when objects it creates or activates are no longer active, so that it can make the appropriate inactiveObject call to its ActivationMonitor (see the ActivationGroup class for more details).

If object activation fails, then the newInstance method throws ActivationException. If the remote call fails, then the method throws RemoteException.

7.4.5 The ActivationGroupDesc Class

An activation group descriptor (ActivationGroupDesc) contains the information necessary to create or re-create an activation group in which to activate objects in the same JVM.

Such a descriptor contains:

The group's class must be a concrete subclass of ActivationGroup. A subclass of ActivationGroup is created or re-created via the ActivationGroup.createGroup static method, which invokes a special constructor that takes two arguments:

package java.rmi.activation;
public final class ActivationGroupDesc
        implements java.io.Serializable
{

        public ActivationGroupDesc(java.util.Properties props,
                                   CommandEnvironment env);;

        public ActivationGroupDesc(String className,
                                   String codebase,
                                   java.rmi.MarshalledObject data,
                                   java.util.Properties props,
                                   CommandEnvironment env);

        public String getClassName();

        public String getLocation();

        public java.rmi.MarshalledObject getData();

        public CommandEnvironment getCommandEnvironment();

        public java.util.Properties getPropertiesOverrides();

}

The first constructor creates a group descriptor that uses system default for group implementation and code location. Properties specify Java application environment overrides (which will override system properties in the group implementation's JVM). The command environment can control the exact command/options used in starting the child JVM, or can be null to accept rmid's default. This constructor will create an ActivationGroupDesc with a null group class name, which indicates the system's default ActivationGroup implementation.

The second constructor is the same as the first, but allows the specification of Properties and CommandEnvironment.

The getClassName method returns the group's class name (possibly null). A null group class name indicates the system's default ActivationGroup implementation.

The getLocation method returns the codebase path from where the group's class can be loaded.

The getData method returns the group's initialization data in marshalled form.

The getCommandEnvironment method returns the command environment (possibly null).

The getPropertiesOverrides method returns the properties overrides (possibly null) for this descriptor.

7.4.6 The ActivationGroupDesc.CommandEnvironment Class

The CommandEnvironment class allows overriding default system properties and specifying implemention-defined options for an ActivationGroup.

public static class CommandEnvironment
        implements java.io.Serializable
{
        public CommandEnvironment(String cmdpath, String[] args);
        public boolean equals(java.lang.Object);
        public String[] getCommandOptions();
        public String getCommandPath();
        public int hashCode();

}

The constructor creates a CommandEnvironment with the given command, cmdpath, and additional command line options, args.

The equals implements content equality for command environment objects. The hashCode method is implemented appropriately so that a CommandEnvironment can be stored in a hash table if necessary.

The getCommandOptions method returns the environment object's command line options.

The getCommandPath method returns the environment object's command string.

7.4.7 The ActivationGroupID Class

The identifier for a registered activation group serves several purposes:

The ActivationGroupID is returned from the call to ActivationSystem.registerGroup and is used to identify the group within the activation system. This group identifier is passed as one of the arguments to the activation group's special constructor when an activation group is created or re-created.

package java.rmi.activation;
public class ActivationGroupID implements java.io.Serializable
{
        public ActivationGroupID(ActivationSystem system);

        public ActivationSystem getSystem();

        public boolean equals(Object obj);

        public int hashCode();
}

The ActivationGroupID constructor creates a unique group identifier whose ActivationSystem is system.

The getSystem method returns the activation system for the group.

The hashCode method returns a hashcode for the group's identifier. Two group identifiers that refer to the same remote group will have the same hash code.

The equals method compares two group identifiers for content equality. The method returns true if both of the following conditions are true: 1) the unique identifiers are equivalent (by content), and 2) the activation system specified in each refers to the same remote object.

7.4.8 The ActivationGroup Class

An ActivationGroup is responsible for creating new instances of activatable objects in its group, informing its ActivationMonitor when:

  1. its objects become active,
  2. its objects become inactive, or
  3. the group as a whole becomes inactive.

An ActivationGroup is initially created in one of several ways:

Only the activator can re-create an ActivationGroup. The activator spawns, as needed, a separate JVM (as a child process, for example) for each registered activation group and directs activation requests to the appropriate group. It is implementation specific how JVMs 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:

When created, the default implementation of ActivationGroup will set the system properties to the system properties in force when the 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).

package java.rmi.activation;
public abstract 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 boolean 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:

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 unexports the remote object, associated with id (only if there are no pending or executing calls to the remote object) from the RMI runtime so that the object can no longer receive incoming RMI calls. If the object currently has pending or executing calls, inactiveObject returns false and no action is taken.

If the unexportObject operation was successful (meaning that the object has no pending or executing calls), 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 reactivated by the activator upon a subsequent activation request. If the operation was successful, inactiveObject returns true. The operation may still succeed if the object is considered active by the ActivationGroup but has already been unexported.

The inactiveObject method throws an UnknownObjectException if the activation group 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 JVM. 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). If the ActivationGroupDesc.getClassName method returns null, the system's default group implementation is used. 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 callback 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 JVM. 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 JVM. 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 JVM has become inactive.

7.4.9 The MarshalledObject Class

A MarshalledObject is a container for an object that allows that object to be passed as a parameter in an RMI call, but postpones deserializing the object at the receiver until the application explicitly requests the object (via a call to the container object). The Serializable object contained in the MarshalledObject is serialized and deserialized (when requested) with the same semantics as parameters passed in RMI calls, which means that any remote object in the MarshalledObject is represented by a serialized instance of its stub. The object contained by the MarshalledObject may be a remote object, a non-remote object, or an entire graph of remote and non-remote objects.

When an object is placed inside the MarshalledObject wrapper, the serialized form of the object is annotated with the codebase URL (where the class can be loaded); likewise, when the contained object is retrieved from its MarshalledObject wrapper, if the code for the object is not available locally, the URL (annotated during serialization) is used to locate and load the bytecodes for the object's class.

package java.rmi;
public final class MarshalledObject implements java.io.Serializable
{
        public MarshalledObject(Object obj)
                throws java.io.IOException;

        public Object get()
                throws java.io.IOException, ClassNotFoundException;

        public int hashCode();

        public boolean equals();
}

MarshalledObject's constructor takes a serializable object, obj, as its single argument and holds the marshalled representation of the object in a byte stream. The marshalled representation of the object preserves the semantics of objects that are passed in RMI calls:

When an instance of the class MarshalledObject is written to a java.io.ObjectOutputStream, the contained object's marshalled form (created during construction) is written to the stream; thus, only the byte stream is serialized.

When a MarshalledObject is read from a java.io.ObjectInputStream, the contained object is not deserialized into a concrete object; the object remains in its marshalled representation until the marshalled object's get method is called.

The get method always reconstructs a new copy of the contained object from its marshalled form. The internal representation is deserialized with the semantics used for unmarshalling parameters for RMI calls. So, the deserialization of the object's representation loads class code (if not available locally) using the URL annotation embedded in the serialized stream for the object.

The hashCode of the marshalled representation of the object is the same as the object passed to the constructor. The equals method will return true if the marshalled representation of the objects being compared are equivalent. The comparison that equals uses ignores a class's codebase annotation, meaning that two objects are equivalent if they have the same serialized representation except for the codebase of each class in the serialized representation.