org.omg.PortableServer
Interface ServantActivatorOperations

All Superinterfaces:

ServantManagerOperations

All Known Subinterfaces:

ServantActivator

All Known Implementing Classes:

_ServantActivatorStub, ServantActivatorPOA

public interface ServantActivatorOperations
extends ServantManagerOperations

When the POA has the RETAIN policy it uses servant managers that are ServantActivators.
When using such servant managers, the following statements apply for a given ObjectId used in the incarnate and etherealize operations: Servants incarnated by the servant manager will be placed in the Active Object Map with objects they have activated. Invocations of incarnate on the servant manager are serialized. Invocations of etherealize on the servant manager are serialized. Invocations of incarnate and etherealize on the servant manager are mutually exclusive.
Incarnations of a particular object may not overlap; that is, incarnate shall not be invoked with a particular ObjectId while, within the same POA, that ObjectId is in use as the ObjectId of an activated object or as the argument of a call to incarnate or etherealize that has not completed.
It should be noted that there may be a period of time between an object's deactivation and the etherealization (during which outstanding requests are being processed) in which arriving requests on that object should not be passed to its servant. During this period, requests targeted for such an object act as if the POA were in holding state until etherealize completes. If etherealize is called as a consequence of a deactivate call with an etherealize_objects parameter of TRUE, incoming requests are rejected. It should also be noted that a similar situation occurs with incarnate.
There may be a period of time after the POA invokes incarnate and before that method returns in which arriving requests bound for that object should not be passed to the servant.
A single servant manager object may be concurrently registered with multiple POAs. Invocations of incarnate and etherealize on a servant manager in the context of different POAs are not necessarily serialized or mutually exclusive. There are no assumptions made about the thread in which etherealize is invoked.

Method Summary

void	etherealize(byte[] oid, POA adapter, Servant serv, boolean cleanup_in_progress, boolean remaining_activations) This operation is invoked whenever a servant for an object is deactivated, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.
Servant	incarnate(byte[] oid, POA adapter) This operation is invoked by the POA whenever the POA receives a request for an object that is not currently active, assuming the POA has the USE_SERVANT_MANAGER and RETAIN policies.

Method Detail

etherealize

void etherealize(byte[] oid,
                 POA adapter,
                 Servant serv,
                 boolean cleanup_in_progress,
                 boolean remaining_activations)

       This operation is invoked whenever a servant for an object is
       deactivated, assuming the POA has the USE_SERVANT_MANAGER and
       RETAIN policies. Note that an active servant may be deactivated
       by the servant manager via etherealize even if it was not
       incarnated by the servant manager.  The oid parameter contains
       the Object Id value of the object being deactivated. The adapter
       parameter is an object reference for the POA in whose scope the
       object was active. The serv parameter contains a reference to
       the servant that is associated with the object being
       deactivated. If the servant denoted by the serv parameter is
       associated with other objects in the POA denoted by the adapter
       parameter (that is, in the POA's Active Object Map) at the time
       that etherealize is called, the remaining_activations parameter
       has the value TRUE. Otherwise, it has the value FALSE.  If the
       cleanup_in_progress parameter is TRUE, the reason for the
       etherealize operation is that either the deactivate or destroy
       operation was called with an etherealize_objects parameter of
       TRUE. If the parameter is FALSE, the etherealize operation is
       called for other reasons.  Deactivation occurs in the following
       circumstances:
       

       When an object is deactivated explicitly by an invocation of
       POA::deactivate_object.  When the ORB or POA determines
       internally that an object must be deactivated.  For example, an
       ORB implementation may provide policies that allow objects to be
       deactivated after some period of quiescence, or when the number
       of active objects reaches some limit.  f POAManager::deactivate
       is invoked on a POA manager associated with a POA that has
       currently active objects.  Destroying a servant that is in the
       Active Object Map or is otherwise known to the POA can lead to
       undefined results.  In a multi-threaded environment, the POA
       makes certain guarantees that allow servant managers to safely
       destroy servants. Specifically, the servant's entry in the
       Active Object Map corresponding to the target object is removed
       before etherealize is called.  Because calls to incarnate and
       etherealize are serialized, this prevents new requests for the
       target object from being invoked on the servant during
       etherealization. After removing the entry from the Active Object
       Map, if the POA determines before invoking etherealize that
       other requests for the same target object are already in
       progress on the servant, it delays the call to etherealize until
       all active methods for the target object have completed.
       Therefore, when etherealize is called, the servant manager can
       safely destroy the servant if it wants to, unless the
       remaining_activations argument is TRUE.  If the etherealize
       operation returns a system exception, the POA ignores the
       exception.

Parameters:

oid - The object id of the object whose servant is to be deactivated.

adapter - The POA in whose scope the object was active.

serv - The servant which is to be deactivated.

cleanup_in_progress - If set to True, the reason for the invocation of the method is either that the deactivate or destroy method was called with the etherealize_objects parameter set to True; otherwise, the method was called for other reasons.

remaining_activations - If the specified serv is associated with other objects in the specified adapter it is set to True; otherwise it is FALSE.

incarnate

Servant incarnate(byte[] oid,
                  POA adapter)
                  throws ForwardRequest

       This operation is invoked by the POA whenever the POA receives a
       request for an object that is not currently active, assuming the
       POA has the USE_SERVANT_MANAGER and RETAIN policies.  The oid
       parameter contains the ObjectId value associated with the
       incoming request.  The adapter is an object reference for the
       POA in which the object is being activated.
       

       The user-supplied servant manager implementation is responsible
       for locating or creating an appropriate servant that corresponds
       to the ObjectId value if possible.  incarnate returns a value of
       type Servant, which is the servant that will be used to process
       the incoming request (and potentially subsequent requests, since
       the POA has the RETAIN policy).  The POA enters the returned
       Servant value into the Active Object Map so that subsequent
       requests with the same ObjectId value will be delivered directly
       to that servant without invoking the servant manager.  If the
       incarnate operation returns a servant that is already active for
       a different Object Id and if the POA also has the UNIQUE_ID
       policy, the incarnate has violated the POA policy and is
       considered to be in error. The POA will raise an OBJ_ADAPTER
       system exception for the request.

Parameters:

oid - The object id of the object whose servant is to be activated.

adapter - The POA in whose scope the object is to be activated.

Throws:

ForwardRequest