java.rmi.activation
Class ActivationGroup

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.rmi.server.RemoteObject sample code for java.rmi.server.RemoteObject definition code for java.rmi.server.RemoteObject 
      extended by java.rmi.server.RemoteServer sample code for java.rmi.server.RemoteServer definition code for java.rmi.server.RemoteServer 
          extended by java.rmi.server.UnicastRemoteObject sample code for java.rmi.server.UnicastRemoteObject definition code for java.rmi.server.UnicastRemoteObject 
              extended by java.rmi.activation.ActivationGroup
All Implemented Interfaces:
Serializable sample code for java.io.Serializable definition code for java.io.Serializable , ActivationInstantiator sample code for java.rmi.activation.ActivationInstantiator definition code for java.rmi.activation.ActivationInstantiator , Remote sample code for java.rmi.Remote definition code for java.rmi.Remote

public abstract class ActivationGroup
extends UnicastRemoteObject sample code for java.rmi.server.UnicastRemoteObject definition code for java.rmi.server.UnicastRemoteObject
implements ActivationInstantiator sample code for java.rmi.activation.ActivationInstantiator definition code for java.rmi.activation.ActivationInstantiator

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:

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:

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.

Since:
1.2
See Also:
ActivationInstantiator sample code for java.rmi.activation.ActivationInstantiator definition code for java.rmi.activation.ActivationInstantiator , ActivationGroupDesc sample code for java.rmi.activation.ActivationGroupDesc definition code for java.rmi.activation.ActivationGroupDesc , ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID , Serialized Form

Field Summary
 
Fields inherited from class java.rmi.server.RemoteObject sample code for java.rmi.server.RemoteObject definition code for java.rmi.server.RemoteObject
ref sample code for java.rmi.server.RemoteObject.ref definition code for java.rmi.server.RemoteObject.ref
 
Constructor Summary
protected ActivationGroup sample code for java.rmi.activation.ActivationGroup.ActivationGroup(java.rmi.activation.ActivationGroupID) definition code for java.rmi.activation.ActivationGroup.ActivationGroup(java.rmi.activation.ActivationGroupID) (ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID  groupID)
          Constructs an activation group with the given activation group identifier.
 
Method Summary
protected  void activeObject sample code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.MarshalledObject) definition code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.MarshalledObject) (ActivationID sample code for java.rmi.activation.ActivationID definition code for java.rmi.activation.ActivationID  id, MarshalledObject sample code for java.rmi.MarshalledObject definition code for java.rmi.MarshalledObject  mobj)
          This protected method is necessary for subclasses to make the activeObject callback to the group's monitor.
abstract  void activeObject sample code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.Remote) definition code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.Remote) (ActivationID sample code for java.rmi.activation.ActivationID definition code for java.rmi.activation.ActivationID  id, Remote sample code for java.rmi.Remote definition code for java.rmi.Remote  obj)
          The group's activeObject method is called when an object is exported (either by Activatable object construction or an explicit call to Activatable.exportObject.
static ActivationGroup sample code for java.rmi.activation.ActivationGroup definition code for java.rmi.activation.ActivationGroup createGroup sample code for java.rmi.activation.ActivationGroup.createGroup(java.rmi.activation.ActivationGroupID, java.rmi.activation.ActivationGroupDesc, long) definition code for java.rmi.activation.ActivationGroup.createGroup(java.rmi.activation.ActivationGroupID, java.rmi.activation.ActivationGroupDesc, long) (ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID  id, ActivationGroupDesc sample code for java.rmi.activation.ActivationGroupDesc definition code for java.rmi.activation.ActivationGroupDesc  desc, long incarnation)
          Create and set the activation group for the current VM.
static ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID currentGroupID sample code for java.rmi.activation.ActivationGroup.currentGroupID() definition code for java.rmi.activation.ActivationGroup.currentGroupID() ()
          Returns the current activation group's identifier.
static ActivationSystem sample code for java.rmi.activation.ActivationSystem definition code for java.rmi.activation.ActivationSystem getSystem sample code for java.rmi.activation.ActivationGroup.getSystem() definition code for java.rmi.activation.ActivationGroup.getSystem() ()
          Returns the activation system for the VM.
protected  void inactiveGroup sample code for java.rmi.activation.ActivationGroup.inactiveGroup() definition code for java.rmi.activation.ActivationGroup.inactiveGroup() ()
          This protected method is necessary for subclasses to make the inactiveGroup callback to the group's monitor.
 boolean inactiveObject sample code for java.rmi.activation.ActivationGroup.inactiveObject(java.rmi.activation.ActivationID) definition code for java.rmi.activation.ActivationGroup.inactiveObject(java.rmi.activation.ActivationID) (ActivationID sample code for java.rmi.activation.ActivationID definition code for java.rmi.activation.ActivationID  id)
          The group's inactiveObject method is called indirectly via a call to the Activatable.inactive method.
