ActivationGroup (Java 2 Platform SE 5.0) (original) (raw)

java.rmi.activation

Class ActivationGroup

java.lang.Object java.rmi.server.RemoteObject java.rmi.server.RemoteServer java.rmi.server.UnicastRemoteObject java.rmi.activation.ActivationGroup

All Implemented Interfaces:

Serializable, ActivationInstantiator, Remote

public abstract class ActivationGroup

extends UnicastRemoteObject

implements ActivationInstantiator

An ActivationGroup is responsible for creating new instances of "activatable" objects in its group, informing itsActivationMonitor 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 explicit ActivationGroupID 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 anActivationGroup. 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 theActivationGroup.createGroup static method. ThecreateGroup method has two requirements on the group to be created: 1) the group must be a concrete subclass ofActivationGroup, and 2) the group must have a constructor that takes two arguments:

• the group's ActivationGroupID, and
• the group's initialization data (in ajava.rmi.MarshalledObject)

When created, the default implementation ofActivationGroup will override the system properties with the properties requested when itsActivationGroupDesc was created, and will set ajava.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 useActivationGroup.createGroup before creating anyActivationDescs (before the defaultActivationGroupDesc is created). If your application requires the use of a security manager other thanjava.rmi.RMISecurityManager, in the ActivativationGroupDescriptor properties list you can setjava.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

ActivationGroup

protected ActivationGroup(ActivationGroupID groupID) throws RemoteException

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](../../../java/rmi/RemoteException.html "class in java.rmi") - if this group could not be exported

Since:

1.2

inactiveObject

public boolean inactiveObject(ActivationID id) throws ActivationException, UnknownObjectException, RemoteException

The group's inactiveObject method is called indirectly via a call to the Activatable.inactive method. A remote object implementation must callActivatable's inactive 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 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'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](../../../java/rmi/activation/UnknownObjectException.html "class in java.rmi.activation") - if object is unknown (may already be inactive)

[RemoteException](../../../java/rmi/RemoteException.html "class in java.rmi") - if call informing monitor fails

[ActivationException](../../../java/rmi/activation/ActivationException.html "class in java.rmi.activation") - if group is inactive

Since:

1.2

activeObject

public abstract void activeObject(ActivationID id, Remote obj) throws ActivationException, UnknownObjectException, RemoteException

The group's activeObject method is called when an object is exported (either by Activatable object construction or an explicit call toActivatable.exportObject. The group must inform itsActivationMonitor 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](../../../java/rmi/activation/UnknownObjectException.html "class in java.rmi.activation") - if object is not registered

[RemoteException](../../../java/rmi/RemoteException.html "class in java.rmi") - if call informing monitor fails

[ActivationException](../../../java/rmi/activation/ActivationException.html "class in java.rmi.activation") - if group is inactive

Since:

1.2

createGroup

public static ActivationGroup createGroup(ActivationGroupID id, ActivationGroupDesc desc, long incarnation) throws 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 theActivationGroupDesc must be a concrete subclass ofActivationGroup 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 theActivationGroupDesc.

If the group class name specified in theActivationGroupDesc 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'scheckSetFactory 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, theActivationSystem 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 thecurrentGroupID 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](../../../java/rmi/activation/ActivationException.html "class in java.rmi.activation") - if group already exists or if error occurs during group creation

[SecurityException](../../../java/lang/SecurityException.html "class in java.lang") - 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()

currentGroupID

public static 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

public static void setSystem(ActivationSystem system) throws 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 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 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](../../../java/rmi/activation/ActivationException.html "class in java.rmi.activation") - if activation system is already set

[SecurityException](../../../java/lang/SecurityException.html "class in java.lang") - 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(), SecurityManager.checkSetFactory()

getSystem

public static ActivationSystem getSystem() throws 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 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](../../../java/rmi/activation/ActivationException.html "class in java.rmi.activation") - 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)

activeObject

protected void activeObject(ActivationID id, MarshalledObject mobj) throws ActivationException, UnknownObjectException, 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'sActivationMonitor.

Parameters:

id - the object's identifier

mobj - a marshalled object containing the remote object's stub

Throws:

[UnknownObjectException](../../../java/rmi/activation/UnknownObjectException.html "class in java.rmi.activation") - if object is not registered

[RemoteException](../../../java/rmi/RemoteException.html "class in java.rmi") - if call informing monitor fails

[ActivationException](../../../java/rmi/activation/ActivationException.html "class in java.rmi.activation") - if an activation error occurs

Since:

1.2

inactiveGroup

protected void inactiveGroup() throws UnknownGroupException, 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'sActivationMonitor. Also, the current group for the VM is set to null.

Throws:

[UnknownGroupException](../../../java/rmi/activation/UnknownGroupException.html "class in java.rmi.activation") - if group is not registered

[RemoteException](../../../java/rmi/RemoteException.html "class in java.rmi") - if call informing monitor fails

Since:

1.2

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 2004, 2010 Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.