org.omg.PortableServer
Interface ServantLocatorOperations

All Superinterfaces:

ServantManagerOperations

All Known Subinterfaces:

ServantLocator

All Known Implementing Classes:

_ServantLocatorStub, ServantLocatorPOA

public interface ServantLocatorOperations
extends ServantManagerOperations

     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.  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.  he 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 that the ServantActivator interface does not behave
     similarly with respect to a GIOP Locate message since the
     etherealize operation is not associated with request processing.)
     

Method Summary

void	postinvoke(byte[] oid, POA adapter, java.lang.String operation, java.lang.Object the_cookie, Servant the_servant) This operation is invoked whenever a servant completes a request, assuming the POA has the USE_SERVANT_MANAGER and NON_RETAIN policies.
Servant	preinvoke(byte[] oid, POA adapter, java.lang.String operation, CookieHolder the_cookie) 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.

Method Detail

postinvoke

void postinvoke(byte[] oid,
                POA adapter,
                java.lang.String operation,
                java.lang.Object the_cookie,
                Servant the_servant)

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.

Parameters:

oid - The ObjectId value that is associated with the incoming request.

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

operation - The name of the operation which will be called by the POA when the servant is returned.

the_cookie - An opaque value which can be set by the servant manager in the preinvoke method for use in this method.

the_servant - The servant associated with the object.

preinvoke

Servant preinvoke(byte[] oid,
                  POA adapter,
                  java.lang.String operation,
                  CookieHolder the_cookie)
                  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 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.

Parameters:

oid - The ObjectId value that is associated with the incoming request.

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

operation - The name of the operation which will be called by the POA when the servant is returned.

the_cookie - An opaque value which can be set by the servant manager to be used later in the postinvoke method.

Throws:

ForwardRequest