com.sun.jini.phoenix
Class ActivationGroupImpl

java.lang.Object
  extended by java.rmi.server.RemoteObject
      extended by java.rmi.server.RemoteServer
          extended by java.rmi.server.UnicastRemoteObject
              extended by java.rmi.activation.ActivationGroup
                  extended by net.jini.activation.ActivationGroup
                      extended by 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
ActivationGroupImpl(ActivationGroupID id, MarshalledObject data)
          Creates an instance with the specified group identifier and initialization data.
 
Method Summary
 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 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


Copyright 2007, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.