java.rmi.activation Documentation Differences

This file contains all the changes in documentation in the package java.rmi.activation as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

The Activatable class provides support for remote objects that require persistent access over time and that can be activated by the system. @author Ann Wollrath @version 1.20 0926 02/1102/9800 @since JDK11.2

Constructor used to activate/export the object on a specified port. An "activatable" remote object must have a constructor that takes two arguments:

• the object's activation identifier (ActivationID) and
• the object's initialization data (a MarshalledObject).

A concrete subclass of this class must call this constructor when it is activated via the two parameter constructor described above. 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. @param id activation identifier for the object @param port the port number on which the object is exported @exception RemoteException if exporting the object to the RMI runtime fails @since JDK11.2

Constructor used to activate/export the object on a specified port. An "activatable" remote object must have a constructor that takes two arguments:

• the object's activation identifier (ActivationID) and
• the object's initialization data (a MarshalledObject).

A concrete subclass of this class must call this constructor when it is activated via the two parameter constructor described above. 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. @param id activation identifier for the object @param port the port number on which the object is exported @param csf the client-side socket factory for making calls to the remote object @param ssf the server-side socket factory for receiving remote calls @exception RemoteException if exporting the object to the RMI runtime fails @since JDK11.2

Constructor used to register and export the object on a specified port (an anonymous port is chosen if port=0) . A concrete subclass of this 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=0) to the RMI runtime so that it is available to accept incoming calls from clients. @param location the location for classes for this object @param data the object's initialization data @param port the port on which the object is exported (an anonymous port is used if port=0) @param restart if true the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false the object is only activated on demand. Specifying restart to be true does not force an initial immediate activation of a newly registered object; initial activation is lazy. @exception ActivationException if object registration fails. @exception RemoteException if either of the following fails: a) registering the object with the activation system or b) exporting the object to the RMI runtime. @since JDK11.2

Constructor used to register and export the object on a specified port (an anonymous port is chosen if port=0) .

A concrete subclass of this 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=0) to the RMI runtime so that it is available to accept incoming calls from clients. Note that objects created via this constructor will be activated on demand not restarted when the activation daemon starts. If an activatable objects requires restart when the activation daemon rmid starts use the second Activatable constructor form. @param location the location for classes for this object @param data the object's initialization data @param restart if true the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false the object is only activated on demand. Specifying restart to be true does not force an initial immediate activation of a newly registered object; initial activation is lazy. @param port the port on which the object is exported (an anonymous port is used if port=0) @param csf the client-side socket factory for making calls to the remote object @param ssf the server-side socket factory for receiving remote calls @exception ActivationException if object registration fails. @exception RemoteException if either of the following fails: a) registering the object with the activation system or b) exporting the object to the RMI runtime. @since JDK11.2

Export the activatable remote object to the RMI runtime to make the object 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 second constructor above (which a subclass should invoke from its special activation constructor). @return the stub for the activatable remote object @param obj the remote object implementation @param id the object's activation identifier @param port the port on which the object is exported (an anonymous port is used if port=0) @exception RemoteException if object export fails @since JDK11.2

Export the activatable remote object to the RMI runtime to make the object 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 second constructor above (which a subclass should invoke from its special activation constructor). @return the stub for the activatable remote object @param obj the remote object implementation @param id the object's activation identifier @param port the port on which the object is exported (an anonymous port is used if port=0) @param csf the client-side socket factory for making calls to the remote object @param ssf the server-side socket factory for receiving remote calls @exception RemoteException if object export fails @since JDK11.2

This exportObject method may be invoked explicitly by an "activatable" object that does not extend the Activatable class in order to both a) register the object's activation descriptor constructed from the supplied location and data with the activation system (so the object can be activated) and b) export the remote object obj on a specific port (if port=0 then an anonymous port is chosen). Once the object is exported it can receive incoming RMI calls.

