Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jini.phoenix
Class ActivationGroupImpl

    java.lang.Object
      java.rmi.server.RemoteObject
          java.rmi.server.RemoteServer
              java.rmi.server.UnicastRemoteObject
                  java.rmi.activation.ActivationGroup
                      net.jini.activation.ActivationGroup
                          com.sun.jini.phoenix.ActivationGroupImpl

All Implemented Interfaces:
  ActivationInstantiator, Remote, Serializable, 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
See Also:
  Serialized Form

Field Summary

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
`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.
`static ActivationGroup` | `createGroup(ActivationGroupID id, ActivationGroupDesc desc, long incarnation)` Creates an `ActivationGroup` instance and returns it.
`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.
`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`

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

### 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

### 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 the newly created instance implements `ProxyAccessor`, a proxy is obtained by invoking the `getProxy` method on that instance. If the obtained proxy is not `null`, that proxy is returned in a `MarshalledObject`; otherwise, an `ActivationException` is thrown.
  - If the newly created instance does not implement `ProxyAccessor`, the instance is returned in a `MarshalledObject`. In this case, the instance must be serializable, and marshalling the instance must produce a suitable proxy for the remote object (for example, the object implements `Serializable` and defines a `writeReplace` method that returns the object's proxy).

  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`.

  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`

### 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.

  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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved