com.sun.jini.phoenix

Class ActivationGroupImpl

java.lang.Object

java.rmi.server.RemoteObject

java.rmi.server.RemoteServer

java.rmi.server.UnicastRemoteObject

java.rmi.activation.ActivationGroup

net.jini.activation.ActivationGroup

com.sun.jini.phoenix.ActivationGroupImpl

All Implemented Interfaces:

Serializable, ActivationInstantiator, Remote, ServerProxyTrust

public class ActivationGroupImpl
extends ActivationGroup
implements ServerProxyTrust

The default activation group implementation for phoenix. Instances of this class are configurable through a Configuration, as detailed further below, and provide the necessary support to allow exporter-based remote objects to go inactive. Instances of this class support the creation of remote objects through the normal activatable constructor; an activatable remote object must either implement the ProxyAccessor interface to return a suitable proxy for the remote object, or the remote object must itself be serializable and marshalling the object must produce a suitable proxy for the remote object.

An instance of this class can be configured by specifying an ActivationGroupData instance containing configuration options as the initialization data for the activation group. Typically this is accomplished indirectly, by setting the groupConfig configuration entry for phoenix itself. The following entries are obtained from the configuration, all for the component named com.sun.jini.phoenix:

•	loginContext
	Type:	LoginContext
	Default:	null
	Description:	JAAS login context

•	inheritGroupSubject
	Type:	boolean
	Default:	false
	Description:	if true, group subject is inherited when an activatable object is created

•	instantiatorExporter
	Type:	Exporter
	Default:	retains existing JRMP export of instantiator
	Description:	ActivationInstantiator exporter

•	monitorPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	ActivationMonitor proxy preparer

•	systemPreparer
	Type:	ProxyPreparer
	Default:	new BasicProxyPreparer()
	Description:	ActivationSystem proxy preparer

•	unexportTimeout
	Type:	int
	Default:	60000
	Description:	maximum time in milliseconds to wait for in-progress calls to finish before forcibly unexporting the group when going inactive

•	unexportWait
	Type:	int
	Default:	10
	Description:	milliseconds to wait between unexport attempts when going inactive

This class depends on its createGroup method being called to initialize the activation group. As such, this class cannot be used in conjunction with the standard rmid.

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Field Summary

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

Constructors

Constructor and Description
ActivationGroupImpl(ActivationGroupID id, MarshalledObject data) Creates an instance with the specified group identifier and initialization data.

Method Summary

Methods

Modifier and Type	Method and Description
void	activeObject(ActivationID id, Remote impl) Marks the object as active in this virtual machine, and calls the superclass activeObject method with the same arguments, with the ActivationMonitor constraints (if any) set as contextual client constraints, and with the group's subject (if any) set as the executing subject.
static ActivationGroup	createGroup(ActivationGroupID id, ActivationGroupDesc desc, long incarnation) Creates an ActivationGroup instance and returns it.
TrustVerifier	getProxyVerifier() Returns a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service; that is, the isTrustedObject method of the returned verifier can be called with a candidate proxy.
boolean	inactiveObject(ActivationID id) Attempts to make the remote object that is associated with the specified activation identifier, and that was exported as a JRMP Activatable object, inactive.
boolean	inactiveObject(ActivationID id, Exporter exporter) Attempts to make the remote object that is associated with the specified activation identifier, and that was exported through the specified exporter, inactive.
MarshalledObject	newInstance(ActivationID id, ActivationDesc desc) Creates a new instance of an activatable remote object and returns a marshalled object containing the activated object's proxy.
protected Object	writeReplace() Returns the proxy for this remote object.

Methods inherited from class net.jini.activation.ActivationGroup

inactive

Methods inherited from class java.rmi.activation.ActivationGroup

activeObject, currentGroupID, getSystem, inactiveGroup, setSystem

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ActivationGroupImpl

public ActivationGroupImpl(ActivationGroupID id,
                   MarshalledObject data)
                    throws ActivationException,
                           RemoteException