This method does not need to be called if obj extends Activatable since the first constructor calls this method. @param obj the object being exported @param location the object's code location @param data the object's bootstrapping data @param restart if true the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false the object is only activated on demand. Specifying restart to be true does not force an initial immediate activation of a newly registered object; initial activation is lazy. @param port the port on which the object is exported (an anonymous port is used if port=0) @returnsreturn the activation identifier obtained from registering the descriptor desc with the activation system the wrong group @exception ActivationException if activation group is not active @exception RemoteException if object registration or export fails @since JDK11.2

This exportObject method may be invoked explicitly by an "activatable" object that does not extend the Activatable class in order to both a) register the object's activation descriptor constructed from the supplied location and data with the activation system (so the object can be activated) and b) export the remote object obj on a specific port (if port=0 then an anonymous port is chosen). Once the object is exported it can receive incoming RMI calls.

This method does not need to be called if obj extends Activatable since the first constructor calls this method. @param obj the object being exported @param location the object's code location @param data the object's bootstrapping data @param restart if true the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false the object is only activated on demand. Specifying restart to be true does not force an initial immediate activation of a newly registered object; initial activation is lazy. @param port the port on which the object is exported (an anonymous port is used if port=0) @param csf the client-side socket factory for making calls to the remote object @param ssf the server-side socket factory for receiving remote calls @return the activation identifier obtained from registering the descriptor desc with the activation system the wrong group @exception ActivationException if activation group is not active @exception RemoteException if object registration or export fails @since JDK11.2

Returns the object's activation identifier. The method is protected so that only subclasses can obtain an object's identifier. @return the object's activation identifier @since JDK11.2

Informs the system that the object with the corresponding activation id is currently inactive. If the object is currently active the object is "unexported" from the RMI runtime (only if there are no pending or in-progress calls) so the that it can no longer receive incoming calls. This call informs this VM's ActivationGroup that the object is inactive that in turn informs its ActivationMonitor. If this call completes successfully a subsequent activate request to the activator will cause the object to reactivate. The operation may still succeed if the object is considered active but has already unexported itself. @param id the object's activation identifier @returnsreturn true if the operation succeeds (the operation will succeed if the object in currently known to be active and is either already unexported or is currently exported and has no pending/executing calls); false is returned if the object has pending/executing calls in which case it cannot be deactivated @exception UnknownObjectException if object is not known (it may already be inactive) @exception ActivationException if group is not active @exception RemoteException if call informing monitor fails @since JDK11.2

Register an object descriptor for an activatable remote object so that is can be activated on demand. @param desc the object's descriptor @return the stub for the activatable remote object @exception UnknownGroupException if group id in desc is not registered with the activation system @exception ActivationException if activation system is not running @exception RemoteException if remote call fails @since JDK11.2

Remove the remote object obj from the RMI runtime. If successful the object can no longer accept incoming RMI 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. @param obj the remote object to be unexported @param force if true unexports the object even if there are pending or in-progress calls; if false only unexports the object if there are no pending or in-progress calls @return true if operation is successful false otherwise @exception NoSuchObjectException if the remote object is not currently exported @since JDK11.2

Revokes previous registration for the activation descriptor associated with id. An object can no longer be activated via that id. @param id the object's activation identifier @exception UnknownObjectException if object (id) is unknown @exception ActivationException if activation system is not running @exception RemoteException if remote call to activation system fails @since JDK11.2

This exception is thrown by the RMI runtime when activation fails during a remote call to an activatable object. @author Ann Wollrath @version 1.3 077 02/0802/9800 @since JDK11.2

Constructs an ActivateFailedException with the specified detail message. @param s the detail message @since JDK11.2

Constructs an ActivateFailedException with the specified detail message and nested exception. @param s the detail message @param ex the nested exception @since JDK11.2

An activation descriptor contains the information necessary to activate an object:

• the object's group identifier
• the object's fully-qualified class name
• the object's code location (the location of the class) a codebase URL path
• the object's restart "mode" and
• a "marshalled" object that can contain object specific initialization data.

A descriptor registered with the activation system can be used to recreate/activate the object specified by the descriptor. The MarshalledObject in the object's descriptor is passed as the second argument to the remote object's constructor for object to use during reinitialization/activation. @author Ann Wollrath @version 1.19 0824 02/1002/9800 @since JDK11.2 @see java.rmi.activation.Activatable

