11.3.7 ServantLocator Interface

   When the POA has the NON_RETAIN policy it uses servant managers that are ServantLocators. Because the POA knows that the servant returned by this servant manager will be used only for a single request, it can supply extra information to the servant manager’s operations and the servant manager’s pair of operations may be able to cooperate to do something different than a ServantActivator.

   ServantLocator is a local interface. A ServantLocator object must be local to the process containing the POA objects it is registered with.

   When the POA uses the ServantLocator interface, immediately after performing the operation invocation on the servant returned by preinvoke, the POA will invoke postinvoke on the servant manager, passing the ObjectId value and the Servant value as parameters (among others). The next request with this ObjectId value will then cause preinvoke to be invoked again. This feature may be used to force every request for objects associated with a POA to be mediated by the servant manager.

   When using such a ServantLocator, the following statements apply for a given ObjectId used in the preinvoke and postinvoke operations:

• The servant returned by preinvoke is used only to process the single request that caused preinvoke to be invoked.

• No servant incarnated by the servant manager will be placed in the Active Object Map.

• When the invocation of the request on the servant is complete, postinvoke will be invoked for the object.

• No serialization of invocations of preinvoke or postinvoke may be assumed; there may be multiple concurrent invocations of preinvoke for the same ObjectId. (However, if the SINGLE_THREAD_MODEL policy is being used, that policy will serialize these calls.)

• The same thread will be used to preinvoke the object, process the request, and postinvoke the object.

• If preinvoke raises an exception, postinvoke is not called. Otherwise the preinvoke and postinvoke operations are always called in pairs in response to any ORB activity. In particular, for a response to a GIOP Locate message a GIOP-conforming ORB may (or may not) call preinvoke to determine whether the object could be served at this location. If the ORB makes such a call, whatever the result, the ORB does not invoke a method, but does call postinvoke before responding to the Locate message.

   Note – The ServantActivator interface does not behave similarly with respect to a GIOP Locate message since the etherealize operation is not associated with request processing.

   11.3.7.1 preinvoke

   Servant preinvoke( in ObjectId oid, in POA adapter, in CORBA::Identifier operation, out Cookie the_cookie) 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 NON_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. preinvoke returns a value of type Servant, which is the servant that will be used to process the incoming request.

   The Cookie is a type opaque to the POA that can be set by the servant manager for use later by postinvoke. The operation is the name of the operation that will be called by the POA when the servant is returned.

   This operation is invoked whenever a servant completes a request, assuming the POA has the USE_SERVANT_MANAGER and NON_RETAIN policies.

   The postinvoke operation is considered to be part of a request on an object.That is, the request is not complete until postinvoke finishes. If the method finishes normally but postinvoke raises a system exception, the method's normal return is overridden; the request completes with the exception.

   The oid parameter contains the Object Id value of the object on which the request was made. The adapter parameter is an object reference for the POA in whose scope the object was active. The the_servant parameter contains a reference to the servant that is associated with the object.

   The Cookie is a type opaque to the POA; it contains any value that was set by the preinvoke operation. The operation is the name of the operation that was called by the POA for the request.

   Destroying a servant that is known to the POA can lead to undefined results.

   11.3.7.3 ServantLocator and Location Determination

   Under certain circumstances, an ORB may need to determine the actual location of an object's implementation. For objects that are managed by a POA that is configured with a ServantLocator, it may invoke preinvoke and postinvoke or it may determine the object’s location by some other means. If it invokes preinvoke and postinvoke under these circumstances it shall use the argument “_locate.?