POAOperations

All Known Subinterfaces:

POA
```
public interface POAOperations
```
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. A POA object must not be exported to other processes, or externalized with ORB::object_to_string.

Method Summary

All Methods

Instance Methods

Abstract Methods
Modifier and Type	Method and Description
`void`	`activate_object_with_id(byte[] id, Servant p_servant)` This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.
`byte[]`	`activate_object(Servant p_servant)` This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.
`IdAssignmentPolicy`	`create_id_assignment_policy(IdAssignmentPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`IdUniquenessPolicy`	`create_id_uniqueness_policy(IdUniquenessPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`ImplicitActivationPolicy`	`create_implicit_activation_policy(ImplicitActivationPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`LifespanPolicy`	`create_lifespan_policy(LifespanPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`POA`	`create_POA(String adapter_name, POAManager a_POAManager, Policy[] policies)` This operation creates a new POA as a child of the target POA.
`Object`	`create_reference_with_id(byte[] oid, String intf)` This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values.
`Object`	`create_reference(String intf)` This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id.
`RequestProcessingPolicy`	`create_request_processing_policy(RequestProcessingPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`ServantRetentionPolicy`	`create_servant_retention_policy(ServantRetentionPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`ThreadPolicy`	`create_thread_policy(ThreadPolicyValue value)` These operations each return a reference to a policy object with the specified value.
`void`	`deactivate_object(byte[] oid)` This operation causes the ObjectId specified in the oid parameter to be deactivated.
`void`	`destroy(boolean etherealize_objects, boolean wait_for_completion)` This operation destroys the POA and all descendant POAs.
`POA`	`find_POA(String adapter_name, boolean activate_it)` 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.
`ServantManager`	`get_servant_manager()` If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface.
`Servant`	`get_servant()` This operation returns the default servant associated with the POA.
`Object`	`id_to_reference(byte[] oid)` If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.
`Servant`	`id_to_servant(byte[] oid)` 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.
`byte[]`	`id()` This returns the unique id of the POA in the process in which it is created.
`byte[]`	`reference_to_id(Object reference)` This operation returns the Object Id value encapsulated by the specified reference.
`Servant`	`reference_to_servant(Object reference)` 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.
`byte[]`	`servant_to_id(Servant p_servant)` This operation has four possible behaviors.
`Object`	`servant_to_reference(Servant p_servant)` 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.
`void`	`set_servant_manager(ServantManager imgr)` This operation sets the default servant manager associated with the POA.
`void`	`set_servant(Servant p_servant)` This operation registers the specified servant with the POA as the default servant.
`AdapterActivator`	`the_activator()` This attribute identifies the adapter activator associated with the POA.
`void`	`the_activator(AdapterActivator newThe_activator)` This attribute identifies the adapter activator associated with the POA.
`POA[]`	`the_children()` This attribute identifies the current set of all child POAs of the POA.
`String`	`the_name()` This attribute identifies the POA relative to its parent.
`POA`	`the_parent()` This attribute identifies the parent of the POA.
`POAManager`	`the_POAManager()` This attribute identifies the POA manager associated with the POA.

- Method Detail
  - create_POA
```
POA create_POA(String adapter_name,
               POAManager a_POAManager,
               Policy[] policies)
        throws AdapterAlreadyExists,
               InvalidPolicy
```
    This operation creates a new POA as a child of the target POA.
    
    Parameters:
    
    adapter_name - identifies the new POA with respect to other POAs with the same parent POA.
    
    a_POAManager - specifies the POA Manager to be associated with the new POA.
    
    policies - specifies policy objects to be associated with the POA to control its behavior.
    
    Throws:
    
    AdapterAlreadyExists - specifies that the target POA already has a child POA with the specified name.
    
    InvalidPolicy - is raised if any of the policy objects are not valid for the ORB, or are in conflict, or require an administrative action that has not been performed.
  - find_POA
```
POA find_POA(String adapter_name,
             boolean activate_it)
      throws 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.
    
    Parameters:
    
    adapter_name - POA name to be found.
    
    activate_it - if a 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.
    
    Returns:
    
    POA if one exists or is activated by the AdapterActivator.
    
    Throws:
    
    AdapterNonExistent
  - destroy
```
void destroy(boolean etherealize_objects,
             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.
    
    Parameters:
    
    etherealize_objects - flag to indicate whether etherealize operation on servant manager needs to be called.
    
    wait_for_completion - flag to indicate whether POA and its children need to wait for active requests and the etherealization to complete.
  - create_thread_policy
```
ThreadPolicy create_thread_policy(ThreadPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    ThreadPolcy Object
  - create_lifespan_policy
```
LifespanPolicy create_lifespan_policy(LifespanPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    LifespanPolicy Object.
  - create_id_uniqueness_policy
```
IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    IdUniquenessPolicy Object.
  - create_id_assignment_policy
```
IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    IdAssignmentPolicy Object.
  - create_implicit_activation_policy
```
ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    ImplicitActivationPolicy Object.
  - create_servant_retention_policy
```
ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    ServantRetentionPolicy Object.
  - create_request_processing_policy
```
RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue value)
```
    These operations each return a reference to a policy object with the specified value.
    
    Parameters:
    
    value - policy type
    
    Returns:
    
    RequestProcessingPolicy Object.
  - the_name
```
String the_name()
```
    This attribute identifies the POA relative to its parent. This name is assigned when the POA is created.
  - the_parent
```
POA the_parent()
```
    This attribute identifies the parent of the POA. The parent of the root POA is null.
  - the_children
```
POA[] 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.
  - the_POAManager
```
POAManager the_POAManager()
```
    This attribute identifies the POA manager associated with the POA.
  - the_activator
```
AdapterActivator the_activator()
```
    This attribute identifies the adapter activator associated with the POA.
  - the_activator
```
void the_activator(AdapterActivator newThe_activator)
```
    This attribute identifies the adapter activator associated with the POA.
  - get_servant_manager
```
ServantManager get_servant_manager()
                            throws WrongPolicy
```
    If the ServantRetentionPolicy of the POA is RETAIN, then the ServantManager argument (imgr) shall support the ServantActivator interface. For a NON_RETAIN policy, the ServantManager shall support the ServantLocator interface. If the argument is nil, or does not support the required interface, then the OBJ_ADAPTER exception is raised.
    
    Returns:
    
    ServantManager associated with a POA or null if none exists.
    
    Throws:
    
    WrongPolicy - raised if the USE_SERVANT_MANAGER policy is not specified.
  - set_servant_manager
```
void set_servant_manager(ServantManager imgr)
                  throws WrongPolicy
```
    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 exception being raised.
    
    Parameters:
    
    imgr - servant manager to be used as a default.
    
    Throws:
    
    WrongPolicy - raised if the USE_SERVANT_MANAGER policy is not specified.
  - get_servant
```
Servant get_servant()
             throws NoServant,
                    WrongPolicy
```
    This operation returns the default servant associated with the POA.
    
    Returns:
    
    p_servant default servant associated with a POA.
    
    Throws:
    
    NoServant - raised if no default servant is associated with the POA.
    
    WrongPolicy - raised if the USE_DEFAULT_SERVANT policy is not specified.
  - set_servant
```
void set_servant(Servant p_servant)
          throws WrongPolicy
```
    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.
    
    Parameters:
    
    p_servant - servant to be used as a default.
    
    Throws:
    
    WrongPolicy - raised if the USE_DEFAULT_SERVANT policy is not specified.
  - activate_object
```
byte[] activate_object(Servant p_servant)
                throws ServantAlreadyActive,
                       WrongPolicy
```
    This operation generates an Object Id and enters the Object Id and the specified servant in the Active Object Map.
    
    Parameters:
    
    p_servant - servant to be associated with an object to be activated.
    
    Returns:
    
    POA generated object id.
    
    Throws:
    
    ServantAlreadyActive - is raised if the POA has UNIQUE_ID policy and servant is is already in the Active Object Map.
    
    WrongPolicy - raised if the SYSTEM_ID and RETAIN policies are not specified.
  - activate_object_with_id
```
void activate_object_with_id(byte[] id,
                             Servant p_servant)
                      throws ServantAlreadyActive,
                             ObjectAlreadyActive,
                             WrongPolicy
```
    This operation enters an association between the specified Object Id and the specified servant in the Active Object Map.
    
    Parameters:
    
    id - object id for the object to be activated.
    
    p_servant - servant to be associated with the object.
    
    Throws:
    
    ServantAlreadyActive - raised if the POA has the UNIQUE_ID policy and the servant is already in the Active Object Map.
    
    ObjectAlreadyActive - raised if the object is already active in the POA.
    
    WrongPolicy - raised if the RETAIN policy is is not specified.
  - deactivate_object
```
void deactivate_object(byte[] oid)
                throws ObjectNotActive,
                       WrongPolicy
```
    This operation causes the ObjectId specified in the oid parameter to be deactivated. An ObjectId which has been deactivated continues to process requests until there are no active requests for that ObjectId. A deactivated ObjectId is removed from the Active Object Map when all requests executing for that ObjectId have completed.
    
    Parameters:
    
    oid - Object Id for the object to be deactivated.
    
    Throws:
    
    ObjectNotActive - if the object with the specified oid is not in the Active Object Map.
    
    WrongPolicy - raised if the RETAIN policy is is not specified.
  - create_reference
```
Object create_reference(String intf)
                 throws WrongPolicy
```
    This operation creates an object reference that encapsulates a POA-generated Object Id value and the specified interface repository id.
    
    Parameters:
    
    intf - rep id for creating an object reference.
    
    Returns:
    
    object reference created using intf.
    
    Throws:
    
    WrongPolicy - if SYSTEM_ID policy is not specified.
  - create_reference_with_id
```
Object create_reference_with_id(byte[] oid,
                                String intf)
```
    This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values. It 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.
    
    Parameters:
    
    oid - object id for creating an objref
    
    intf - rep id for creating an objref
    
    Returns:
    
    object reference created using oid and intf
    
    Throws:
    
    BAD_PARAM - is raised 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.
  - servant_to_id
```
byte[] servant_to_id(Servant p_servant)
              throws ServantNotActive,
                     WrongPolicy
```
    This operation has four possible behaviors. 1. If the POA has the UNIQUE_ID policy and the specified servant is active, the Object Id associated with that servant is returned. 2. If the POA has 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.
    
    Parameters:
    
    p_servant - servant for which the object disi returned.
    
    Returns:
    
    object id associated with the servant.
    
    Throws:
    
    ServantNotActive - if the above rules and policy combination is not met.
    
    WrongPolicy - if the USE_DEFAULT_SERVANT policy or a combination of the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies are not present.
  - servant_to_reference
```
Object servant_to_reference(Servant p_servant)
                     throws 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. It 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.
    
    Parameters:
    
    p_servant - servant for which the object reference needs to be obtained.
    
    Returns:
    
    object reference associated with the servant.
    
    Throws:
    
    WrongPolicy - if the operation is not invoked in the context of executing a request on the specified servant and the required policies are not present.
    
    ServantNotActive - if the above specified policies and rules are not met.
  - reference_to_servant
```
Servant reference_to_servant(Object reference)
                      throws ObjectNotActive,
                             WrongPolicy,
                             WrongAdapter
```
    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. If the object reference was not created by this POA, the WrongAdapter exception is raised. (OMG Issue on inconsistency with the POA.IDL.
    
    Parameters:
    
    reference - object reference for which the servant is returned.
    
    Returns:
    
    servant associated with the reference.
    
    Throws:
    
    WrongPolicy - if neither the RETAIN policy or the USE_DEFAULT_SERVANT policy is present.
    
    ObjectNotActive - if the servant is not present in the Active Object Map (for RETAIN) or no default servant is registered (for USE_DEFAULT_POLICY).
    
    WrongAdapter - if reference was not created by this POA instance.
  - reference_to_id
```
byte[] reference_to_id(Object reference)
                throws WrongAdapter,
                       WrongPolicy
```
    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. The object denoted by the reference does not have to be active for this operation to succeed.
    
    Parameters:
    
    reference - the object reference from which the object id needs to be returned.
    
    Returns:
    
    object id encapsulated in the reference.
    
    Throws:
    
    WrongAdapter - if the reference was not created by the POA specified in the reference.
    
    WrongPolicy - declared to allow future extensions.
  - id_to_servant
```
Servant id_to_servant(byte[] oid)
               throws ObjectNotActive,
                      WrongPolicy
```
    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.
    
    Parameters:
    
    oid - object id for the which the servant is returned.
    
    Returns:
    
    servant associated with oid.
    
    Throws:
    
    ObjectNotActive - is raised if ObjectId is is not in the Active Object Map (for RETAIN policy), or no default servant is registered (for USE_DEFAULT_SERVANT policy).
    
    WrongPolicy - is raised if the RETAIN policy or the USE_DEFAULT_SERVANT policy is not present.
  - id_to_reference
```
Object id_to_reference(byte[] oid)
                throws ObjectNotActive,
                       WrongPolicy
```
    If an object with the specified Object Id value is currently active, a reference encapsulating the information used to activate the object is returned.
    
    Parameters:
    
    oid - id of the object for which the reference is returned.
    
    Returns:
    
    the object reference
    
    Throws:
    
    ObjectNotActive - if the Object Id value is not active in the POA.
    
    WrongPolicy - if the RETAIN policy is not present.
  - id
```
byte[] 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.

Interface POAOperations

Method Summary

Method Detail

create_POA

find_POA

destroy

create_thread_policy

create_lifespan_policy

create_id_uniqueness_policy

create_id_assignment_policy

create_implicit_activation_policy

create_servant_retention_policy

create_request_processing_policy

the_name

the_parent

the_children

the_POAManager

the_activator

the_activator

get_servant_manager

set_servant_manager

get_servant

set_servant

activate_object

activate_object_with_id

deactivate_object

create_reference

create_reference_with_id

servant_to_id

servant_to_reference

reference_to_servant

reference_to_id

id_to_servant

id_to_reference

id