Chapter 14. The java.rmi.activation Package

The java.rmi.activation package contains the interfaces, classes, and exceptions that represent the RMI activation system, introduced in Java 2. This RMI service allows you to define remote objects that are not instantiated on the server until a client request triggers their activation. The activation system provides the means to specify how a remote object is activated and how activated objects are grouped into Java VMs. The activation also supports persistent remote references, or in other words, references to remote objects that can persist beyond the lifetime of an individual server object. Figure 14-1 shows the class hierarchy for this package.

Figure 14-1. The java.rmi.activation package

Activatable

Java 1.2

java.rmi.activation

serializable remote

This abstract subclass of java.rmi.server.RemoteServer represents a server object that is persistent and activatable. This is in contrast to a java.rmi.server.UnicastRemoteObject, which represents a server object that is only available during the lifetime of the server process. Both UnicastRemoteObject objects and Activatable objects support only point-to-point communication, however.

The Activatable class provides a set of constructors and a corresponding set of static exportObject() methods that can be used to register and export server objects, either pre-instantiated or not. The exportObject() methods are provided for server objects that choose not to extend the Activatable class. Other static methods are the register() method, which can be used to register an activatable object without instantiating it, the unexportObject() method, which removes the specified object from the RMI runtime system, the unregister() method, which removes the activation registration for the given ActivationID, and the inactive() method, which tells the activation system that the object associated with the given ActivationID should be inactivated. The getID() method is an instance method that allows you to get the ActivationID for a server object.

public abstract class Activatable extends java.rmi.server.RemoteServer {
//	Protected Constructors
	protected Activatable (ActivationID id, int port) throws RemoteException;
	protected Activatable (ActivationID id, int port, java.rmi.server.RMIClientSocketFactory csf, java.rmi.server.RMIServerSocketFactory ssf) throws RemoteException;
	protected Activatable (String location, MarshalledObject data, boolean restart, int port) throws ActivationException, RemoteException;
	protected Activatable (String location, MarshalledObject data, boolean restart, int port, java.rmi.server.RMIClientSocketFactory csf, java.rmi.server.RMIServerSocketFactory ssf) throws ActivationException, RemoteException;
//	Public Class Methods
	public static Remote exportObject (Remote obj, ActivationID id, int port) throws RemoteException;
	public static ActivationID exportObject (Remote obj, String location, MarshalledObject data, boolean restart, int port) throws ActivationException, RemoteException;
	public static Remote exportObject (Remote obj, ActivationID id, int port, java.rmi.server.RMIClientSocketFactory csf, java.rmi.server.RMIServerSocketFactory ssf) throws RemoteException;
	public static ActivationID exportObject (Remote obj, String location, MarshalledObject data, boolean restart, int port, java.rmi.server.RMIClientSocketFactory csf, java.rmi.server.RMIServerSocketFactory ssf) throws ActivationException, RemoteException;
	public static boolean inactive (ActivationID id) throws UnknownObjectException, ActivationException, RemoteException;
	public static Remote register (ActivationDesc desc) throws UnknownGroupException, ActivationException, RemoteException;
	public static boolean unexportObject (Remote obj, boolean force) throws NoSuchObjectException;
	public static void unregister (ActivationID id) throws UnknownObjectException, ActivationException, RemoteException;
//	Protected Instance Methods
	protected ActivationID getID ();
}

Hierarchy: Object-->java.rmi.server.RemoteObject(Remote,Serializable)-->java.rmi.server.RemoteServer-->Activatable

ActivateFailedException

Java 1.2

java.rmi.activation

serializable checked

This subclass of RemoteException is thrown to a client when a remote method call fails because the object could not be activated.

