11.3.9 POA Interface

   A POA object manages the implementation of a collection of objects. The POA supports a name space for the objects, which are identified by Object Ids.

   A POA also provides a name space for POAs. A POA is created as a child of an existing POA, which forms a hierarchy starting with the root POA.

   The POA interface is a local interface.

   11.3.9.1 create_POA

   POA create_POA( in string adapter_name, in POAManager a_POAManager, in CORBA::PolicyList policies)

   raises (AdapterAlreadyExists, InvalidPolicy );

   This operation creates a new POA as a child of the target POA. The specified name identifies the new POA with respect to other POAs with the same parent POA. If the target POA already has a child POA with the specified name, the AdapterAlreadyExists exception is raised.

   If the a_POAManager parameter is null, a new POAManager object is created and associated with the new POA. Otherwise, the specified POAManager object is associated with the new POA. The POAManager object can be obtained using the attribute name the_POAManager.

   The specified policy objects are associated with the POA and used to control its behavior. The policy objects are effectively copied before this operation returns, so the application is free to destroy them while the POA is in use. Policies are not inherited from the parent POA.

   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.

   If any of the policy objects specified are not valid for the ORB implementation, if conflicting policy objects are specified, or if any of the specified policy objects require prior administrative action that has not been performed, an InvalidPolicy exception is raised containing the index in the policies parameter value of the first offending policy object.

   Note – Creating a POA using a POA manager that is in the active state can lead to race conditions if the POA supports preexisting objects, because the new POA may receive a request before its adapter activator, servant manager, or default servant have been initialized. These problems do not occur if the POA is created by an adapter activator registered with a parent of the new POA, because requests are queued until the adapter activator returns. To avoid these problems when a POA must be explicitly initialized, the application can initialize the POA by invoking find_POA with a TRUE activate parameter.

   11.3.9.2 find_POA

   POA find_POA(in string adapter_name, in boolean activate_it)raises (AdapterNonExistent

   );

   If the target POA is the parent of a child POA with the specified name (relative to the target POA), that child POA is returned. If a child POA with the specified name does not exist and the value of the activate_it parameter is TRUE, the target POA's AdapterActivator, if one exists, is invoked, and, if it successfully activates the child POA, that child POA is returned. Otherwise, the AdapterNonExistent exception is raised.

   If find_POA receives a system exception in response to a call to unknown_adapter on a POA, find_POA raises OBJ_ADAPTER system exception with standard minor code 1

   11.3.9.3 destroy

   void destroy(in boolean etherealize_objects,in boolean wait_for_completion

   );

   This operation destroys the POA and all descendant POAs. All descendant POAs are destroyed (recursively) before the destruction of the containing POA. The POA so destroyed (that is, the POA with its name) may be re-created later in the same process. (This differs from the POAManager::deactivate operation that does not allow a recreation of its associated POA in the same process. After a deactivate, re-creation is allowed only if the POA is later destroyed.)

   When destroy is called the POA behaves as follows:

• The POA assumes the discarding state except when its POAManager is in the inactive state in which case the POA assumes the inactive state. Any further changes to the POAManager's state do not affect this POA.

• The POA calls destroy on all of its immediate descendants.

• After all descendant POAs have been destroyed and their servants etherealized, the POA continues to process requests until there are no requests executing in the POA. At this point, apparent destruction of the POA has occurred.

• After destruction has become apparent, the POA may be re-created via either an AdapterActivator or a call to create_POA.

• If the etherealize_objects parameter is TRUE, the POA has the RETAIN policy, and a servant manager is registered with the POA, the etherealize operation on the servant manager is called for each active object in the Active Object Map. The apparent destruction of the POA occurs before any calls to etherealize are made. Thus, for example, an etherealize method that attempts to invoke operations on the POA receives the OBJECT_NOT_EXIST exception.

• If the POA has an AdapterActivator installed, any requests that would have caused unknown_adapter to be called cause a TRANSIENT exception with standard minor code 4 to be raised instead.

