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

Nested Class Summary
private static class ActivationGroupImpl.ActiveEntry
          Entry in table for active object.
private static class ActivationGroupImpl.AlreadyExportedExporter
          Exporter for an object that is already exported to JRMP.
private static class ActivationGroupImpl.WrappedGID
          ActivationGroupID containing a prepared ActivationSystem proxy and the original ActivationGroupID (with unprepared ActivationSystem proxy), that writeReplaces itself to the original.
 
Field Summary
private static Map active
          maps ActivationID to ActiveEntry
private static int ACTIVE
          createGroup has succeeded
private static Permission activeObjectPermission
          permission to check for monitor's activeObject call
private static int CREATED
          constructor (including activeGroup) has succeeded
private static int CREATING
          in the middle of createGroup
private static Exporter exporter
           
private static ActivationGroupID groupID
          original unprepared group id
private static int INACTIVE
          group is inactive
private static Permission inactiveObjectPermission
          permission to check for monitor's activeObject call
private static long incarnation
           
private static boolean inheritGroupSubject
          true if group subject is inherited when creating activatable objects
private static List lockedIDs
          ActivationIDs with operations in progress
private static LoginContext login
          server LoginContext or null
private static ActivationMonitor monitor
           
private static ProxyPreparer monPreparer
          monitor proxy preparer
private static Class[] paramTypes
          parameter types for activatable constructor
private static String PHOENIX
           
private  ActivationInstantiator proxy
          proxy for this activation group
private static boolean refuseCalls
          true if calls should be refused, false otherwise
private static ObjectStreamField[] serialPersistentFields
           
private static long serialVersionUID
           
private static int state
           
private static long unexportTimeout
          timeout on wait for unexport to succeed
private static long unexportWait
          timeout on wait between unexport attempts
private static int UNUSED
          instance has not been created
 
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
private  void acquireLock(ActivationID id)
           
 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.
private static void checkInactiveGroup()
           
private static boolean covers(ClassLoader sub, ClassLoader sup)
          Returns true if the first argument is either equal to, or is a descendant of, the second argument.
static ActivationGroup createGroup(ActivationGroupID id, ActivationGroupDesc desc, long incarnation)
          Creates an ActivationGroup instance and returns it.
private static Object doAction(PrivilegedExceptionAction action)
          Execute the specified action on behalf of the server subject without requiring the caller to have doAsPrivileged permission.
private static Configuration getConfiguration(MarshalledObject mobj)
          Returns the configuration obtained from the specified marshalled object.
private static int getInt(Configuration config, String name, int defValue)
          Return an int configuration entry.
private static ProxyPreparer getPreparer(Configuration config, String name)
          Return a ProxyPreparer configuration entry.
 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.
private  void releaseLock(ActivationID id)
           
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
 

Field Detail

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

PHOENIX

private static final String PHOENIX
See Also:
Constant Field Values

UNUSED

private static final int UNUSED
instance has not been created

See Also:
Constant Field Values

CREATING

private static final int CREATING
in the middle of createGroup

See Also:
Constant Field Values

CREATED

private static final int CREATED
constructor (including activeGroup) has succeeded

See Also:
Constant Field Values

ACTIVE

private static final int ACTIVE
createGroup has succeeded

See Also:
Constant Field Values

INACTIVE

private static final int INACTIVE
group is inactive

See Also:
Constant Field Values

paramTypes

private static Class[] paramTypes
parameter types for activatable constructor


serialPersistentFields

private static final ObjectStreamField[] serialPersistentFields

state

private static int state

incarnation

private static long incarnation

groupID

private static ActivationGroupID groupID
original unprepared group id


login

private static LoginContext login
server LoginContext or null


exporter

private static Exporter exporter

refuseCalls

private static boolean refuseCalls
true if calls should be refused, false otherwise


monPreparer

private static ProxyPreparer monPreparer
monitor proxy preparer


monitor

private static ActivationMonitor monitor

unexportTimeout

private static long unexportTimeout
timeout on wait for unexport to succeed


unexportWait

private static long unexportWait
timeout on wait between unexport attempts


active

private static Map active
maps ActivationID to ActiveEntry


lockedIDs

private static List lockedIDs
ActivationIDs with operations in progress


inheritGroupSubject

private static boolean inheritGroupSubject
true if group subject is inherited when creating activatable objects


activeObjectPermission

private static final Permission activeObjectPermission
permission to check for monitor's activeObject call


inactiveObjectPermission

private static Permission inactiveObjectPermission
permission to check for monitor's activeObject call


proxy

private ActivationInstantiator proxy
proxy for this activation group

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

getConfiguration

private static Configuration getConfiguration(MarshalledObject mobj)
                                       throws ConfigurationException,
                                              IOException,
                                              ClassNotFoundException
Returns the configuration obtained from the specified marshalled object.

Throws:
ConfigurationException
IOException
ClassNotFoundException

covers

private static boolean covers(ClassLoader sub,
                              ClassLoader sup)
Returns true if the first argument is either equal to, or is a descendant of, the second argument. Null is treated as the root of the tree.


getPreparer

private static ProxyPreparer getPreparer(Configuration config,
                                         String name)
                                  throws ConfigurationException
Return a ProxyPreparer configuration entry.

Throws:
ConfigurationException

getInt

private static int getInt(Configuration config,
                          String name,
                          int defValue)
                   throws ConfigurationException
Return an int configuration entry.

Throws:
ConfigurationException

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

acquireLock

private void acquireLock(ActivationID id)

releaseLock

private void releaseLock(ActivationID id)

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

checkInactiveGroup

private static void checkInactiveGroup()

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

doAction

private static Object doAction(PrivilegedExceptionAction action)
                        throws ActivationException,
                               RemoteException
Execute the specified action on behalf of the server subject without requiring the caller to have doAsPrivileged permission.

Throws:
ActivationException
RemoteException


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