org.omg.PortableServer
Interface POAOperations

All Known Subinterfaces:

POA, com.inprise.vbroker.PortableServerExt.POA, POAOperations, PSA, PSAOperations

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.

Method Summary

void	activate_object_with_id(byte[] id, Servant p_servant) This operation requires the RETAIN policy; if not present, the WrongPolicy exception is raised.
byte[]	activate_object(Servant p_servant) This operation requires the SYSTEM_ID and RETAIN policy; if not present, the WrongPolicy exception is raised.
IdAssignmentPolicy	create_id_assignment_policy(IdAssignmentPolicyValue value) This method returns an IdAssignmentPolicy object with the specified value.
IdUniquenessPolicy	create_id_uniqueness_policy(IdUniquenessPolicyValue value) This method returns an IdUniquenessPolicy object with the specified value.
ImplicitActivationPolicy	create_implicit_activation_policy(ImplicitActivationPolicyValue value) This method returns an ImplicitActivationPolicy object with the specified value.
LifespanPolicy	create_lifespan_policy(LifespanPolicyValue value) This method returns a LifespanPolicy object with the specified value.
POA	create_POA(java.lang.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, java.lang.String intf) This operation creates an object reference that encapsulates the specified Object Id and interface repository Id values.
Object	create_reference(java.lang.String intf) This operation requires the SYSTEM_ID policy; if not present, the WrongPolicy exception is raised.
RequestProcessingPolicy	create_request_processing_policy(RequestProcessingPolicyValue value) This method returns a RequestProcessingPolicy object with the specified value.
ServantRetentionPolicy	create_servant_retention_policy(ServantRetentionPolicyValue value) This method returns a ServantRetentionPolicy object with the specified value. If no ServantRetentionPolicy is specified at POA creation, then the default is RETAIN.
ThreadPolicy	create_thread_policy(ThreadPolicyValue value) This method returns a ThreadPolicy object with the specified value. If no ThreadPolicy is specified at POA creation, then the default is ORB_CTRL_MODEL.
void	deactivate_object(byte[] oid) This operation requires the RETAIN policy; if not present, the WrongPolicy exception is raised.
void	destroy(boolean etherealize_objects, boolean wait_for_completion) This operation destroys the POA and all descendant POAs.
POA	find_POA(java.lang.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()
Servant	get_servant() This operation requires the USE_DEFAULT_SERVANT policy; if not present, the WrongPolicy exception is raised.
Object	id_to_reference(byte[] oid) 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.
Servant	id_to_servant(byte[] oid) This operation requires the RETAIN policy or the USE_DEFAULT_SERVANT policy.
byte[]	id() This returns the unique id of the POA in the process in which it is created.
byte[]	reference_to_id(Object reference) The WrongPolicy exception is declared to allow future extensions.
Servant	reference_to_servant(Object reference) This operation requires the RETAIN policy or the USE_DEFAULT_SERVANT policy.
byte[]	servant_to_id(Servant p_servant) 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 not present, the WrongPolicy exception is raised.
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 requires the USE_SERVANT_MANAGER policy; if not present, the WrongPolicy exception is raised.
void	set_servant(Servant p_servant) This operation requires the USE_DEFAULT_SERVANT policy; if not present, the WrongPolicy exception is raised.
AdapterActivator	the_activator() This attribute identifies the adapter activator associated with the POA.
void	the_activator(AdapterActivator arg0) This attribute identifies the adapter activator associated with the POA.
POA[]	the_children() This method returns the current set of all child POAs of the POA.
java.lang.String	the_name() This method returns the read-only attribute which identifies the POA relative to its parent.
POA	the_parent() This method returns the POA's parent POA.
POAManager	the_POAManager() This method returns the POAManager associated with the POA.
POAManagerFactory	the_POAManagerFactory() This attribute returns the POAManagerFactory that created the POA

Method Detail

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.

id_to_reference

Object id_to_reference(byte[] oid)
                       throws 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.

Parameters:

oid - The ObjectId of the object for which a reference is to be returned.

Throws:

ObjectNotActive - if the Object Id value is not active in the POA.

WrongPolicy - if the RETAIN policy is not present.

id_to_servant

Servant id_to_servant(byte[] oid)
                      throws 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.

Parameters:

reference - The object for which a servant is to be returned.

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.

reference_to_id

byte[] reference_to_id(Object reference)
                       throws 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.

       Though the IDL specifies that a WrongPolicy exception may be raised by this
       method, it is simply declared for possible future extension.
       

Parameters:

reference - The object for which an ObjectId is to be returned.

Throws:

WrongAdapter - if the reference was not created by the POA specified in the reference.

WrongPolicy - declared to allow future extensions.

reference_to_servant

Servant reference_to_servant(Object reference)
                             throws 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.

Parameters:

reference - object reference for which the servant is returned.

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.

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. 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.

Parameters:

p_servant - The Servant for which a reference is to be returned.

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.

servant_to_id

byte[] servant_to_id(Servant p_servant)
                     throws 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 not present, the WrongPolicy exception is raised. 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 - The Servant for which the ObjectId to be returned is desired.

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.

create_reference_with_id

Object create_reference_with_id(byte[] oid,
                                java.lang.String 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. 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.

Parameters:

oid - object id for creating an objref.

iintf - rep id for creating an objref.

create_reference

Object create_reference(java.lang.String intf)
                        throws 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.

Parameters:

intf - RepositoryId of the Object.

Throws:

WrongPolicy - - if SYSTEM_ID policy is not specified.

deactivate_object

void deactivate_object(byte[] oid)
                       throws 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 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. 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.
       

Parameters:

oid - The ObjectId of 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.

activate_object_with_id

void activate_object_with_id(byte[] id,
                             Servant p_servant)
                             throws ServantAlreadyActive,
                                    ObjectAlreadyActive,
                                    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.
       

Parameters:

servant - to be associated with an object to be activated.

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.

activate_object

byte[] activate_object(Servant p_servant)
                       throws 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.

Parameters:

servant - The servant to be activated.

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.

set_servant

void set_servant(Servant p_servant)
                 throws 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.

Parameters:

p_servant - The Servant to be used as the default associated with the POA.

Throws:

WrongPolicy - raised if the USE_DEFAULT_SERVANT policy is not specified.

get_servant

Servant get_servant()
                    throws 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.

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_manager

void set_servant_manager(ServantManager imgr)
                         throws WrongPolicy

This operation requires the USE_SERVANT_MANAGER policy; if not present, the WrongPolicy exception 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 exception being raised.

Parameters:

imgr - The ServantManager to be used as the default used with the POA.

Throws:

WrongPolicy - raised if the USE_SERVANT_MANAGER policy is not specified.

get_servant_manager

ServantManager get_servant_manager()
                                   throws WrongPolicy

Throws:

WrongPolicy

the_POAManagerFactory

POAManagerFactory the_POAManagerFactory()

This attribute returns the POAManagerFactory that created the POA

the_activator

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.

the_activator

void the_activator(AdapterActivator arg0)

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.

the_POAManager

POAManager the_POAManager()

This method returns the POAManager associated with the POA.

the_children

POA[] the_children()

This method returns 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_parent

POA the_parent()

This method returns the POA's parent POA. The parent of the root POA is null.

the_name

java.lang.String the_name()

This method returns the read-only attribute which identifies the POA relative to its parent. This attribute is assigned at POA creation. The name of the root POA is system dependent and should not be relied upon by the application.

create_request_processing_policy

RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue value)

This method returns a RequestProcessingPolicy object with the specified value.
If no RequestProcessingPolicy is specified at POA creation, then the default is USE_ACTIVE_OBJECT_MAP_ONLY.

Parameters:

If - set to USE_ACTIVE_OBJECT_MAP_ONLY and the object id is not found in the Active Object Map, then an OBJECT_NOT_EXIST exception is returned to the client. (The RETAIN policy is also required.)
If set to USE_DEFAULT_SERVANT and 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 method, then the request is dispatched to the default servant. If no default servant has been registered, then an OBJ_ADAPTER exception is returned to the client. (The MULTIPLE_ID policy is also required.)
If set to USE_SERVANT_MANAGER and 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 method, then the servant manager is given the opportunity to locate a servant or raise an exception. If no servant manager has been registered, then an OBJ_ADAPTER is returned to the client.

create_servant_retention_policy

ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue value)