• If wait_for_completion is TRUE and the current thread is not in an invocation context dispatched from some POA belonging to the same ORB as this POA, the destroy operation returns only after all active requests have completed and all invocations of etherealize have completed.

• If wait_for_completion is TRUE and the current thread is in an invocation context dispatched from some POA belonging to the same ORB as this POA, the BAD_INV_ORDER system exception with standard minor code 3 is raised and POA destruction does not occur.

• If wait_for_completion is FALSE, the destroy operation destroys the POA and its children but waits neither for active requests to complete nor for etherealization to occur. If destroy is called multiple times before destruction is complete (because there are active requests), the etherealize_objects parameter applies only to the first call of destroy. Subsequent calls with conflicting etherealize_objects settings use the value of etherealize_objects from the first call. The wait_for_completion parameter is handled as defined above for each individual call (some callers may choose to block, while others may not).

• The POA disables the create_POA operation. Subsequent calls to create_POA will result in a BAD_INV_ORDER system exception with standard minor code

17.

   The wait_for_completion parameter is handled as follows:

   11.3.9.4 Policy Creation Operations

   ThreadPolicy create_thread_policy(in ThreadPolicyValue value);LifespanPolicy create_lifespan_policy(in LifespanPolicyValue value);

   IdUniquenessPolicy create_id_uniqueness_policy(in IdUniquenessPolicyValue value);IdAssignmentPolicy create_id_assignment_policy(in IdAssignmentPolicyValue value);

   ImplicitActivationPolicy create_implicit_activation_policy( in ImplicitActivationPolicyValue value); ServantRetentionPolicy create_servant_retention_policy( in ServantRetentionPolicyValue value); RequestProcessingPolicy create_request_processing_policy( in RequestProcessingPolicyValue value);

   These operations each return a reference to a policy object with the specified value. The application is responsible for calling the inherited destroy operation on the returned reference when it is no longer needed.

   11.3.9.5 the_name

   readonly attribute string the_name;

   This attribute identifies the POA relative to its parent. This name is assigned when the POA is created. The name of the root POA is system-dependent and should not be relied upon by the application. In order to work properly with Portable Interceptors (see Section 21.5.2.1, “Adapter Names,? on page 21-41 ) the name of the root POA must be the sequence containing only the string “RootPOA?.

   11.3.9.6 the_parent

   readonly attribute POA the_parent;

   This attribute identifies the parent of the POA. The parent of the root POA is null.

   11.3.9.7 the_children

   readonly attribute POAList the_children;

   This attribute identifies the current set of all child POAs of the POA. The set of child POAs includes only the POA's immediate children, and not their descendants.

   11.3.9.8 the_POAManager

   readonly attribute POAManager the_POAManager;

   This attribute identifies the POA manager associated with the POA.

   11.3.9.9 the_activator

   attribute AdapterActivator the_activator;

   This attribute identifies the adapter activator associated with the POA. A newly created POA has no adapter activator (the attribute is null). It is system-dependent whether the root POA initially has an adapter activator; the application is free to assign its own adapter activator to the root POA.

   11.3.9.10 the_POAManagerFactory

    readonly attribute POAManagerFactory the_POAManagerFactory; This attribute returns the POAManagerFactory that created the POA.

   11.3.9.11 get_servant_manager

   ServantManager get_servant_manager()raises(WrongPolicy);

   This operation requires the USE_SERVANT_MANAGER policy; if not present, the WrongPolicy exception is raised.

   This operation returns the servant manager associated with the POA. If no servant manager has been associated with the POA, it returns a null reference.

   11.3.9.12 set_servant_manager

   void set_servant_manager(

   in ServantManager imgr) raises(WrongPolicy);

   This operation requires the USE_SERVANT_MANAGER policy; if not present, the WrongPolicy exception is raised.

   If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface (e.g., in C++ imgr is narrowable to ServantActivator). If the ServantRetentionPolicy of the POA is NON_RETAIN, then the ServantManager argument shall support the ServantLocator interface. If the argument is nil, or does not support the required interface, then the OBJ_ADAPTER system exception with standard minor code 4 is raised.

   This operation sets the default servant manager associated with the POA. This operation may only be invoked once after a POA has been created. Attempting to set the servant manager after one has already been set will result in the BAD_INV_ORDER system exception with standard minor code 6 being raised.

   11.3.9.13 get_servant

   Servant get_servant()raises(NoServant, WrongPolicy);

   This operation requires the USE_DEFAULT_SERVANT policy; if not present, the WrongPolicy exception is raised.

   This operation returns the default servant associated with the POA. If no servant has been associated with the POA, the NoServant exception is raised.

   11.3.9.14 set_servant

   void set_servant(in Servant p_servan

   ) raises(WrongPolicy);

   This operation requires the USE_DEFAULT_SERVANT policy; if not present, the WrongPolicy exception is raised.

   This operation registers the specified servant with the POA as the default servant. This servant will be used for all requests for which no servant is found in the Active Object Map.

   11.3.9.15 activate_object

   ObjectId activate_object(in Servant p_servant

   ) raises (ServantAlreadyActive, WrongPolicy);

   This operation requires the SYSTEM_ID and RETAIN policy; if not present, the WrongPolicy exception is raised.

   If the POA has the UNIQUE_ID policy and the specified servant is already in the Active Object Map, the ServantAlreadyActive exception is raised. Otherwise, the activate_object operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map. The Object Id is returned.

   11.3.9.16 activate_object_with_id

   void activate_object_with_id(in ObjectId oid, in Servant p_servant

   ) raises (ObjectAlreadyActive, ServantAlreadyActive, WrongPolicy);

   This operation requires the RETAIN policy; if not present, the WrongPolicy exception is raised.

   If the CORBA object denoted by the Object Id value is already active in this POA (there is a servant bound to it in the Active Object Map), the ObjectAlreadyActive exception is raised. If the POA has the UNIQUE_ID policy and the servant is already in the Active Object Map, the ServantAlreadyActive exception is raised. Otherwise, the activate_object_with_id operation enters an association between the specified Object Id and the specified servant in the Active Object Map.

   If the POA has the SYSTEM_ID policy and it detects that the Object Id value was not generated by the system or for this POA, the activate_object_with_id operation may raise the BAD_PARAM system exception. An ORB is not required to detect all such invalid Object Id values, but a portable application must not invoke activate_object_with_id on a POA that has the SYSTEM_ID policy with an Object Id value that was not previously generated by the system for that POA, or, if the POA also has the PERSISTENT policy, for a previous instantiation of the same POA. A POA is not required to raise the BAD_PARAM exception in this case because, in the general case, accurate rejection of an invalid Object Id requires unbounded persistent memory of all previously generated Id values.

   11.3.9.17 deactivate_object

   void deactivate_object(in ObjectId oid

   ) raises (ObjectNotActive, WrongPolicy);

   This operation requires the RETAIN policy; if not present, the WrongPolicy exception is raised.

   This operation causes the ObjectId specified in the oid parameter to be deactivated. An ObjectId that has been deactivated continues to process requests until there are no active requests for that ObjectId. Active requests are those requests that arrived before deactivate_object was called. A deactivated ObjectId is removed from the Active Object Map when all requests executing for that ObjectId have completed. If a servant manager is associated with the POA, ServantActivator::etherealize is invoked with the oid and the associated servant after the ObjectId has been removed from the Active Object Map. Reactivation for the ObjectId blocks until etherealization (if necessary) is complete. This includes implicit activation (as described in etherealize) and explicit activation via POA::activate_object_with_id. Once an ObjectId has been removed from the Active Object Map and etherealized (if necessary) it may then be reactivated through the usual mechanisms.

   The operation does not wait for requests or etherealization to complete and always returns immediately after deactivating the ObjectId.

   Note – If the servant associated with the oid is serving multiple Object Ids, ServantActivator::etherealize may be invoked multiple times with the same servant when the other objects are deactivated. It is the responsibility of the object implementation to refrain from destroying the servant while it is active with any Id.

   11.3.9.18 create_reference

   Object create_reference (in CORBA::RepositoryId intf

   ) raises (WrongPolicy);

   This operation requires the SYSTEM_ID policy; if not present, the WrongPolicy exception is raised.

   This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id. The specified repository id, which may be a null string, will become the type_id of the generated object reference. A repository id that does not identify the most derived interface of the object or one of its base interfaces will result in undefined behavior.

   This operation does not cause an activation to take place. The resulting reference may be passed to clients, so that subsequent requests on those references will cause the appropriate servant manager to be invoked, if one is available. The generated Object Id value may be obtained by invoking POA::reference_to_id with the created reference.

   11.3.9.19 create_reference_with_id

   Object create_reference_with_id (in ObjectId oid,in CORBA::RepositoryId intf

   );

   This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values. The specified repository id, which may be a null string, will become the type_id of the generated object reference. A repository id that does not identify the most derived interface of the object or one of its base interfaces will result in undefined behavior.

   This operation does not cause an activation to take place. The resulting reference may be passed to clients, so that subsequent requests on those references will cause the object to be activated if necessary, or the default servant used, depending on the applicable policies.

   If the POA has the SYSTEM_ID policy and it detects that the Object Id value was not generated by the system or for this POA, the create_reference_with_id operation may raise the BAD_PARAM system exception with standard minor code 14. An ORB is not required to detect all such invalid Object Id values, but a portable application must not invoke this operation on a POA that has the SYSTEM_ID policy with an Object Id value that was not previously generated by the system for that POA, or, if the POA also has the PERSISTENT policy, for a previous instantiation of the same POA.

   11.3.9.20 servant_to_id

   ObjectId servant_to_id(in Servant p_servant

   ) raises (ServantNotActive, WrongPolicy);

   This operation requires the USE_DEFAULT_SERVANT policy or a combination of the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA. If this operation is not invoked in the context of executing a request on the specified servant and the policies specified previously are not present, the WrongPolicy exception is raised.

   This operation has four possible behaviors.

