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.
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()
Copyright © 2001 O'Reilly & Associates. All rights reserved.