This method returns a ServantRetentionPolicy object with the specified value.
If no ServantRetentionPolicy is specified at POA creation, then the default is RETAIN.

Parameters:

value - If set to RETAIN, then the POA will retain active servants in its Active Object Map. If set to NON_RETAIN, then servants are not retained by the POA.

create_implicit_activation_policy

ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue value)

This method returns an ImplicitActivationPolicy object with the specified value.
If no ImplicitActivationPolicy is specified at POA creation, then the default is NO_IMPLICIT_ACTIVATION.

Parameters:

value - If set to IMPLICIT_ACTIVATION, the POA will support implicit activation of servants: also requires SYSTEM_ID and RETAIN policies. If set to NO_IMPLICIT_ACTIVATION, the POA will not support the implicit activation of servants.

create_id_assignment_policy

IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value)

This method returns an IdAssignmentPolicy object with the specified value. If no IdAssignmentPolicy is specified at POA creation, then the default is SYSTEM_ID.

Parameters:

value - If set to USER_ID, then objects created the POA are assigned object ids only by the application. If set to SYSTEM_ID, then objects created with the POA are assigned object ids only by the POA.

create_id_uniqueness_policy

IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue value)

This method returns an IdUniquenessPolicy object with the specified value. If no IdUniquenessPolicy is specified at POA creation, then the default is UNIQUE_ID.