1. If the POA has both the RETAIN and the UNIQUE_ID policy and the specified servant is active, the Object Id associated with that servant is returned.

2. If the POA has both the RETAIN and the IMPLICIT_ACTIVATION policy and either the POA has the MULTIPLE_ID policy or the specified servant is not active, the servant is activated using a POA-generated Object Id and the Interface Id associated with the servant, and that Object Id is returned.

3. If the POA has the USE_DEFAULT_SERVANT policy, the servant specified is the default servant, and the operation is being invoked in the context of executing a request on the default servant, then the ObjectId associated with the current invocation is returned.

4. Otherwise, the ServantNotActive exception is raised.

   11.3.9.21 servant_to_reference

   Object servant_to_reference (in Servant p_servant

   ) raises (ServantNotActive, WrongPolicy);

   This operation requires the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies if invoked outside the context of an operation dispatched by this POA. If this operation is not invoked in the context of executing a request on the specified servant and the policies specified previously are not present the WrongPolicy exception is raised.

   This operation has four possible behaviors.

1. If the POA has both the RETAIN and the UNIQUE_ID policy and the specified servant is active, an object reference encapsulating the information used to activate the servant is returned.

2. If the POA has both the RETAIN and the IMPLICIT_ACTIVATION policy and either the POA has the MULTIPLE_ID policy or the specified servant is not active, the servant is activated using a POA-generated Object Id and the Interface Id associated with the servant, and a corresponding object reference is returned.