Constructs an object descriptor for an object whose class name is className that can be loaded from the code location and whose initialization information is data. All objects with the same groupID are activated in the same Java VM.

Note that objects specified by a descriptor created with this constructor will only be activated on demand (by default the restart mode is false). If an activatable object requires restart services use one of the ActivationDesc constructors that takes a boolean parameter restart. @param groupID the group's identifier (obtained from registering ActivationSystem.registerGroup method). The group indicates the VM in which the object should be activated. @param className the object's fully package-qualified class name @param location the object's code location (from where the class is loaded) @param data the object's initialization (activation) data contained in marshalled form. @exception IllegalArgumentException if groupID is null @since JDK11.2

Constructs an object descriptor for an object whose class name is className that can be loaded from the code location and whose initialization information is data. All objects with the same groupID are activated in the same Java VM. @param groupID the group's identifier (obtained from registering ActivationSystem.registerGroup method). The group indicates the VM in which the object should be activated. @param className the object's fully package-qualified class name @param location the object's code location (from where the class is loaded) @param data the object's initialization (activation) data contained in marshalled form. @param restart if true the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false the object is only activated on demand. Specifying restart to be true does not force an initial immediate activation of a newly registered object; initial activation is lazy. @exception IllegalArgumentException if groupID is null @since JDK11.2

Constructs an object descriptor for an object whose class name is className that can be loaded from the code location and whose initialization information is data. If this form of the constructor is used the groupID defaults to the current id for ActivationGroup for this VM. All objects with the same ActivationGroupID are activated in the same VM. Objects

Note that objects specified by a descriptor created bywith this constructor will notonly restart automatically when thebe activated on demand RMI(by activation daemon starts but willdefault the restart mode is befalse). activated on demandIf an activatable (viaobject a method callrequires restart services touse one of the activatableActivationDesc object)constructors that takes a boolean parameter restart.

This constructor will throw ActivationException if there is no current activation group for this VM. To create an ActivationGroup use the ActivationGroup.createGroup method. @param className the object's fully package qualified class name @param location the object's code location (from where the class is loaded) @param data the object's initialization (activation) data contained in marshalled form. @exception ActivationException if the current group is nonexistent @since JDK11.2

Constructs an object descriptor for an object whose class name is className that can be loaded from the code location and whose initialization information is data. If this form of the constructor is used the groupID defaults to the current id for ActivationGroup for this VM. All objects with the same ActivationGroupID are activated in the same VM.

This constructor will throw ActivationException if there is no current activation group for this VM. To create an ActivationGroup use the ActivationGroup.createGroup method. @param className the object's fully package qualified class name @param location the object's code location (from where the class is loaded) @param data the object's initialization (activation) data contained in marshalled form. @param restart if true the object is restarted (reactivated) when either the activator is restarted or the object's activation group is restarted after an unexpected crash; if false the object is only activated on demand. Specifying restart to be true does not force an initial immediate activation of a newly registered object; initial activation is lazy. @exception ActivationException if the current group is nonexistent @since JDK11.2

Compares two activation descriptors for content equality. @param obj the Object to compare with @return true if these Objects are equal; false otherwise. @see java.util.Hashtable @since JDK11.2

Returns the class name for the object specified by this descriptor. @return the class name @since JDK11.2

Returns a "marshalled object" containing intialization/activation data for the object specified by this descriptor. @return the object specific "initialization" data @since JDK11.2

Returns the group identifier for the object specified by this descriptor. A group provides a way to aggregate objects into a single Java virtual machine. RMI creates/activates objects with the same groupID in the same virtual machine. @return the group identifier @since JDK11.2

Returns the code location for the object specified by this descriptor. @return the code location @since JDK11.2

Returns the "restart" mode of the object associated with this activation descriptor. @return true if the activatable object associated with this activation descriptor should beis restarted via the activation daemon when either the daemon comes up or the object's group is restarted after an unexpected crash; otherwise it returns false (meaning that the object is only activated on demand via a method call). Note that if the restart mode is true the activator does not force an initial immediate activation of a newly registered object; initial activation is lazy. @since JDK11.2

