11.3.8 POA Policy Objects

   Interfaces derived from CORBA::Policy are used with the POA::create_POA operation to specify policies that apply to a POA. Policy objects are created using factory operations on any pre-existing POA, such as the root POA, or by a call to ORB::create_policy. Policy objects are specified when a POA is created. Policies may not be changed on an existing POA. Policies are not inherited from the parent POA. All Policy interfaces defined in this section are local interfaces.

   The POA shall preserve Policies whose types have been registered via PortableInterceptor::ORBInitInfo::register_policy_factory, even if the POA itself does not know about those policies.

   11.3.8.1 Thread Policy

   Objects with the ThreadPolicy interface are obtained using the POA::create_thread_policy operation and passed to the POA::create_POA operation to specify the threading model used with the created POA. The value attribute of ThreadPolicy contains the value supplied to the POA::create_thread_policy operation from which it was obtained. The following values can be supplied.

• ORB_CTRL_MODEL - The ORB is responsible for assigning requests for an ORB- controlled POA to threads. In a multi-threaded environment, concurrent requests may be delivered using multiple threads.

• SINGLE_THREAD_MODEL - Requests for a single-threaded POA are processed sequentially. In a multi-threaded environment, all upcalls made by this POA to implementation code (servants and servant managers) are made in a manner that is safe for code that is multi-thread-unaware. The POA will still allow reentrant calls from an object implementation to itself, or to another object implementation managed by the same POA.

• MAIN_THREAD_MODEL - Requests for all main-thread POAs are processed sequentially. In a multi-threaded environment, all upcalls made by all POAs with this policy to servants are made in a manner that is safe for code that is multi-thread-unaware. If the environment has special requirements that some code must run on a distinguished “main? thread, servant upcalls will be processed on that thread. (See Section 4.2.5, “Thread-Related Operations,? on page 4-10.)

   If no ThreadPolicy object is passed to create_POA, the thread policy defaults to ORB_CTRL_MODEL.

   Note – In some environments, calling multi-thread-unaware code safely (that is, using the MAIN_THREAD_MODEL) may mean that the POA will use only the main thread, in which case the application programmer is responsible to ensure that the main thread is given to the ORB, using ORB::perform_work or ORB::run.

   POAs using the SINGLE_THREAD_MODEL may need to cooperate to ensure that calls are safe even when implementation code (such as a servant manager) is shared by multiple single-threaded POAs.

   These models presume that the ORB and the application are using compatible threading primitives in a multi-threaded environment.

   11.3.8.2 Lifespan Policy

   Objects with the LifespanPolicy interface are obtained using the POA::create_lifespan_policy operation and passed to the POA::create_POA operation to specify the lifespan of the objects implemented in the created POA. The following values can be supplied.

• TRANSIENT - The objects implemented in the POA cannot outlive the POA instance in which they are first created. Once the POA’s POAManager enters the deactivated state, any requests received by this POA will cause the POA to raise an OBJECT_NOT_EXIST system exception with standard minor code 4.

• PERSISTENT - The objects implemented in the POA can outlive the process in which they are first created.

• Persistent objects have a POA associated with them (the POA that created them). When the ORB receives a request on a persistent object, it first searches for the matching POA, based on the names of the POA and all of its ancestors. • Administrative action beyond the scope of this specification may be necessary to inform the ORB's location service of the creation and eventual termination of existence of this POA, and optionally to arrange for on-demand activation of a process implementing this POA. • POA names must be unique within their enclosing scope (the parent POA). A portable program can assume that POA names used in other processes will not conflict with its own POA names. A conforming CORBA implementation will provide a method for ensuring this property.

   If no LifespanPolicy object is passed to create_POA, the lifespan policy defaults to TRANSIENT.

   11.3.8.3 Object Id Uniqueness Policy

   Objects with the IdUniquenessPolicy interface are obtained using the POA::create_id_uniqueness_policy operation and passed to the POA::create_POA operation to specify whether the servants activated in the created POA must have unique object identities. The following values can be supplied.

• UNIQUE_ID - Servants activated with that POA support exactly one Object Id.

• MULTIPLE_ID - a servant activated with that POA may support one or more Object Ids.

   If no IdUniquenessPolicy is specified at POA creation, the default is UNIQUE_ID.

   Note – Use of UNIQUE_ID policy is meaningless in conjunction with NON_RETAIN policy. A conforming application should not use this policy combination. A conforming orb may, but need not, report an error during create_POA if this

   March 2004 CORBA, v3.0.3: Interfaces

   combination is used. If an orb permits this combination of policies to be used, the resulting POA shall not treat the use of the same servant for concurrent requests on different object ids as an error.

   11.3.8.4 Id Assignment Policy

   Objects with the IdAssignmentPolicy interface are obtained using the POA::create_id_assignment_policy operation and passed to the POA::create_POA operation to specify whether Object Ids in the created POA are generated by the application or by the ORB. The following values can be supplied.

• USER_ID - Objects created with that POA are assigned Object Ids only by the application.

• SYSTEM_ID - Objects created with that POA are assigned Object Ids only by the POA. If the POA also has the PERSISTENT policy, assigned Object Ids must be unique across all instantiations of the same POA.

   If no IdAssignmentPolicy is specified at POA creation, the default is SYSTEM_ID.

   11.3.8.5 Servant Retention Policy

   Objects with the ServantRetentionPolicy interface are obtained using the POA::create_servant_retention_policy operation and passed to the POA::create_POA operation to specify whether the created POA retains active servants in an Active Object Map. The following values can be supplied.

• RETAIN - The POA will retain active servants in its Active Object Map.

• NON_RETAIN - Servants are not retained by the POA.

   If no ServantRetentionPolicy is specified at POA creation, the default is RETAIN.

   Note – The NON_RETAIN policy requires either the USE_DEFAULT_SERVANT or USE_SERVANT_MANAGER policies.

   11.3.8.6 Request Processing Policy

   Objects with the RequestProcessingPolicy interface are obtained using the POA::create_request_processing_policy operation and passed to the POA::create_POA operation to specify how requests are processed by the created POA. The following values can be supplied.

• USE_ACTIVE_OBJECT_MAP_ONLY - If the Object Id is not found in the Active Object Map, an OBJECT_NOT_EXIST system exception with standard minor code 2 is returned to the client. The RETAIN policy is also required.

• USE_SERVANT_MANAGER - If the Object Id is not found in the Active Object Map or the NON_RETAIN policy is present, and a servant manager has been registered with the POA using the set_servant_manager operation, the servant manager is given the opportunity to locate a servant or raise an exception. If no servant manager has been registered, an OBJ_ADAPTER system exception with standard minor code 4 is returned to the client.

• USE_DEFAULT_SERVANT - If the Object Id is not found in the Active Object Map or the NON_RETAIN policy is present, and a default servant has been registered with the POA using the set_servant operation, the request is dispatched

to the default servant. If no default servant has been registered, an OBJ_ADAPTER system exception with standard minor code 3 is returned to the client. The MULTIPLE_ID policy is also required.

   If no RequestProcessingPolicy is specified at POA creation, the default is USE_ACTIVE_OBJECT_MAP_ONLY.

   By means of combining the USE_ACTIVE_OBJECT_MAP_ONLY / USE_DEFAULT_SERVANT / USE_SERVANT_MANAGER policies and the RETAIN / NON_RETAIN policies, the programmer is able to define a rich number of possible behaviors.

   RETAIN and USE_ACTIVE_OBJECT_MAP_ONLY

   This combination represents the situation where the POA does no automatic object activation (that is, the POA searches only the Active Object Map).

   RETAIN and USE_SERVANT_MANAGER

   This combination represents a very common situation, where there is an Active Object Map and a ServantManager.

   Because RETAIN is in effect, the application can call activate_object or activate_object_with_id to establish known servants in the Active Object Map for use in later requests.

   If the POA doesn't find a servant in the Active Object Map for a given object, it tries to determine the servant by means of invoking incarnate in the ServantManager (specifically a ServantActivator) registered with the POA. If no ServantManager is available, the POA raises the OBJ_ADAPTER system exception with standard minor code 4.

   RETAIN and USE_DEFAULT_SERVANT

   This combination represents the situation where there is a default servant defined for all requests involving unknown objects.

   Because RETAIN is in effect, the application can call activate_object or activate_object_with_id to establish known servants in the Active Object Map for use in later requests.

   The POA first tries to find a servant in the Active Object Map for a given object. If it does not find such a servant, it uses the default servant. If no default servant is available, the POA raises the OBJ_ADAPTER system exception with standard minor code 3.

   NON-RETAIN and USE_SERVANT_MANAGER

   This combination represents the situation where one servant is used per method call.

   The POA doesn't try to find a servant in the Active Object Map because the ActiveObjectMap does not exist. In every request, it will call preinvoke on the ServantManager (specifically a ServantLocator) registered with the POA. If no ServantManager is available, the POA will raise the OBJ_ADAPTER system exception.

   NON-RETAIN and USE_DEFAULT_SERVANT

   This combination represents the situation where there is one single servant defined for all CORBA objects.

   The POA does not try to find a servant in the Active Object Map because the ActiveObjectMap doesn't exist. In every request, the POA will invoke the appropriate operation on the default servant registered with the POA. If no default servant is available, the POA will raise the OBJ_ADAPTER system exception.

   11.3.8.7 Implicit Activation Policy

   Objects with the ImplicitActivationPolicy interface are obtained using the POA::create_implicit_activation_policy operation and passed to the POA::create_POA operation to specify whether implicit activation of servants is supported in the created POA. The following values can be supplied.

• IMPLICIT_ACTIVATION - the POA will support implicit activation of servants. IMPLICIT_ACTIVATION also requires the SYSTEM_ID and RETAIN policies.

• NO_IMPLICIT_ACTIVATION - the POA will not support implicit activation of servants.

   If no ImplicitActivationPolicy is specified at POA creation, the default is NO_IMPLICIT_ACTIVATION.