ActivationGroup JDK 1.6)

Description

publicabstract abstract class ActivationGroup

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.

See also: ActivationInstantiator ActivationGroupDesc ActivationGroupID

Methods

Hide/Show inherited methods

protected void activeObject (ActivationID id, MarshalledObject<Remote> mobj) throws ActivationException UnknownObjectException RemoteException

This protected method is necessary for subclasses to make the activeObject callback to the group's monitor.

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.
Parameters:
- id - the object's identifier
- mobj - a marshalled object containing the remote object's stub
Throws:
- UnknownObjectException - if object is not registered
- RemoteException - if call informing monitor fails
- ActivationException - if an activation error occurs
Since: 1.2

publicabstract void activeObject (ActivationID id, Remote obj) throws ActivationException UnknownObjectException RemoteException

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'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.
Parameters:
- id - the object's identifier
- obj - the remote object implementation
Throws:
- UnknownObjectException - if object is not registered
- RemoteException - if call informing monitor fails
- ActivationException - if group is inactive
Since: 1.2

public Object clone () throws CloneNotSupportedException [Inherited From UnicastRemoteObject]

Returns a clone of the remote object that is distinct from the original.

publicstaticsynchronized ActivationGroup createGroup (ActivationGroupID id, ActivationGroupDesc desc, long incarnation) throws ActivationException

Create and set the activation group for the current VM.

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.

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 that 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.
Returns: the activation group for the VM
Parameters:
- id - the activation group's identifier
- desc - the activation group's descriptor
- incarnation - the group's incarnation number (zero on group's initial creation)
Throws:
- ActivationException - if group already exists or if error occurs during group creation
- SecurityException - if permission to create group is denied. (Note: The default implementation of the security manager checkSetFactory method requires the RuntimePermission "setFactory")
Since: 1.2
See Also: SecurityManager.checkSetFactory(),

pack-privatestaticsynchronized ActivationGroup currentGroup () throws ActivationException

Returns the current group for the VM.

publicstaticsynchronized ActivationGroupID currentGroupID ()

Returns the current activation group's identifier.

public boolean equals (Object obj) [Inherited From RemoteObject]

Compares two remote objects for equality.

Compares two remote objects for equality.
Returns a boolean that indicates whether this remote object is
equivalent to the specified Object. This method is used when a
remote object is stored in a hashtable.
If the specified Object is not itself an instance of RemoteObject,
then this method delegates by returning the result of invoking the
equals method of its parameter with this remote object
as the argument.
Returns: true if these Objects are equal; false otherwise.
Parameters:
- obj - the Object to compare with
See Also: Hashtable,

publicstatic RemoteStub exportObject (Remote obj) throws RemoteException [Inherited From UnicastRemoteObject]

Exports the remote object to make it available to receive incoming calls using an anonymous port.

publicstatic Remote exportObject (Remote obj, int port) throws RemoteException [Inherited From UnicastRemoteObject]

Exports the remote object to make it available to receive incoming calls, using the particular supplied port.

publicstatic Remote exportObject (Remote obj, int port, RMIClientSocketFactory csf, RMIServerSocketFactory ssf) throws RemoteException [Inherited From UnicastRemoteObject]

Exports the remote object to make it available to receive incoming calls, using a transport specified by the given socket factory.

publicstatic String getClientHost () throws ServerNotActiveException [Inherited From RemoteServer]

Returns a string representation of the client host for the remote method invocation being processed in the current thread.

publicstatic PrintStream getLog () [Inherited From RemoteServer]

Returns stream for the RMI call log.

public RemoteRef getRef () [Inherited From RemoteObject]

Returns the remote reference for the remote object.

publicstaticsynchronized ActivationSystem getSystem () throws ActivationException

Returns the activation system for the VM.

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.
Returns: the activation system for the VM/group
Throws:
- ActivationException - if activation system cannot be obtained or is not bound (means that it is not running)
Since: 1.2
See Also: ActivationGroup.setSystem(java.rmi.activation.ActivationSystem),

public int hashCode () [Inherited From RemoteObject]

Returns a hashcode for a remote object.

protected void inactiveGroup () throws UnknownGroupException RemoteException

This protected method is necessary for subclasses to make the inactiveGroup callback to the group's monitor.

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.
Throws:
- UnknownGroupException - if group is not registered
- RemoteException - if call informing monitor fails
Since: 1.2

public boolean inactiveObject (ActivationID id) throws ActivationException UnknownObjectException RemoteException

The group's inactiveObject method is called indirectly via a call to the Activatable.inactive method.

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.

Returns: true if the object was successfully deactivated; otherwise returns false.
Parameters:
- id - the object's activation identifier
Throws:
- UnknownObjectException - if object is unknown (may already be inactive)
- RemoteException - if call informing monitor fails
- ActivationException - if group is inactive
Since: 1.2

pack-privatestaticsynchronized ActivationGroupID internalCurrentGroupID () throws ActivationException

Returns the activation group identifier for the VM.

publicstatic void setLog (OutputStream out) [Inherited From RemoteServer]

Log RMI calls to the output stream out.

Log RMI calls to the output stream out. If out is null, call logging is turned off.

If there is a security manager, its checkPermission method will be invoked with a java.util.logging.LoggingPermission("control") permission; this could result in a SecurityException.
Parameters:
- out - the output stream to which RMI calls should be logged
Throws:
- SecurityException - if there is a security manager and the invocation of its checkPermission method fails
Since: JDK1.1
See Also: RemoteServer.getLog(),

publicstaticsynchronized void setSystem (ActivationSystem system) throws ActivationException

Set the activation system for the VM.

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.
Parameters:
- system - remote reference to the ActivationSystem
Throws:
- ActivationException - if activation system is already set
- SecurityException - if permission to set the activation system is denied. (Note: The default implementation of the security manager checkSetFactory method requires the RuntimePermission "setFactory")
Since: 1.2
See Also: ActivationGroup.getSystem(), SecurityManager.checkSetFactory(),

public String toString () [Inherited From RemoteObject]

Returns a String that represents the value of this remote object.

publicstatic Remote toStub (Remote obj) throws NoSuchObjectException [Inherited From RemoteObject]

Returns the stub for the remote object obj passed as a parameter.

Returns the stub for the remote object obj passed
as a parameter. This operation is only valid after
the object has been exported.
Returns: the stub for the remote object, obj.
Parameters:
- obj - the remote object whose stub is needed
Throws:
- NoSuchObjectException - if the stub for the remote object could not be found.
Since: 1.2

publicstatic boolean unexportObject (Remote obj, boolean force) throws NoSuchObjectException [Inherited From UnicastRemoteObject]

Removes the remote object, obj, from the RMI runtime.