General exception used by the activation interfaces. @author Ann Wollrath @version 1.14 0719 02/0802/9800 @since JDK11.2

Constructs an ActivationException with no specified detail message. @since JDK11.2

Constructs an ActivationException with detail message s. @param s the detail message @since JDK11.2

Constructs an ActivationException with detail message s and detail exception ex. @param s detail message @param ex detail exception @since JDK11.2

Produces the message include the message from the nested exception if there is one. @return the message @since JDK11.2

Prints the composite message to System.err. @since JDK11.2

Prints the composite message and the embedded stack trace to the specified stream ps. @param ps the print stream @since JDK11.2

Prints the composite message and the embedded stack trace to the specified print writer pw. @param pw the print writer @since JDK11.2

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

An ActivationGroup is initially created in one of several ways:

• as a side-effect of creating an ActivationDesc (using its first constructor) for the first activatable object in the group or
• via the ActivationGroup.createGroup method
• as a side-effect of activating the first object in a group whose ActivationGroupDesc was only registered.

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

• the group's ActivationGroupID and
• the group's initialization data (in a java.rmi.MarshalledObject)

When created the default implementation of ActivationGroup will override the system properties with the properties requested when its ActivationGroupDesc was created and will set a java.rmi.RMISecurityManager as the default system security manager. If your application requires specific properties to be set when objects are activated in the group the application should create a special Properties object containing these properties then create an ActivationGroupDesc with the Properties object and use ActivationGroup.createGroup before creating any ActivationDescs (before the default ActivationGroupDesc is created). If your application requires the use of a security manager other than java.rmi.RMISecurityManager in the ActivativationGroupDescriptor properties list you can set java.security.manager property to the name of the security manager you would like to install. @author Ann Wollrath @version 1.2733 0402/2202/9900 @see ActivationInstantiator @see ActivationGroupDesc @see ActivationGroupID @since JDK11.2

Constructs and exports an activation group as a UnicastRemoteObject so that a client can invoke its newInstance method. @param groupID the group's identifier @exception RemoteException if group could not be exported @since JDK11.2

This protected method is necessary for subclasses to make the activeObject callback to the group's monitor. The call is simply forwarded to the group's ActivationMonitor. @param id the object's identifier @param mobj a marshalled object containing the remote object's stub @exception UnknownObjectException if object is not registered @exception RemoteException if call informing monitor fails @exception ActivationException if an activation error occurs @since JDK11.2

The group's activeObject method is called when an object is exported (either by Activatable object construction or an explicit call to Activatable.exportObject. The group must inform its ActivationMonitor that the object is active (via the monitor's activeObject method) if the group hasn't already done so. @param id the object's identifier @param obj the remote object implementation @exception UnknownObjectException if object is not registered @exception RemoteException if call informing monitor fails @exception ActivationException if group is inactive @since JDK11.2

Create and set the activation group for the current VM. The activation group can only be set if it is not currently set. An activation group is set using the createGroup method when the Activator initiates the re-creation of an activation group in order to carry out incoming activate requests. A group must first be registered with the ActivationSystem before it can be created via this method. If there is a security manager this method first calls the security manager's checkSetFactory method. This could result in a SecurityException.

The group class specified by the ActivationGroupDesc must be a concrete subclass of ActivationGroup and have a public constructor that takes two arguments: the ActivationGroupID for the group and the MarshalledObject containing the group's initialization data (obtained from the ActivationGroupDesc.

If the group class name specified in the ActivationGroupDesc is null then this method will behave as if the group descriptor contained the name of the default activation group implementation class.

Note: Ifthat if your application creates its own custom activation group a security manager must be set for that group. Otherwise objects cannot be activated in the group. java.rmi.RMISecurityManager is set by default.

If a security manager is already set in the group VM this method first calls the security manager's checkSetFactory method. This could result in a SecurityException. If your application needs to set a different security manager you must ensure that the policy file specified by the group's ActivationGroupDesc grants the group the necessary permissions to set a new security manager. (Note: This will be necessary if your group downloads and sets a security manager).

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 it is taken care of by this method.