static void setSystem sample code for java.rmi.activation.ActivationGroup.setSystem(java.rmi.activation.ActivationSystem) definition code for java.rmi.activation.ActivationGroup.setSystem(java.rmi.activation.ActivationSystem) (ActivationSystem sample code for java.rmi.activation.ActivationSystem definition code for java.rmi.activation.ActivationSystem  system)
          Set the activation system for the VM.
 
Methods inherited from class java.rmi.server.UnicastRemoteObject sample code for java.rmi.server.UnicastRemoteObject definition code for java.rmi.server.UnicastRemoteObject
clone sample code for java.rmi.server.UnicastRemoteObject.clone() definition code for java.rmi.server.UnicastRemoteObject.clone() , exportObject sample code for java.rmi.server.UnicastRemoteObject.exportObject(java.rmi.Remote) definition code for java.rmi.server.UnicastRemoteObject.exportObject(java.rmi.Remote) , exportObject sample code for java.rmi.server.UnicastRemoteObject.exportObject(java.rmi.Remote, int) definition code for java.rmi.server.UnicastRemoteObject.exportObject(java.rmi.Remote, int) , exportObject sample code for java.rmi.server.UnicastRemoteObject.exportObject(java.rmi.Remote, int, java.rmi.server.RMIClientSocketFactory, java.rmi.server.RMIServerSocketFactory) definition code for java.rmi.server.UnicastRemoteObject.exportObject(java.rmi.Remote, int, java.rmi.server.RMIClientSocketFactory, java.rmi.server.RMIServerSocketFactory) , unexportObject sample code for java.rmi.server.UnicastRemoteObject.unexportObject(java.rmi.Remote, boolean) definition code for java.rmi.server.UnicastRemoteObject.unexportObject(java.rmi.Remote, boolean)
 
Methods inherited from class java.rmi.server.RemoteServer sample code for java.rmi.server.RemoteServer definition code for java.rmi.server.RemoteServer
getClientHost sample code for java.rmi.server.RemoteServer.getClientHost() definition code for java.rmi.server.RemoteServer.getClientHost() , getLog sample code for java.rmi.server.RemoteServer.getLog() definition code for java.rmi.server.RemoteServer.getLog() , setLog sample code for java.rmi.server.RemoteServer.setLog(java.io.OutputStream) definition code for java.rmi.server.RemoteServer.setLog(java.io.OutputStream)
 
Methods inherited from class java.rmi.server.RemoteObject sample code for java.rmi.server.RemoteObject definition code for java.rmi.server.RemoteObject
equals sample code for java.rmi.server.RemoteObject.equals(java.lang.Object) definition code for java.rmi.server.RemoteObject.equals(java.lang.Object) , getRef sample code for java.rmi.server.RemoteObject.getRef() definition code for java.rmi.server.RemoteObject.getRef() , hashCode sample code for java.rmi.server.RemoteObject.hashCode() definition code for java.rmi.server.RemoteObject.hashCode() , toString sample code for java.rmi.server.RemoteObject.toString() definition code for java.rmi.server.RemoteObject.toString() , toStub sample code for java.rmi.server.RemoteObject.toStub(java.rmi.Remote) definition code for java.rmi.server.RemoteObject.toStub(java.rmi.Remote)
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 
Methods inherited from interface java.rmi.activation.ActivationInstantiator sample code for java.rmi.activation.ActivationInstantiator definition code for java.rmi.activation.ActivationInstantiator
newInstance sample code for java.rmi.activation.ActivationInstantiator.newInstance(java.rmi.activation.ActivationID, java.rmi.activation.ActivationDesc) definition code for java.rmi.activation.ActivationInstantiator.newInstance(java.rmi.activation.ActivationID, java.rmi.activation.ActivationDesc)
 

Constructor Detail

ActivationGroup sample code for java.rmi.activation.ActivationGroup(java.rmi.activation.ActivationGroupID) definition code for java.rmi.activation.ActivationGroup(java.rmi.activation.ActivationGroupID)

protected ActivationGroup(ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID  groupID)
                   throws RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException 
Constructs an activation group with the given activation group identifier. The group is exported as a java.rmi.server.UnicastRemoteObject.

Parameters:
groupID - the group's identifier
Throws:
RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException - if this group could not be exported
Since:
1.2
Method Detail

inactiveObject sample code for java.rmi.activation.ActivationGroup.inactiveObject(java.rmi.activation.ActivationID) definition code for java.rmi.activation.ActivationGroup.inactiveObject(java.rmi.activation.ActivationID)

public boolean inactiveObject(ActivationID sample code for java.rmi.activation.ActivationID definition code for java.rmi.activation.ActivationID  id)
                       throws ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException ,
                              UnknownObjectException sample code for java.rmi.activation.UnknownObjectException definition code for java.rmi.activation.UnknownObjectException ,
                              RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException 
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.

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

activeObject sample code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.Remote) definition code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.Remote)