3. If the operation was invoked in the context of executing a request on the specified servant, the reference associated with the current invocation is returned.

4. Otherwise, the ServantNotActive exception is raised.

   Note – The allocation of an Object Id value and installation in the Active Object Map caused by implicit activation may actually be deferred until an attempt is made to externalize the reference. The real requirement here is that a reference is produced that will behave appropriately (that is, yield a consistent Object Id value when asked politely).

   11.3.9.22 reference_to_servant

   Servant reference_to_servant (in Object reference

   ) raises (ObjectNotActive, WrongAdapter, WrongPolicy);

   This operation requires the RETAIN policy or the USE_DEFAULT_SERVANT policy. If neither policy is present, the WrongPolicy exception is raised.

   If the POA has the RETAIN policy and the specified object is present in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map. Otherwise, if the POA has the USE_DEFAULT_SERVANT policy and a default servant has been registered with the POA, this operation returns the default servant. Otherwise, the ObjectNotActive exception is raised.

   If the object reference was not created by this POA, the WrongAdapter exception is raised.

   11.3.9.23 reference_to_id

   ObjectId reference_to_id(in Object reference

   ) raises (WrongAdapter, WrongPolicy);

   The WrongPolicy exception is declared to allow future extensions.

   This operation returns the Object Id value encapsulated by the specified reference. This operation is valid only if the reference was created by the POA on which the operation is being performed. If the reference was not created by that POA, a WrongAdapter exception is raised. The object denoted by the reference does not have to be active for this operation to succeed.

   11.3.9.24 id_to_servant

   Servant id_to_servant(in ObjectId oid

   ) raises (ObjectNotActive, WrongPolicy);

   This operation requires the RETAIN policy or the USE_DEFAULT_SERVANT policy. If neither policy is present, the WrongPolicy exception is raised.

   If the POA has the RETAIN policy and the specified ObjectId is in the Active Object Map, this operation returns the servant associated with that object in the Active Object Map. Otherwise, if the POA has the USE_DEFAULT_SERVANT policy and a default servant has been registered with the POA, this operation returns the default servant. Otherwise the ObjectNotActive exception is raised.

   11.3.9.25 id_to_reference

   Object id_to_reference(in ObjectId oid

   ) raises (ObjectNotActive, WrongPolicy);

   This operation requires the RETAIN policy; if not present, the WrongPolicy exception is raised.

   If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned. If the Object Id value is not active in the POA, an ObjectNotActive exception is raised.

   11.3.9.26 id

   readonly attribute CORBA::OctetSeq id;

   This returns the unique id of the POA in the process in which it is created. It is for use by portable interceptors.

   This id is guaranteed unique for the life span of the POA in the process. For persistent POAs, this means that if a POA is created in the same path with the same name as another POA, these POAs are identical and, therefore, have the same id. For transient POAs, each POA is unique.

   11.3.10 Current Operations

   The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked. The Current interface is provided to support servants that implement multiple objects, but can be used within the context of POA-dispatched method invocations on any servant. To provide location transparency, ORBs are required to support use of Current in the context of both locally and remotely invoked operations.

   An instance of Current can be obtained by the application by issuing the CORBA::ORB::resolve_initial_references("POACurrent") operation. Thereafter, it can be used within the context of a method dispatched by the POA to obtain the POA and ObjectId that identify the object on which that operation was invoked.

   PortableServer::Current is a local interface.

   11.3.10.1 get_POA

   POA get_POA()raises (NoContext);

   This operation returns a reference to the POA implementing the object in whose context it is called. If called outside the context of a POA-dispatched operation, a NoContext exception is raised.

   11.3.10.2 get_object_id

   ObjectId get_object_id()raises (NoContext);

   This operation returns the ObjectId identifying the object in whose context it is called. If called outside the context of a POA-dispatched operation, a NoContext exception is raised.

   11.3.10.3 get_reference

   Object get_reference()raises(NoContext);

   This operation returns a locally manufactured reference to the object in the context of which it is called. If called outside the context of a POA dispatched operation, a NoContext exception is raised.

   Note – This reference is not guaranteed to be identical to the original reference the client used to make the invocation, and calling the Object::is_equivalent operation to compare the two references may not necessarily return true.

   11.3.10.4 get_servant

   Servant get_servant() raises(NoContext);

   This operation returns a reference to the servant that hosts the object in whose context it is called. If called outside the context of a POA dispatched operation, a NoContext exception is raised.