Once a group is created subsequent calls to the currentGroupID method will return the identifier for this group until the group becomes inactive. @param id the activation group's identifier @param desc the activation group's descriptor @param incarnation the group's incarnation number (zero on group's initial creation) @return the activation group for the VM @exception ActivationException if group already exists or if error occurs during group creation @exception SecurityException if permission to create group is denied. (Note: The default implementation of the security manager checkSetFactory method requires the RuntimePermission "setFactory") @see SecurityManager#checkSetFactory @since JDK11.2

Returns the current activation group's identifier. Returns null if no group is currently active for this VM. @return the activation group's identifier @since JDK11.2

Returns the activation system for the VM. The activation system may be set by the setSystem method. If the activation system is not set via the setSystem method then the getSystem method attempts 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. @return the activation system for the VM/group @exception ActivationException if activation system cannot be obtained or is not bound (means that it is not running) @since JDK11.2

This protected method is necessary for subclasses to make the inactiveGroup callback to the group's monitor. The call is simply forwarded to the group's ActivationMonitor. Also the current group for the VM is set to null. @exception UnknownGroupException if group is not registered @exception RemoteException if call informing monitor fails @since JDK11.2

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 from the RMI runtime so that the object can no longer receive incoming RMI calls. An object will only be unexported if the object has no pending or executing calls. The subclass of ActivationGroup must override this method and unexport the object.

After removing the object from the RMI runtime the group must inform its ActivationMonitor (via the monitor's inactiveObject method) that the remote object is not currently active so that the remote object will be re-activated by the activator upon a subsequent activation request.

This method simply informs the group's monitor that the object is inactive. It is up to the concrete subclass of ActivationGroup to fulfill the additional requirement of unexporting the object.

@param id the object's activation identifier @return true if the object was successfully deactivated; otherwise returns false. @exception UnknownObjectException if object is unknown (may already be inactive) @exception RemoteException if call informing monitor fails @exception ActivationException if group is inactive @since JDK11.2

Set the activation system for the VM. The activation system can only be set it if no group is currently active. If the activation system is not set via this call then the getSystem method attempts 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 there is a security manager this method first calls the security manager's checkSetFactory method. This could result in a SecurityException. @param system remote reference to the ActivationSystem @exception ActivationException if activation system is already set @exception SecurityException if permission to set the activation system is denied. (Note: The default implementation of the security manager checkSetFactory method requires the RuntimePermission "setFactory") @see SecurityManager#checkSetFactory @since JDK11.2

An activation group descriptor contains the information necessary to create/recreate an activation group in which to activate objects. Such a descriptor contains:

• the group's class name
• the group's code location (the location of the group's class) and
• a "marshalled" object that can contain group specific initialization data.

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

• the group's ActivationGroupID and
• the group's initialization data (in a java.rmi.MarshalledObject)

@version 1.17 1024 02/1702/9800 @author Ann Wollrath @since JDK11.2 @see ActivationGroup @see ActivationGroupID

Startup options for ActivationGroup implementations. This class allows overriding default system properties and specifying implementation-defined options for ActivationGroups. @since JDK11.2

Create a CommandEnvironment with all the necessary information. @param cmdpath the name of the java executable including the full path or null meaning "use rmid's default". The named program must be able to accept multiple -Dpropname=value options (as documented for the "java" tool) @param argv extra options which will be used in creating the ActivationGroup. Null has the same effect as an empty list. @since JDK11.2

Compares two command environments for content equality. @param obj the Object to compare with @return true if these Objects are equal; false otherwise. @see java.util.Hashtable @since JDK11.2

Fetch the configured java command options. @return An array of the command options which will be passed to the new child command by rmid. Note that rmid may add other options before or after these options or both. Never returns null. @since JDK11.2

Fetch the configured path-qualified java command name. @return the configured name or null if configured to accept the default @since JDK11.2

Return identical values for similar CommandEnvironments. @return an integer @see java.util.Hashtable

