- All Implemented Interfaces:
Serializable
,ActivationInstantiator
,Remote
@Deprecated(forRemoval=true, since="15") public abstract class ActivationGroup extends UnicastRemoteObject implements ActivationInstantiator
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:
- as a side-effect of creating an
ActivationDesc
without an explicitActivationGroupID
for the first activatable object in the group, or - via the
ActivationGroup.createGroup
method - as a side-effect of activating the first object in a group
whose
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:
- the group's
ActivationGroupID
, and - the group's initialization data (in a
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
SecurityManager
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
ActivationDesc
s (before the default
ActivationGroupDesc
is created). If your application
requires the use of a security manager other than
SecurityManager
, 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
,ActivationGroupDesc
,ActivationGroupID
, Serialized Form
-
Field Summary
Fields declared in class java.rmi.server.RemoteObject
ref
-
Constructor Summary
Constructors Modifier Constructor Description protected
ActivationGroup(ActivationGroupID groupID)
Deprecated, for removal: This API element is subject to removal in a future version.Constructs an activation group with the given activation group identifier. -
Method Summary
Modifier and Type Method Description protected void
activeObject(ActivationID id, MarshalledObject<? extends Remote> mobj)
Deprecated, for removal: This API element is subject to removal in a future version.This protected method is necessary for subclasses to make theactiveObject
callback to the group's monitor.abstract void
activeObject(ActivationID id, Remote obj)
Deprecated, for removal: This API element is subject to removal in a future version.The group'sactiveObject
method is called when an object is exported (either byActivatable
object construction or an explicit call toActivatable.exportObject
.static ActivationGroup
createGroup(ActivationGroupID id, ActivationGroupDesc desc, long incarnation)
Deprecated, for removal: This API element is subject to removal in a future version.Create and set the activation group for the current VM.static ActivationGroupID
currentGroupID()
Deprecated, for removal: This API element is subject to removal in a future version.Returns the current activation group's identifier.static ActivationSystem
getSystem()
Deprecated, for removal: This API element is subject to removal in a future version.Returns the activation system for the VM.protected void
inactiveGroup()
Deprecated, for removal: This API element is subject to removal in a future version.This protected method is necessary for subclasses to make theinactiveGroup
callback to the group's monitor.boolean
inactiveObject(ActivationID id)
Deprecated, for removal: This API element is subject to removal in a future version.The group'sinactiveObject
method is called indirectly via a call to theActivatable.inactive
method.static void
setSystem(ActivationSystem system)
Deprecated, for removal: This API element is subject to removal in a future version.Set the activation system for the VM.Methods declared in class java.rmi.server.UnicastRemoteObject
clone, exportObject, exportObject, exportObject, exportObject, exportObject, unexportObject
Methods declared in class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
Methods declared in interface java.rmi.activation.ActivationInstantiator
newInstance
-
Constructor Details
-
ActivationGroup
Deprecated, for removal: This API element is subject to removal in a future version.Constructs an activation group with the given activation group identifier. The group is exported as ajava.rmi.server.UnicastRemoteObject
.- Parameters:
groupID
- the group's identifier- Throws:
RemoteException
- if this group could not be exportedUnsupportedOperationException
- if and only if activation is not supported by this implementation- Since:
- 1.2
-
-
Method Details
-
inactiveObject
public boolean inactiveObject(ActivationID id) throws ActivationException, UnknownObjectException, RemoteExceptionDeprecated, for removal: This API element is subject to removal in a future version.The group'sinactiveObject
method is called indirectly via a call to theActivatable.inactive
method. A remote object implementation must callActivatable
'sinactive
method when that object deactivates (the object deems that it is no longer active). If the object does not callActivatable.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 ofActivationGroup
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'sinactiveObject
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
- if object is unknown (may already be inactive)RemoteException
- if call informing monitor failsActivationException
- if group is inactive- Since:
- 1.2
-
activeObject
public abstract void activeObject(ActivationID id, Remote obj) throws ActivationException, UnknownObjectException, RemoteExceptionDeprecated, for removal: This API element is subject to removal in a future version.The group'sactiveObject
method is called when an object is exported (either byActivatable
object construction or an explicit call toActivatable.exportObject
. The group must inform itsActivationMonitor
that the object is active (via the monitor'sactiveObject
method) if the group hasn't already done so.- Parameters:
id
- the object's identifierobj
- the remote object implementation- Throws:
UnknownObjectException
- if object is not registeredRemoteException
- if call informing monitor failsActivationException
- if group is inactive- Since:
- 1.2
-
createGroup
public static ActivationGroup createGroup(ActivationGroupID id, ActivationGroupDesc desc, long incarnation) throws ActivationExceptionDeprecated, for removal: This API element is subject to removal in a future version.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 thecreateGroup
method when theActivator
initiates the re-creation of an activation group in order to carry out incomingactivate
requests. A group must first be registered with theActivationSystem
before it can be created via this method.The group class specified by the
ActivationGroupDesc
must be a concrete subclass ofActivationGroup
and have a public constructor that takes two arguments: theActivationGroupID
for the group and theMarshalledObject
containing the group's initialization data (obtained from theActivationGroupDesc
.If the group class name specified in the
ActivationGroupDesc
isnull
, 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.
SecurityManager
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 aSecurityException
. If your application needs to set a different security manager, you must ensure that the policy file specified by the group'sActivationGroupDesc
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 theactiveGroup
method which returns theActivationMonitor
for the group. The application need not callactiveGroup
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 identifierdesc
- the activation group's descriptorincarnation
- the group's incarnation number (zero on group's initial creation)- Returns:
- the activation group for the VM
- Throws:
ActivationException
- if group already exists or if error occurs during group creationSecurityException
- if permission to create group is denied. (Note: The default implementation of the security managercheckSetFactory
method requires the RuntimePermission "setFactory")UnsupportedOperationException
- if and only if activation is not supported by this implementation- Since:
- 1.2
- See Also:
SecurityManager.checkSetFactory()
-
currentGroupID
Deprecated, for removal: This API element is subject to removal in a future version.Returns the current activation group's identifier. Returns null if no group is currently active for this VM.- Returns:
- the activation group's identifier
- Throws:
UnsupportedOperationException
- if and only if activation is not supported by this implementation- Since:
- 1.2
-
setSystem
Deprecated, for removal: This API element is subject to removal in a future version.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 thegetSystem
method attempts to obtain a reference to theActivationSystem
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 byActivationSystem.SYSTEM_PORT
. This port can be overridden by setting the propertyjava.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 theActivationSystem
- Throws:
ActivationException
- if activation system is already setSecurityException
- if permission to set the activation system is denied. (Note: The default implementation of the security managercheckSetFactory
method requires the RuntimePermission "setFactory")UnsupportedOperationException
- if and only if activation is not supported by this implementation- Since:
- 1.2
- See Also:
getSystem()
,SecurityManager.checkSetFactory()
-
getSystem
Deprecated, for removal: This API element is subject to removal in a future version.Returns the activation system for the VM. The activation system may be set by thesetSystem
method. If the activation system is not set via thesetSystem
method, then thegetSystem
method attempts to obtain a reference to theActivationSystem
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 byActivationSystem.SYSTEM_PORT
. This port can be overridden by setting the propertyjava.rmi.activation.port
.- Returns:
- the activation system for the VM/group
- Throws:
ActivationException
- if activation system cannot be obtained or is not bound (means that it is not running)UnsupportedOperationException
- if and only if activation is not supported by this implementation- Since:
- 1.2
- See Also:
setSystem(java.rmi.activation.ActivationSystem)
-
activeObject
protected void activeObject(ActivationID id, MarshalledObject<? extends Remote> mobj) throws ActivationException, UnknownObjectException, RemoteExceptionDeprecated, for removal: This API element is subject to removal in a future version.This protected method is necessary for subclasses to make theactiveObject
callback to the group's monitor. The call is simply forwarded to the group'sActivationMonitor
.- Parameters:
id
- the object's identifiermobj
- a marshalled object containing the remote object's stub- Throws:
UnknownObjectException
- if object is not registeredRemoteException
- if call informing monitor failsActivationException
- if an activation error occurs- Since:
- 1.2
-
inactiveGroup
Deprecated, for removal: This API element is subject to removal in a future version.This protected method is necessary for subclasses to make theinactiveGroup
callback to the group's monitor. The call is simply forwarded to the group'sActivationMonitor
. Also, the current group for the VM is set to null.- Throws:
UnknownGroupException
- if group is not registeredRemoteException
- if call informing monitor fails- Since:
- 1.2
-
java.rmi.activation
package specification for further information.