public abstract void activeObject(ActivationID sample code for java.rmi.activation.ActivationID definition code for java.rmi.activation.ActivationID  id,
                                  Remote sample code for java.rmi.Remote definition code for java.rmi.Remote  obj)
                           throws ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException ,
                                  UnknownObjectException sample code for java.rmi.activation.UnknownObjectException definition code for java.rmi.activation.UnknownObjectException ,
                                  RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.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 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 sample code for java.rmi.activation.UnknownObjectException definition code for java.rmi.activation.UnknownObjectException - if object is not registered
RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException - if call informing monitor fails
ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException - if group is inactive
Since:
1.2

createGroup sample code for java.rmi.activation.ActivationGroup.createGroup(java.rmi.activation.ActivationGroupID, java.rmi.activation.ActivationGroupDesc, long) definition code for java.rmi.activation.ActivationGroup.createGroup(java.rmi.activation.ActivationGroupID, java.rmi.activation.ActivationGroupDesc, long)

public static ActivationGroup sample code for java.rmi.activation.ActivationGroup definition code for java.rmi.activation.ActivationGroup  createGroup(ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID  id,
                                          ActivationGroupDesc sample code for java.rmi.activation.ActivationGroupDesc definition code for java.rmi.activation.ActivationGroupDesc  desc,
                                          long incarnation)
                                   throws ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException 
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.

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)
Returns:
the activation group for the VM
Throws:
ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException - if group already exists or if error occurs during group creation
SecurityException sample code for java.lang.SecurityException definition code for java.lang.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() sample code for java.lang.SecurityManager.checkSetFactory() definition code for java.lang.SecurityManager.checkSetFactory()

currentGroupID sample code for java.rmi.activation.ActivationGroup.currentGroupID() definition code for java.rmi.activation.ActivationGroup.currentGroupID()

public static ActivationGroupID sample code for java.rmi.activation.ActivationGroupID definition code for java.rmi.activation.ActivationGroupID  currentGroupID()
Returns the current activation group's identifier. Returns null if no group is currently active for this VM.

Returns:
the activation group's identifier
Since:
1.2

setSystem sample code for java.rmi.activation.ActivationGroup.setSystem(java.rmi.activation.ActivationSystem) definition code for java.rmi.activation.ActivationGroup.setSystem(java.rmi.activation.ActivationSystem)

public static void setSystem(ActivationSystem sample code for java.rmi.activation.ActivationSystem definition code for java.rmi.activation.ActivationSystem  system)
                      throws ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException 
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 sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException - if activation system is already set
SecurityException sample code for java.lang.SecurityException definition code for java.lang.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:
getSystem() sample code for java.rmi.activation.ActivationGroup.getSystem() definition code for java.rmi.activation.ActivationGroup.getSystem() , SecurityManager.checkSetFactory() sample code for java.lang.SecurityManager.checkSetFactory() definition code for java.lang.SecurityManager.checkSetFactory()

getSystem sample code for java.rmi.activation.ActivationGroup.getSystem() definition code for java.rmi.activation.ActivationGroup.getSystem()

public static ActivationSystem sample code for java.rmi.activation.ActivationSystem definition code for java.rmi.activation.ActivationSystem  getSystem()
                                  throws ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException 
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 sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException - if activation system cannot be obtained or is not bound (means that it is not running)
Since:
1.2
See Also:
setSystem(java.rmi.activation.ActivationSystem) sample code for java.rmi.activation.ActivationGroup.setSystem(java.rmi.activation.ActivationSystem) definition code for java.rmi.activation.ActivationGroup.setSystem(java.rmi.activation.ActivationSystem)

activeObject sample code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.MarshalledObject) definition code for java.rmi.activation.ActivationGroup.activeObject(java.rmi.activation.ActivationID, java.rmi.MarshalledObject)

protected void activeObject(ActivationID sample code for java.rmi.activation.ActivationID definition code for java.rmi.activation.ActivationID  id,
                            MarshalledObject sample code for java.rmi.MarshalledObject definition code for java.rmi.MarshalledObject  mobj)
                     throws ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException ,
                            UnknownObjectException sample code for java.rmi.activation.UnknownObjectException definition code for java.rmi.activation.UnknownObjectException ,
                            RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException 
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 sample code for java.rmi.activation.UnknownObjectException definition code for java.rmi.activation.UnknownObjectException - if object is not registered
RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException - if call informing monitor fails
ActivationException sample code for java.rmi.activation.ActivationException definition code for java.rmi.activation.ActivationException - if an activation error occurs
Since:
1.2

inactiveGroup sample code for java.rmi.activation.ActivationGroup.inactiveGroup() definition code for java.rmi.activation.ActivationGroup.inactiveGroup()

protected void inactiveGroup()
                      throws UnknownGroupException sample code for java.rmi.activation.UnknownGroupException definition code for java.rmi.activation.UnknownGroupException ,
                             RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException 
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 sample code for java.rmi.activation.UnknownGroupException definition code for java.rmi.activation.UnknownGroupException - if group is not registered
RemoteException sample code for java.rmi.RemoteException definition code for java.rmi.RemoteException - if call informing monitor fails
Since:
1.2