Creates an instance with the specified group identifier and initialization data. This constructor must be called indirectly, via createGroup. By default, this instance automatically exports itself as a UnicastRemoteObject. (This is a limitation of the existing activation system design.) If an Exporter was obtained by createGroup, then this instance is unexported from the JRMP runtime and re-exported using that exporter. (Any incoming remote calls received on the original JRMP export before this instance can be unexported will be refused with a security exception thrown.) The activeGroup method of the activation system proxy (in the group identifier) is called to make the group active. The returned ActivationMonitor proxy is passed to the corresponding ProxyPreparer obtained by createGroup. Note that after this constructor returns, ActivationGroup.createGroup will also call activeGroup (so the activation system must accept idempotent calls to that method), but the ActivationMonitor proxy returned by that call will not be used.

Parameters:

id - the activation group identifier

data - group initialization data (ignored)

Throws:

RemoteException - if the group could not be exported or made active, or proxy preparation fails

ActivationException - if the constructor was not called indirectly from createGroup

Method Detail

createGroup

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

Creates an ActivationGroup instance and returns it. An ActivationGroupData instance is extracted from the initialization data, and a Configuration is obtained by calling Configuration.Provider.getInstance with the configuration options from that instance. A LoginContext is obtained from the loginContext configuration entry, if one exists; if the value is not null, a login is performed on that context, and the resulting Subject (set to be read-only) is used as the subject when executing the rest of this method. The subject is also used for all subsequent remote calls by this class to the ActivationMonitor. The ActivationSystem proxy (obtained from the ActivationGroupID) is passed to the ProxyPreparer given by the systemPreparer configuration entry, if one exists; a new ActivationGroupID is constructed with the resulting proxy. An Exporter instance is obtained from the instantiatorExporter configuration entry, if one exists; this exporter will be used (in the constructor of this class) to export the group. A ProxyPreparer instance is obtained from the monitorPreparer configuration entry, if one exists; this preparer will be used (in the constructor of this class) to prepare the ActivationMonitor. A call is then made to ActivationGroup.createGroup with the new group identifier, the activation group descriptor, and the group incarnation number, and the result of that call is returned.

Parameters:

id - the activation group identifier

desc - the activation group descriptor

incarnation - the group's incarnation number (zero on initial creation)

Returns:

the created activation group

Throws:

ActivationException - if a group already exists or if an exception occurs during group creation

getProxyVerifier

public TrustVerifier getProxyVerifier()

Description copied from interface: ServerProxyTrust

Returns a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service; that is, the isTrustedObject method of the returned verifier can be called with a candidate proxy. The verifier should be able to verify all proxies for the service, including proxies for resources (such as leases and registrations).

Specified by:

getProxyVerifier in interface ServerProxyTrust

Returns:

a TrustVerifier that can be used to verify that a proxy can be trusted as a proxy for the service

writeReplace

protected Object writeReplace()

Returns the proxy for this remote object. Group creation was designed to rely on automatic stub replacement (as provided by the JRMP runtime), which is not supported by all exporters.

Returns:

the proxy for this remote object

newInstance

public MarshalledObject newInstance(ActivationID id,
                           ActivationDesc desc)
                             throws ActivationException

Creates a new instance of an activatable remote object and returns a marshalled object containing the activated object's proxy.

If an active object already exists for the specified identifier, the existing marshalled object for it is returned.

Otherwise:

The class for the object is loaded by invoking RMIClassLoader.loadClass passing the class location (obtained by invoking getLocation on the activation descriptor) and the class name (obtained by invoking getClassName on the activation descriptor).

The new instance is constructed as follows. If the class defines a constructor with two parameters of type ActivationID and MarshalledObject, that constructor is called with the specified activation identifier and the initialization data from the specified activation descriptor. Otherwise, an ActivationException is thrown.

If the class loader of the object's class is a descendant of the current context class loader, then that class loader is set as the context class loader when the constructor is called.

If the inheritGroupSubject configuration entry is true then the constructor is invoked in an action passed to the Security.doPrivileged method; otherwise the constructor is invoked in an action passed to the AccessController.doPrivileged method.