Parameters:

value - If set to UNIQUE_ID, then servants which are activated with the POA support exactly one object id. If set to MULTIPLE_ID, then a servant which is activated with the POA may support one or more object ids.

create_lifespan_policy

LifespanPolicy create_lifespan_policy(LifespanPolicyValue value)

This method returns a LifespanPolicy object with the specified value. If no LifespanPolicy is specified at POA creation, then the default is TRANSIENT.

Parameters:

value - If set to TRANSIENT, then objects implemented in the POA cannot outlive the POA instance in which they were first created. Once a transient POA is deactivated, the use of any object references generated from it will result in an OBJECT_NOT_EXIST exception being raised. If set to PERSISTENT, then the objects implemented in the POA can outlive any process in which they are first created.

create_thread_policy

ThreadPolicy create_thread_policy(ThreadPolicyValue value)

This method returns a ThreadPolicy object with the specified value.
If no ThreadPolicy is specified at POA creation, then the default is ORB_CTRL_MODEL.

Parameters:

value - If set to 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. If set to SINGLE_THREAD_MODEL, then requests to the POA are processed sequentially. In a multi-threaded environment, all upcalls made by the POA to servants and servant managers are made in a manner that is safe for code that is multi-thread unaware.

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.  (This differs from the POAManager::deactivate
       operation that does not allow a re-creation 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:  he 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.  The apparent destruction of the POA
       occurs only after all executing requests in the POA have
       completed. After destruction has become apparent, the POA may be
       re-created via either an AdapterActivator or a call to
       create_POA.  f t he 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. Once apparent destruction has
       occurred, the POA behaves as if its POAManager is in the holding
       state until destruction is complete. Thus, for example, an
       invocation of create_POA with the same name blocks until POA
       destruction has finished.  The wait_for_completion parameter is
       handled as follows:  f 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.  f
       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 exception 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).
       

Parameters:

etherealize_objects - If True, the POA has the RETAIN policy, and a servant manager has registered with the POA, then the etherealize method is called on each active object in the Active Object Map. The apparent destruction of the POA occurs before the etherealize method is called, and thus any etherealize method which attempts to invoke methods on the POA raises a OBJECT_NOT_EXIST exception.

wait_for_completion - If 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 method only returns after all active requests and all invocations of etherealize have completed. If 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 exception is raised and POA destruction does not occur.

find_POA

POA find_POA(java.lang.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. 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.

Parameters:

adapter_name - The name of the AdapterActivator associated with the POA.

activate_it - If set to True and no child POA of the POA specified by adapter_name exists, then the POA's AdapterActivator, if not null, is invoked, and, if it successfully activates the child POA, then that POA is returned. Otherwise an AdapterNonExistent exception is raised.

Returns:

POA if one exists or is activated by the AdapterActivator.

Throws:

AdapterNonExistent.

AdapterNonExistent

create_POA

POA create_POA(java.lang.String adapter_name,
               POAManager a_POAManager,
               Policy[] policies)
               throws 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.
       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
       

Parameters:

adapter_name - The name which specifies the new POA.

a_POAManager - The manager of the new POA.

policies - A list of policies which are to apply to the new POA.

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.