Constructs a group descriptor that uses the system defaultdefaults for group implementation and code location. Properties specify Java environment overrides (which will override system properties in the group implementation's VM). The command environment can control the exact command/options used in starting the child VM 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. @param propertiesoverrides the set of properties to set when the group is recreated. @param cmd the controlling options for executing the VM in another process (or null). @since JDK11.2

Specifies an alternate group implementation and execution environment to be used for the group. @param className the group's fully package qualified classNameclass name or null. A null group class name indicates the system's default ActivationGroup implementation. @param location the location from where to load the group's class @param data the group's initialization data contained in marshalled form (could contain properties for example) @param overrides a properties map which will override those set by default in the subprocess environment (will be translated into -D options) or null. @param cmd the controlling options for executing the VM in another process (or null). @since JDK11.2

Compares two activation group descriptors for content equality. @param obj the Object to compare with @return true if these Objects are equal; false otherwise. @see java.util.Hashtable @since JDK11.2

Returns the group's class name (possibly null). A null group class name indicates the system's default ActivationGroup implementation. @return the group's class name @since JDK11.2

Returns the group's command-environment control object. @return the command-environment object or null @since JDK11.2

Returns the group's initialization data. @return the group's initialization data @since JDK11.2

Returns the group's code location. @return the group's code location @since JDK11.2

Returns the group's property-override list. @return the property-override list or null @since JDK11.2

The identifier for a registered activation group serves several purposes:

• identifies the group uniquely within the activation system and
• contains a reference to the group's activation system so that the group can contact its activation system when necessary.

The ActivationGroupID is returned from the call to ActivationSystem.registerGroup and is used to identify the group within the activation system. This group id is passed as one of the arguments to the activation group's special constructor when an activation group is created/recreated. @author Ann Wollrath @version 1.8 0712 02/0802/9800 @see ActivationGroup @see ActivationGroupDesc @since JDK11.2

Constructs a unique group id. @param system the group's activation system @since JDK11.2

Compares two group identifiers for content equality. 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. @param obj the Object to compare with @return true if these Objects are equal; false otherwise. @see java.util.Hashtable @since JDK11.2

Returns the group's activation system. @return the group's activation system @since JDK11.2

Returns a hashcode for the group's identifier. Two group identifiers that refer to the same remote group will have the same hash code. @see java.util.Hashtable @since JDK11.2

Activation makes use of special 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:

• a remote reference to the object's activator and
• a unique identifier for the object.

An activation id for an object can be obtained by registering an object with the activation system. Registration is accomplished in a few ways:

• via the Activatable.register method
• via the first Activatable constructor (that takes three arguments and both registers and exports the object and
• via the first Activatable.exportObject method that takes the activation descriptor object and port as arguments; this method both registers and exports the object.

@author Ann Wollrath @version 1.15 0719 02/0802/9800 @see Activatable @since JDK11.2

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 identifier. An instance of ActivationID is globally unique. @param activator reference to the activator responsible for activating the object @since JDK11.2

Activate the object for this id. @param force if true forces the activator to contact the group when activating the object (instead of returning a cached reference); if false returning a cached value is acceptable. @return the reference to the active remote object @exception ActivationException if activation fails @exception UnknownObjectException if the object is unknown @exception RemoteException if remote call fails @since JDK11.2

Compares two activation ids for content equality. Returns true if both of the following conditions are true: 1) the unique identifiers equivalent (by content) and 2) the activator specified in each identifier refers to the same remote object. @param obj the Object to compare with @return true if these Objects are equal; false otherwise. @see java.util.Hashtable @since JDK11.2

Returns a hashcode for the activation id. Two identifiers that refer to the same remote object will have the same hash code. @see java.util.Hashtable @since JDK11.2

An 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. @author Ann Wollrath @version 1.7 0711 02/0802/9800 @see ActivationGroup @since JDK11.2

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

• determining the class for the object using the descriptor's getClassName method
• loading the class from the code location obtained from the descriptor (using the getLocation method)
• creating an instance of the class by invoking the special "activation" constructor of the object's class that takes two arguments: the object's ActivationID and the MarshalledObject containing object specific initialization data and
• returning a MarshalledObject containing the stub for the remote object it created

  @param id the object's activation identifier @param desc the object's descriptor @return a marshalled object containing the serialized representation of remote object's stub @exception ActivationException if object activation fails @exception RemoteException if remote call fails @since JDK11.2

