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:
ActivationDesc
* without an explicit ActivationGroupID for the
* first activatable object in the group, or
* ActivationGroup.createGroup method
* 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:
*
*
ActivationGroupID, and
* 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
* @see ActivationInstantiator
* @see ActivationGroupDesc
* @see ActivationGroupID
* @since 1.2
*/
public abstract class ActivationGroup
extends UnicastRemoteObject
implements ActivationInstantiator
{
/**
* @serial the group's identifier
*/
private ActivationGroupID groupID;
/**
* @serial the group's monitor
*/
private ActivationMonitor monitor;
/**
* @serial the group's incarnation number
*/
private long incarnation;
/** the current activation group for this VM */
private static ActivationGroup currGroup;
/** the current group's identifier */
private static ActivationGroupID currGroupID;
/** the current group's activation system */
private static ActivationSystem currSystem;
/** used to control a group being created only once */
private static boolean canCreate = true;
/** indicate compatibility with the Java 2 SDK v1.2 version of class */
private static final long serialVersionUID = -7696947875314805420L;
/**
* Constructs an activation group with the given activation group
* identifier. The group is exported as a
* java.rmi.server.UnicastRemoteObject.
*
* @param groupID the group's identifier
* @throws RemoteException if this group could not be exported
* @since 1.2
*/
protected ActivationGroup(ActivationGroupID groupID)
throws RemoteException
{
// call super constructor to export the object
super();
this.groupID = groupID;
}
/**
* 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.
*
* @param id the object's activation identifier
* @return true if the object was successfully deactivated; otherwise
* returns false.
* @exception UnknownObjectException if object is unknown (may already
* be inactive)
* @exception RemoteException if call informing monitor fails
* @exception ActivationException if group is inactive
* @since 1.2
*/
public boolean inactiveObject(ActivationID id)
throws ActivationException, UnknownObjectException, RemoteException
{
getMonitor().inactiveObject(id);
return true;
}
/**
* 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.
*
* @param id the object's identifier
* @param obj the remote object implementation
* @exception UnknownObjectException if object is not registered
* @exception RemoteException if call informing monitor fails
* @exception ActivationException if group is inactive
* @since 1.2
*/
public abstract void activeObject(ActivationID id, Remote obj)
throws ActivationException, UnknownObjectException, RemoteException;
/**
* 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.
*
* @param id the activation group's identifier
* @param desc the activation group's descriptor
* @param incarnation the group's incarnation number (zero on group's
* initial creation)
* @return the activation group for the VM
* @exception ActivationException if group already exists or if error
* occurs during group creation
* @exception SecurityException if permission to create group is denied.
* (Note: The default implementation of the security manager
* checkSetFactory
* method requires the RuntimePermission "setFactory")
* @see SecurityManager#checkSetFactory
* @since 1.2
*/
public static synchronized
ActivationGroup createGroup(ActivationGroupID id,
final ActivationGroupDesc desc,
long incarnation)
throws ActivationException
{
SecurityManager security = System.getSecurityManager();
if (security != null)
security.checkSetFactory();
if (currGroup != null)
throw new ActivationException("group already exists");
if (canCreate == false)
throw new ActivationException("group deactivated and " +
"cannot be recreated");
try {
// load group's class
String groupClassName = desc.getClassName();
Class cl;
Class defaultGroupClass =
sun.rmi.server.ActivationGroupImpl.class;
if (groupClassName == null || // see 4252236
groupClassName.equals(defaultGroupClass.getName()))
{
cl = defaultGroupClass;
} else {
Class cl0;
try {
cl0 = RMIClassLoader.loadClass(desc.getLocation(),
groupClassName);
} catch (Exception ex) {
throw new ActivationException(
"Could not load group implementation class", ex);
}
if (ActivationGroup.class.isAssignableFrom(cl0)) {
cl = cl0.asSubclass(ActivationGroup.class);
} else {
throw new ActivationException("group not correct class: " +
cl0.getName());
}
}
// create group
Constructor constructor =
cl.getConstructor(ActivationGroupID.class,
MarshalledObject.class);
ActivationGroup newGroup =
constructor.newInstance(id, desc.getData());
currSystem = id.getSystem();
newGroup.incarnation = incarnation;
newGroup.monitor =
currSystem.activeGroup(id, newGroup, incarnation);
currGroup = newGroup;
currGroupID = id;
canCreate = false;
} catch (InvocationTargetException e) {
e.getTargetException().printStackTrace();
throw new ActivationException("exception in group constructor",
e.getTargetException());
} catch (ActivationException e) {
throw e;
} catch (Exception e) {
throw new ActivationException("exception creating group", e);
}
return currGroup;
}
/**
* Returns the current activation group's identifier. Returns null
* if no group is currently active for this VM.
* @return the activation group's identifier
* @since 1.2
*/
public static synchronized ActivationGroupID currentGroupID() {
return currGroupID;
}
/**
* Returns the activation group identifier for the VM. If an
* activation group does not exist for this VM, a default
* activation group is created. A group can be created only once,
* so if a group has already become active and deactivated.
*
* @return the activation group identifier
* @exception ActivationException if error occurs during group
* creation, if security manager is not set, or if the group
* has already been created and deactivated.
*/
static synchronized ActivationGroupID internalCurrentGroupID()
throws ActivationException
{
if (currGroupID == null)
throw new ActivationException("nonexistent group");
return currGroupID;
}
/**
* 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
*/
public static synchronized void setSystem(ActivationSystem system)
throws ActivationException
{
SecurityManager security = System.getSecurityManager();
if (security != null)
security.checkSetFactory();
if (currSystem != null)
throw new ActivationException("activation system already set");
currSystem = system;
}
/**
* 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
*/
public static synchronized ActivationSystem getSystem()
throws ActivationException
{
if (currSystem == null) {
try {
int port = AccessController.doPrivileged(
new GetIntegerAction("java.rmi.activation.port",
ActivationSystem.SYSTEM_PORT));
currSystem = (ActivationSystem)
Naming.lookup("//:" + port +
"/java.rmi.activation.ActivationSystem");
} catch (Exception e) {
throw new ActivationException(
"unable to obtain ActivationSystem", e);
}
}
return currSystem;
}
/**
* 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.
*
* @param id the object's identifier
* @param mobj a marshalled object containing the remote object's stub
* @exception UnknownObjectException if object is not registered
* @exception RemoteException if call informing monitor fails
* @exception ActivationException if an activation error occurs
* @since 1.2
*/
protected void activeObject(ActivationID id,
MarshalledObject mobj)
throws ActivationException, UnknownObjectException, RemoteException
{
getMonitor().activeObject(id, mobj);
}
/**
* 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.
*
* @exception UnknownGroupException if group is not registered
* @exception RemoteException if call informing monitor fails
* @since 1.2
*/
protected void inactiveGroup()
throws UnknownGroupException, RemoteException
{
try {
getMonitor().inactiveGroup(groupID, incarnation);
} finally {
destroyGroup();
}
}
/**
* Returns the monitor for the activation group.
*/
private ActivationMonitor getMonitor() throws RemoteException {
synchronized (ActivationGroup.class) {
if (monitor != null) {
return monitor;
}
}
throw new RemoteException("monitor not received");
}
/**
* Destroys the current group.
*/
private static synchronized void destroyGroup() {
currGroup = null;
currGroupID = null;
// NOTE: don't set currSystem to null since it may be needed
}
/**
* Returns the current group for the VM.
* @exception ActivationException if current group is null (not active)
*/
static synchronized ActivationGroup currentGroup()
throws ActivationException
{
if (currGroup == null) {
throw new ActivationException("group is not active");
}
return currGroup;
}
}