public class ActivateFailedException extends RemoteException {
//	Public Constructors
	public ActivateFailedException (String s);
	public ActivateFailedException (String s, Exception ex);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->RemoteException-->ActivateFailedException

ActivationDesc

Java 1.2

java.rmi.activation

serializable

An ActivationDesc represents a description for how a remote object should be activated. It contains an activation group ID for the object, the class name for the object to be instantiated, a codebase that can be used to load the class description, if necessary, and a MarshalledObject that contains object-specific initialization data. Once an ActivationDesc has been created, it can be used to register an object for activation using the Activatable.register() method.

public final class ActivationDesc implements Serializable {
//	Public Constructors
	public ActivationDesc (String className, String location, MarshalledObject data) throws ActivationException;
	public ActivationDesc (ActivationGroupID groupID, String className, String location, MarshalledObject data);
	public ActivationDesc (String className, String location, MarshalledObject data, boolean restart) throws ActivationException;
	public ActivationDesc (ActivationGroupID groupID, String className, String location, MarshalledObject data, boolean restart);
//	Public Instance Methods
	public String getClassName ();
	public MarshalledObject getData ();
	public ActivationGroupID getGroupID ();
	public String getLocation ();
	public boolean getRestartMode ();
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
}

Hierarchy: Object-->ActivationDesc(Serializable)

Passed To: Activatable.register(), ActivationGroup.newInstance(), ActivationGroup_Stub.newInstance(), ActivationInstantiator.newInstance(), ActivationSystem.{registerObject(), setActivationDesc()}

Returned By: ActivationSystem.{getActivationDesc(), setActivationDesc()}

ActivationException

Java 1.2

java.rmi.activation

serializable checked

This is a base class used for all nonremote, activation-related exceptions (i.e., exceptions thrown between components of the activation system or by the local activation system to clients invoking its methods).

public class ActivationException extends Exception {
//	Public Constructors
	public ActivationException ();
	public ActivationException (String s);
	public ActivationException (String s, Throwable ex);
//	Public methods overriding Throwable
	public String getMessage ();	default:null
	public void printStackTrace ();
	public void printStackTrace (PrintWriter pw);
	public void printStackTrace (PrintStream ps);
//	Public Instance Fields
	public Throwable detail ;
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->ActivationException

Subclasses: UnknownGroupException, UnknownObjectException

Thrown By: Too many methods to list.

ActivationGroup

Java 1.2

java.rmi.activation

serializable remote

An ActivationGroup represents a group of activatable objects that are meant to run within the same Java VM. The ActivationGroup serves as a go-between for the ActivationMonitor and the activatable objects, forwarding messages about the active state of objects in its group. The activeObject() methods forward a message to the activation system about a newly activated object in the group, while the inactiveObject() method does the same for deactivated objects.

You can explicitly create your own ActivationGroup using the createGroup() method. If you don't specify a group ID when you create an ActivationDesc for an activatable object, it is assigned to a default group. When you create an ActivationGroup, you provide an ActivationGroupDesc object that describes how the group is to be created (e.g, from what class the group object should be constructed, or what Properties should be set for the group).

The ActivationGroup class is abstract, so you must provide a concrete implementation in order to create groups. In addition to satisfying the interface defined in ActivationGroup, the subclass must also provide a constructor that takes an ActivationGroupID and a MarshalledObject as arguments. This constructor is invoked by the createGroup() method. A concrete subclass of ActivationGroup must also implement the newInstance() method inherited from ActivationInstantiator.

public abstract class ActivationGroup extends java.rmi.server.UnicastRemoteObjectimplements ActivationInstantiator {
//	Protected Constructors
	protected ActivationGroup (ActivationGroupID groupID) throws RemoteException;
//	Public Class Methods
	public static ActivationGroup createGroup (ActivationGroupID id, ActivationGroupDesc desc, long incarnation) throws ActivationException;	synchronized
	public static ActivationGroupID currentGroupID ();	synchronized
	public static ActivationSystem getSystem () throws ActivationException;	synchronized
	public static void setSystem (ActivationSystem system) throws ActivationException;	synchronized
//	Public Instance Methods
	public abstract void activeObject (ActivationID id, Remote obj) throws ActivationException, UnknownObjectException, RemoteException;
	public boolean inactiveObject (ActivationID id) throws ActivationException, UnknownObjectException, RemoteException;
//	Methods implementing ActivationInstantiator
	public abstract MarshalledObject newInstance (ActivationID id, ActivationDesc desc) throws ActivationException, RemoteException;
//	Protected Instance Methods
	protected void activeObject (ActivationID id, MarshalledObject mobj) throws ActivationException, UnknownObjectException, RemoteException;
	protected void inactiveGroup () throws UnknownGroupException, RemoteException;
}

Hierarchy: Object-->java.rmi.server.RemoteObject(Remote,Serializable)-->java.rmi.server.RemoteServer-->java.rmi.server.UnicastRemoteObject-->ActivationGroup(ActivationInstantiator(Remote))

Returned By: ActivationGroup.createGroup()

ActivationGroupDesc

Java 1.2

java.rmi.activation

serializable

An ActivationGroupDesc contains the information to create a new activation group. It includes the class that should construct the group object, a codebase that can find the class description, if necessary, and a MarshalledObject containing any additional initialization information required by the group. In addition, each constructor allows you to specify a Properties list that overrides any default runtime properties in the Java VM for the group and a CommandEnvironment object that allows you to customize the Java executable that starts the group's VM and its command-line arguments.

public final class ActivationGroupDesc implements Serializable {
//	Public Constructors
	public ActivationGroupDesc (java.util.Properties overrides, ActivationGroupDesc.CommandEnvironment cmd);
	public ActivationGroupDesc (String className, String location, MarshalledObject data, java.util.Properties overrides, ActivationGroupDesc.CommandEnvironment cmd);
//	Inner Classes
	;
//	Public Instance Methods
	public String getClassName ();
	public ActivationGroupDesc.CommandEnvironment getCommandEnvironment ();
	public MarshalledObject getData ();
	public String getLocation ();
	public java.util.Properties getPropertyOverrides ();
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
}

Hierarchy: Object-->ActivationGroupDesc(Serializable)

Passed To: ActivationGroup.createGroup(), ActivationSystem.{registerGroup(), setActivationGroupDesc()}

Returned By: ActivationSystem.{getActivationGroupDesc(), setActivationGroupDesc()}

ActivationGroupDesc.CommandEnvironment

Java 1.2

java.rmi.activation

serializable

This inner class of ActivationGroupDesc specifies customized startup parameters for the Java VM for an activation group. It contains a command path, which specifies where to find the Java executable to be run, and an array of command-line arguments for the Java executable.

public static class ActivationGroupDesc.CommandEnvironment implements Serializable {
//	Public Constructors
	public CommandEnvironment (String cmdpath, String[ ] argv);
//	Public Instance Methods
	public String[ ] getCommandOptions ();
	public String getCommandPath ();
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
}

Hierarchy: Object-->ActivationGroupDesc.CommandEnvironment(Serializable)

Passed To: ActivationGroupDesc.ActivationGroupDesc()

Returned By: ActivationGroupDesc.getCommandEnvironment()

ActivationGroupID

Java 1.2

java.rmi.activation

serializable

An ActivationGroupID uniquely identifies a group within the activation system. The ActivationGroup can also use its ActivationGroupID to query for its ActivationSystem, if needed. An ActivationGroupID is generated for a new group by the ActivationSystem.registerGroup() method.

public class ActivationGroupID implements Serializable {
//	Public Constructors
	public ActivationGroupID (ActivationSystem system);
//	Public Instance Methods
	public ActivationSystem getSystem ();
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
}

Hierarchy: Object-->ActivationGroupID(Serializable)

Passed To: ActivationDesc.ActivationDesc(), ActivationGroup.{ActivationGroup(), createGroup()}, ActivationMonitor.inactiveGroup(), ActivationSystem.{activeGroup(), getActivationGroupDesc(), setActivationGroupDesc(), unregisterGroup()}

Returned By: ActivationDesc.getGroupID(), ActivationGroup.currentGroupID(), ActivationSystem.registerGroup()

ActivationID

Java 1.2

java.rmi.activation

serializable

An ActivationID uniquely identifies an activatable object within the activation system. It also contains an opaque reference to the Activator responsible for activating the object, which it uses when its activate() method is invoked. An ActivationID is generated for an activatable object by registering it using the Activatable.register() method (the stub returned by this method is initialized with the ActivationID) or by using one of the Activatable.exportObject() methods.

public class ActivationID implements Serializable {
//	Public Constructors
	public ActivationID (Activator activator);
//	Public Instance Methods
	public Remote activate (boolean force) throws ActivationException, UnknownObjectException, RemoteException;
//	Public methods overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
}

Hierarchy: Object-->ActivationID(Serializable)

Passed To: Activatable.{Activatable(), exportObject(), inactive(), unregister()}, ActivationGroup.{activeObject(), inactiveObject(), newInstance()}, ActivationGroup_Stub.newInstance(), ActivationInstantiator.newInstance(), ActivationMonitor.{activeObject(), inactiveObject()}, ActivationSystem.{getActivationDesc(), setActivationDesc(), unregisterObject()}, Activator.activate()

Returned By: Activatable.{exportObject(), getID()}, ActivationSystem.registerObject()

ActivationInstantiator

Java 1.2

java.rmi.activation

remote

This interface represents an object that is responsible for activating objects, using its newInstance() method. The arguments to the method provide the ActivationID for the object within the activation system and the ActivationDesc provided for the object when it was registered, which includes the information needed to activate the object. The ActivationGroup class implements this interface; concrete subclasses of ActivationGroup must provide an implementation of the newInstance() method.

public abstract interface ActivationInstantiator extends Remote {
//	Public Instance Methods
	public abstract MarshalledObject newInstance (ActivationID id, ActivationDesc desc) throws ActivationException, RemoteException;
}

Hierarchy: (ActivationInstantiator(Remote))

Implementations: ActivationGroup, ActivationGroup_Stub

Passed To: ActivationSystem.activeGroup()

ActivationMonitor

Java 1.2

java.rmi.activation

remote

An ActivationMonitor monitors a single activation group. It must be notified by the group when objects within the group become active or inactive or when the group as a whole becomes inactive. This lets the ActivationMonitor know when an object needs to be (re)activated, for example.

public abstract interface ActivationMonitor extends Remote {
//	Public Instance Methods
	public abstract void activeObject (ActivationID id, MarshalledObject obj) throws UnknownObjectException, RemoteException;
	public abstract void inactiveGroup (ActivationGroupID id, long incarnation) throws UnknownGroupException, RemoteException;
	public abstract void inactiveObject (ActivationID id) throws UnknownObjectException, RemoteException;
}

Hierarchy: (ActivationMonitor(Remote))

Returned By: ActivationSystem.activeGroup()

ActivationSystem

Java 1.2

java.rmi.activation

remote

The ActivationSystem is the backbone of the activation runtime. It interacts with Activator objects to activate objects and groups and ActivationMonitor objects to determine when such activations are necessary. The ActivationSystem handling a particular Java VM can be obtained using the static ActivationGroup.getSystem() method.

The methods on the ActivationSystem are largely used by other classes in the activation package to implement various functions. The Activatable.register() method, for example, registers the activatable object by calling the registerObject() method on the ActivationSystem.

public abstract interface ActivationSystem extends Remote {
//	Public Constants
	public static final int SYSTEM_PORT ;	=1098
//	Public Instance Methods
	public abstract ActivationMonitor activeGroup (ActivationGroupID id, ActivationInstantiator group, long incarnation) throws UnknownGroupException, ActivationException, RemoteException;
	public abstract ActivationDesc getActivationDesc (ActivationID id) throws ActivationException, UnknownObjectException, RemoteException;
	public abstract ActivationGroupDesc getActivationGroupDesc (ActivationGroupID id) throws ActivationException, UnknownGroupException, RemoteException;
	public abstract ActivationGroupID registerGroup (ActivationGroupDesc desc) throws ActivationException, RemoteException;
	public abstract ActivationID registerObject (ActivationDesc desc) throws ActivationException, UnknownGroupException, RemoteException;
	public abstract ActivationDesc setActivationDesc (ActivationID id, ActivationDesc desc) throws ActivationException, UnknownObjectException, UnknownGroupException, RemoteException;
	public abstract ActivationGroupDesc setActivationGroupDesc (ActivationGroupID id, ActivationGroupDesc desc) throws ActivationException, UnknownGroupException, RemoteException;
	public abstract void shutdown () throws RemoteException;
	public abstract void unregisterGroup (ActivationGroupID id) throws ActivationException, UnknownGroupException, RemoteException;
	public abstract void unregisterObject (ActivationID id) throws ActivationException, UnknownObjectException, RemoteException;
}

Hierarchy: (ActivationSystem(Remote))

Passed To: ActivationGroup.setSystem(), ActivationGroupID.ActivationGroupID()

Returned By: ActivationGroup.getSystem(), ActivationGroupID.getSystem()

Activator

Java 1.2

java.rmi.activation

remote

An Activator is responsible for activating remote objects and their groups. Its only method, activate(), triggers the activation system protocol. The activator first finds the ActivationDesc matching the given ActivationID and checks the activation information contained in it. If the target group for the object is not active, the Activator starts its Java VM and activates the group object itself. Finally, the Activator tells the group to (re)create the object by calling the newInstance() method on the group.

public abstract interface Activator extends Remote {
//	Public Instance Methods
	public abstract MarshalledObject activate (ActivationID id, boolean force) throws ActivationException, UnknownObjectException, RemoteException;
}

Hierarchy: (Activator(Remote))

Passed To: ActivationID.ActivationID()

UnknownGroupException

Java 1.2

java.rmi.activation

serializable checked

This exception is thrown if an unregistered ActivationGroupID is used, either directly as a method argument or indirectly within an ActivationDesc.

public class UnknownGroupException extends ActivationException {
//	Public Constructors
	public UnknownGroupException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->ActivationException-->UnknownGroupException

Thrown By: Activatable.register(), ActivationGroup.inactiveGroup(), ActivationMonitor.inactiveGroup(), ActivationSystem.{activeGroup(), getActivationGroupDesc(), registerObject(), setActivationDesc(), setActivationGroupDesc(), unregisterGroup()}

UnknownObjectException

Java 1.2

java.rmi.activation

serializable checked

This exception is thrown if an invalid ActivationID is passed as a method argument (e.g., the ID was not generated by the current ActivationSystem).

public class UnknownObjectException extends ActivationException {
//	Public Constructors
	public UnknownObjectException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->ActivationException-->UnknownObjectException

Thrown By: Activatable.{inactive(), unregister()}, ActivationGroup.{activeObject(), inactiveObject()}, ActivationID.activate(), ActivationMonitor.{activeObject(), inactiveObject()}, ActivationSystem.{getActivationDesc(), setActivationDesc(), unregisterObject()}, Activator.activate()