An ActivationMonitor is specific to an ActivationGroup and is obtained when a group is reported active via a call to ActivationSystem.activeGroup (this is done internally). An activation group is responsible for informing its ActivationMonitor when either: its objects become active or inactive or the group as a whole becomes inactive. @author Ann Wollrath @version 1.8 0712 02/1202/9800 @see Activator @see ActivationSystem @see ActivationGroup @since JDK11.2

Informs that an object is now active. An ActivationGroup informs its monitor if an object in its group becomes active by other means than being activated directly (i.e. the object is registered and "activated" itself). @param id the active object's id @param obj the marshalled form of the object's stub @exception UnknownObjectException if object is unknown @exception RemoteException if remote call fails @since JDK11.2

Informs that the group is now inactive. The group will be recreated 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. @param id the group's id @param incarnation the group's incarnation number @exception UnknownGroupException if group is unknown @exception RemoteException if remote call fails @since JDK11.2

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 VM is no longer active via calls 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.

@param id the object's activation identifier @exception UnknownObjectException if object is unknown @exception RemoteException if remote call fails @since JDK11.2

The ActivationSystem provides a means for registering groups and "activatable" objects to be activated within those groups. The ActivationSystem works closely with the Activator which activates objects registered via the ActivationSystem and the ActivationMonitor which obtains information about active and inactive objects and inactive groups. @author Ann Wollrath @version 1.8 0713 02/0802/9800 @see Activator @see ActivationMonitor @since JDK11.2

Callback to inform activation system that group is now active. This call is made internally by the ActivationGroup.createGroup method to inform the ActivationSystem that the group is now active. @param id the activation group's identifier @param group the group's instantiator @param incarnation the group's incarnation number @return monitor for activation group @exception UnknownGroupException if group is not registered @exception ActivationException if group is already active @exception RemoteException if remote call fails @since JDK11.2

Returns the activation descriptor for the object with the activation identifier id. @param id the activation identifier for the activatable object @exception UnknownObjectException if id is not registered @exception ActivationException for general failure @exception RemoteException if remote call fails @return the activation descriptor @since JDK11.2

Returns the activation group descriptor for the group with the activation group identifier id. @param id the activation group identifier for the group @exception UnknownGroupException if id is not registered @exception ActivationException for general failure @exception RemoteException if remote call fails @return the activation group descriptor @since JDK11.2

Register the activation group. An activation group must be registered with the ActivationSystem before objects can be registered within that group. @param desc the group's descriptor @return an identifier for the group @exception ActivationException if group registration fails @exception RemoteException if remote call fails @since JDK11.2

The registerObject method is used to register an activation descriptor desc and obtain an activation identifier for a activatable remote object. The ActivationSystem creates an ActivationID (a activation identifier) for the object specified by the descriptor desc and records in stable storage the activation descriptor and its associated identifier for later use. When the Activator receives an activate request for a specific identifier it looks up the activation descriptor (registered previously) for the specified identifier and uses that information to activate the object.

@param desc the object's activation descriptor @return the activation id that can be used to activate the object @exception ActivationException if registration fails (e.g. database update failure etc). @exception UnknownGroupException if group referred to in desc is not registered with this system @exception RemoteException if remote call fails @since JDK11.2

Set the activation descriptor desc for the object with the activation identifier id. The change will take effect upon subsequent activation of the object. @param id the activation identifier for the activatable object @param desc the activation descriptor for the activatable object @exception UnknownGroupException the group associated with desc is not a registered group @exception UnknownObjectException the activation id is not registered @exception ActivationException for general failure (e.g. unable to update log) @exception RemoteException if remote call fails @return the previous value of the activation descriptor @since JDK11.2

