11.3.6 ServantActivator Interface

   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.

   11.3.6.1 incarnate

   Servant incarnate (in ObjectId oid, in POA adapter)

   raises (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. In this case, etherealize is not called by the POA because the servant was never added to the Active Object Map.

   Note – If the same servant is used in two different POAs, it is legal for the POAs to use that servant even if the POAs have different Object Id uniqueness policies. The POAs do not interact with each other in this regard.

   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.

• If 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.