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.30 0131 02/12/03/18 @since 1.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 without an explicit 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.39 0141 02/1204/0308 @see ActivationInstantiator @see ActivationGroupDesc @see ActivationGroupID @since 1.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) @see #setSystem @since 1.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 #getSystem @see SecurityManager#checkSetFactory @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.1213 12/03/0118/02 @see ActivationGroup @since 1.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 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.1415 12/03/0118/02 @see Activator @see ActivationMonitor @since 1.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 @see #setActivationDesc @since 1.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 @see #setActivationGroupDesc @since 1.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 @see #getActivationDesc @since 1.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 @see #getActivationGroupDesc @since 1.2