Set the activation group descriptor desc for the object with the activation group identifier id. The change will take effect upon subsequent activation of the group. @param id the activation group identifier for the activation group @param desc the activation group descriptor for the activation group @exception UnknownGroupException the group associated with id is not a registered group @exception ActivationException for general failure (e.g. unable to update log) @exception RemoteException if remote call fails @return the previous value of the activation group descriptor @since JDK11.2

Shutdown the activation system. Destroys all groups spawned by the activation daemon and exits the activation daemon. @exception RemoteException if failed to contact/shutdown the activation daemon @since JDK11.2

Remove the activation group. An activation group makes this call back to inform the activator that the group should be removed (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. @param id the activation group's identifier @exception ActivationException if unregister fails (e.g. database update failure etc). @exception UnknownGroupException if group is not registered @exception RemoteException if remote call fails @since JDK11.2

Remove the activation id and associated descriptor previously registered with the ActivationSystem; the object can no longer be activated via the object's activation id. @param id the object's activation id (from previous registration) @exception ActivationException if unregister fails (e.g. database update failure etc). @exception UnknownObjectException if object is unknown (not registered) @exception RemoteException if remote call fails @since JDK11.2

The port to lookup the activation system.

The Activator facilitates remote object activation. A "faulting" remote reference calls the activator's activate method to obtain a "live" reference to a "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 initiates object re-creation via the group's ActivationInstantiator (via a call to the newInstance method). The activator initiates the execution of activation groups as necessary. For example if an activation group for a specific group identifier is not already executing the activator initiates the execution of a VM for the group.

The Activator works closely with ActivationSystem which provides a means for registering groups and objects within those groups and ActivationMonitor which recives information about active and inactive objects and inactive groups.

The activator is responsible for monitoring and detecting when activation groups fail so that it can remove stale remote references to groups and active object's within those groups.

@author Ann Wollrath @version 1.11 0915 02/2102/9800 @see ActivationInstantiator @see ActivationGroupDesc @see ActivationGroupID @since JDK11.2

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

If the activation group for the object's group descriptor does not yet exist the activator starts an ActivationInstantiator executing (by spawning a child process for example). When the activator receives the activation group's call back (via the ActivationSystem's activeGroup method) specifying the activation group's reference the activator can then invoke that activation instantiator's newInstance method to forward each pending activation request to the activation group and return the result (a marshalled remote object reference a stub) to the caller.

Note that the activator receives a "marshalled" object 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.

@param id the activation identifier for the object being activated @param force if true the activator contacts the group to obtain the remote object's reference; if false returning the cached value is allowed. @return the remote object (a stub) in a marshalled form @exception ActivationException if object activation fails @exception UnknownObjectException if object is unknown (not registered) @exception RemoteException if remote call fails @since JDK11.2

An UnknownGroupException is thrown by methods of classes and interfaces in the java.rmi.activation package when the ActivationGroupID parameter to the method is determined to be invalid i.e. not known by the ActivationSystem. An UnknownGroupException is also thrown if the ActivationGroupID in an ActivationDesc refers to a group that is not registered with the ActivationSystem @version 1.6 0710 02/0802/9800 @author Ann Wollrath @since JDK11.2 @see java.rmi.activation.Activatable @see java.rmi.activation.ActivationGroup @see java.rmi.activation.ActivationGroupID @see java.rmi.activation.ActivationMonitor @see java.rmi.activation.ActivationSystem

Constructs an UnknownGroupException with the specified detail message. @param s the detail message @since JDK11.2

An UnknownObjectException is thrown by methods of classes and interfaces in the java.rmi.activation package when the ActivationID parameter to the method is determined to be invalid. An ActivationID is invalid if it is not currently known by the ActivationSystem. An ActivationID is obtained by the ActivationSystem.registerObject method. An ActivationID is also obtained during the Activatable.register call. @version 1.4 078 02/0802/9800 @author Ann Wollrath @since JDK11.2 @see java.rmi.activation.Activatable @see java.rmi.activation.ActivationGroup @see java.rmi.activation.ActivationID @see java.rmi.activation.ActivationMonitor @see java.rmi.activation.ActivationSystem @see java.rmi.activation.Activator

Constructs an UnknownObjectException with the specified detail message. @param s the detail message @since JDK11.2