A proxy for the newly created instance is returned as follows:

• If the newly created instance implements ProxyAccessor, a proxy is obtained by invoking the getProxy method on that instance. If the obtained proxy is not null, that proxy is returned in a MarshalledObject; otherwise, an ActivationException is thrown.
• If the newly created instance does not implement ProxyAccessor, the instance is returned in a MarshalledObject. In this case, the instance must be serializable, and marshalling the instance must produce a suitable proxy for the remote object (for example, the object implements Serializable and defines a writeReplace method that returns the object's proxy).

If both the remote object and the activation group are exported using JRMP, then automatic stub replacement will produce the desired result, but otherwise the remote object implementation must provide a means for this group to obtain its proxy as indicated above.

Specified by:

newInstance in interface ActivationInstantiator

Throws:

ActivationException - if the object's class could not be loaded, if the loaded class does not define the appropriate constructor, or any exception occurs activating the object

inactiveObject

public boolean inactiveObject(ActivationID id)
                       throws ActivationException,
                              RemoteException

Attempts to make the remote object that is associated with the specified activation identifier, and that was exported as a JRMP Activatable object, inactive. This method calls Activatable.unexportObject with the active remote object and false, to unexport the object. If that call returns false, this method returns false. If that call returns true, the object is marked inactive in this virtual machine, the superclass inactiveObject method is called with the same activation identifier, with the ActivationMonitor constraints (if any) set as contextual client constraints, and with the group's subject (if any) set as the executing subject, and this method returns true.

Overrides:

inactiveObject in class ActivationGroup

Parameters:

id - the activation identifier

Returns:

true if the object was successfully made inactive; false otherwise

Throws:

UnknownObjectException - if the object is not known to be active (it may already be inactive)

ActivationException - if an activation error occurs

InactiveGroupException - if the group is inactive

RemoteException - if the remote call to the activation monitor fails

SecurityException - if a security manager exists and invoking its checkPermission method with the permission MonitorPermission("java.rmi.activation.ActivationMonitor.inactiveObject") throws a SecurityException

inactiveObject

public boolean inactiveObject(ActivationID id,
                     Exporter exporter)
                       throws ActivationException,
                              RemoteException

Attempts to make the remote object that is associated with the specified activation identifier, and that was exported through the specified exporter, inactive. The unexport method of the specified exporter is called with false as an argument. If that call returns false, this method returns false. If that call returns true, the object is marked inactive in this virtual machine, the superclass inactiveObject method is called with the activation identifier, with the ActivationMonitor constraints (if any) set as contextual client constraints, and with the group's subject (if any) set as the executing subject, and this method returns true.

Specified by:

inactiveObject in class ActivationGroup

Parameters:

id - the activation identifier

exporter - the exporter to use to unexport the object

Returns:

true if the object was successfully made inactive; false otherwise

Throws:

UnknownObjectException - if the object is not known to be active (it may already be inactive)

ActivationException - if an activation error occurs

InactiveGroupException - if the group is inactive

RemoteException - if the remote call to the activation monitor fails

SecurityException - if a security manager exists and invoking its checkPermission method with the permission MonitorPermission("java.rmi.activation.ActivationMonitor.inactiveObject") throws a SecurityException

activeObject

public void activeObject(ActivationID id,
                Remote impl)
                  throws ActivationException

Marks the object as active in this virtual machine, and calls the superclass activeObject method with the same arguments, with the ActivationMonitor constraints (if any) set as contextual client constraints, and with the group's subject (if any) set as the executing subject. Any RemoteException thrown by this call is caught and ignored. If the object is already marked as active in this virtual machine, this method simply returns.

Specified by:

activeObject in class ActivationGroup

Parameters:

id - the activation identifier

impl - the active remote object

Throws:

UnknownObjectException - if no object is registered under the specified activation identifier

ActivationException - if an activation error occurs

InactiveGroupException - if the group is inactive

SecurityException - if a security manager exists and invoking its checkPermission method with the permission MonitorPermission("java.rmi.activation.ActivationMonitor.activeObject") throws a SecurityException