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.26 0230 01/0212/0003 @since 1.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.7 028 12/0203/0001 @since 1.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.24 0225 12/0203/0001 @since 1.2 @see java.rmi.activation.Activatable

General exception used by the activation interfaces.

As of release 1.4 this exception has been retrofitted to conform to the general purpose exception-chaining mechanism. The "detail exception" that may be provided at construction time and accessed via the public #detail field is now known as the cause and may be accessed via the Throwable#getCause() method as well as the aforementioned "legacy field." @author Ann Wollrath @version 1.19 0221 12/0203/0001 @since 1.2

ProducesReturns the detail message includeincluding the message from the nesteddetail exception if there is one. @return the detail message including detail exception message if any @since 1.2

Nested Exception to hold wrapped remote exceptions.

This field predates the general-purpose exception chaining facility. The Throwable#getCause() method is now the preferred means of obtaining this information. @serial

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 (usingwithout its firstan explicit constructor)ActivationGroupID 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.33 0239 01/0212/0003 @see ActivationInstantiator @see ActivationGroupDesc @see ActivationGroupID @since 1.2

Constructs and exports an activation group as a UnicastRemoteObject so thatwith the given activation group aidentifier. clientThe cangroup is invoke its newInstanceexported as a methodjava.rmi.server.UnicastRemoteObject. @param groupID the group's identifier @exceptionthrows RemoteException if this group could not be exported @since 1.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.24 0225 12/0203/0001 @author Ann Wollrath @since 1.2 @see ActivationGroup @see ActivationGroupID

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.12 0213 12/0203/0001 @see ActivationGroup @see ActivationGroupDesc @since 1.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 (a RemoteRef instance) and
• a unique identifier (a UID instance) for the object.

An activation ididentifier 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.1923 0201/0212/0003 @see Activatable @since 1.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.11 0212 12/0203/0001 @see ActivationGroup @since 1.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.12 0213 12/0203/0001 @see Activator @see ActivationSystem @see ActivationGroup @since 1.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.13 0214 12/0203/0001 @see Activator @see ActivationMonitor @since 1.2

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.15 0216 12/0203/0001 @see ActivationInstantiator @see ActivationGroupDesc @see ActivationGroupID @since 1.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.10 0211 12/0203/0001 @author Ann Wollrath @since 1.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

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.8 029 12/0203/0001 @author Ann Wollrath @since 1.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