org.omg.PortableServer
Interface POAOperations

All Known Subinterfaces:
POA

public interface POAOperations

Defines the operations, applicable to the POA.


Method Summary
 void activate_object_with_id(byte[] an_Object_Id, Servant a_servant)
          Add the given servant to the Active Object Map as a servant for the object with the provided Object Id.
 byte[] activate_object(Servant a_servant)
          Generate the Object Id for the given servant and add the servant to the Active Object Map using this Id a a key.
 IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value)
          Create the ID assignment policy with the given value.
 IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue a_value)
          Create the IdUniquenessPolicy policy.
 ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue a_value)
          Create the ImplicitActivationPolicy policy.
 LifespanPolicy create_lifespan_policy(LifespanPolicyValue a_value)
          Create the LifespanPolicy policy.
 POA create_POA(String child_name, POAManager manager, Policy[] policies)
          Creates a new POA as a child of the target POA.
 Object create_reference_with_id(byte[] an_object_id, String a_repository_id)
           Create the object reference, encapsulating the given repository Id and the given Object Id.
 Object create_reference(String a_repository_id)
          Create the object reference, encapsulating the given repository Id and the Object Id, generated by this POA.
 RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue a_value)
          Create the RequestProcessingPolicy policy.
 ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue a_value)
          Create the ServantRetentionPolicy policy.
 ThreadPolicy create_thread_policy(ThreadPolicyValue a_value)
          Create the ThreadPolicy policy.
 void deactivate_object(byte[] the_Object_Id)
          Deactivate object with the given id.
 void destroy(boolean etherealize_objects, boolean wait_for_completion)
           Destroy this POA and all descendant POAs.
 POA find_POA(String poa_name, boolean activate_it)
          Find and optionally activate the child POA with the given name.
 ServantManager get_servant_manager()
          Get the servant manager, associated with this POA.
 Servant get_servant()
          Returns a default servant for this POA.
 Object id_to_reference(byte[] the_Object_Id)
          Returns the reference to the active object with the given Id.
 Servant id_to_servant(byte[] the_Object_Id)
          Returns the servant that serves the active object with the given Id.
 byte[] id()
          Get the unique Id of the POA in the process in which it is created.
 byte[] reference_to_id(Object the_Object)
          Returns the Object Id, encapsulated in the given object reference.
 Servant reference_to_servant(Object the_Object)
          Returns the servant that is serving this object.
 byte[] servant_to_id(Servant the_Servant)
          Returns the id of the object, served by the given servant.
 Object servant_to_reference(Servant the_Servant)
          Converts the given servant to the object reference.
 void set_servant_manager(ServantManager a_manager)
          Set a servant manager for this POA.
 void set_servant(Servant a_servant)
          Sets the default servant for this POA.
 AdapterActivator the_activator()
          Returns the adapter activator, associated with this POA.
 void the_activator(AdapterActivator activator)
          Set the adapter activator for this POA.
 POA[] the_children()
          The children of this POA.
 String the_name()
          Return the name of this POA.
 POA the_parent()
          Return the parent of this POA.
 POAManager the_POAManager()
          Return the POA manager, associated with this POA.
 

Method Detail

create_POA

POA create_POA(String child_name,
               POAManager manager,
               Policy[] policies)
               throws AdapterAlreadyExists,
                      InvalidPolicy
Creates a new POA as a child of the target POA.

Parameters:
child_name - the name of the child POA being created.
manager - the manager that will control the new POA. If this parameter is null, a new POA manager is created and associated with the new POA.
policies - the policies, applicable for the parent POA. Policies are not inherited from the parent POA. If some policy type is missing in the array (or the zero size array is passed), the missing policies obtain the default values from the table, specified in the POA documentation header.
Returns:
an newly created POA. The POA will be intially in the holding state and must be activated to start processing requests.
Throws:
AdapterAlreadyExists - if the child with the given child_name already exists for the current POA.
InvalidPolicy - if the policies conflict with each other or are otherwise inappropriate.
See Also:
for the list of required policies., the_children()

find_POA

POA find_POA(String poa_name,
             boolean activate_it)
             throws AdapterNonExistent
Find and optionally activate the child POA with the given name.

Parameters:
poa_name - the name of the POA to find.
activate_it - if the child with the specified name is not found or inactive and this parameter is true, the target POA activator is invoked to activate that child. If this succeeds, that child POA is returned.
Throws:
AdapterNonExistent - if no active child with the given name is found and one of the following is true: a) the target POA has no associated AdapterActivator. b) that activator fails to activate the child POA. c) activate_id = false.

activate_object

byte[] activate_object(Servant a_servant)
                       throws ServantAlreadyActive,
                              WrongPolicy
Generate the Object Id for the given servant and add the servant to the Active Object Map using this Id a a key. If the servant activator is set, its incarnate method will be called. In this case, the passed servant in this method can be null; in this case, the servant, returned by ServantActivatorOperations.incarnate(byte[], org.omg.PortableServer.POA) will be used.

Parameters:
a_servant - a servant that would serve the object with the returned Object Id.
Returns:
the generated objert Id for the given servant.
Throws:
ServantAlreadyActive - if this servant is already in the Active Object Map and the UNIQUE_ID policy applies.
WrongPolicy - if the required policies SYSTEM_ID and RETAIN do not apply to this POA.

activate_object_with_id

void activate_object_with_id(byte[] an_Object_Id,
                             Servant a_servant)
                             throws ServantAlreadyActive,
                                    ObjectAlreadyActive,
                                    WrongPolicy
Add the given servant to the Active Object Map as a servant for the object with the provided Object Id. If the servant activator is set, its incarnate method will be called. In this case, the passed servant in this method can be null; in this case, the servant, returned by ServantActivatorOperations.incarnate(byte[], org.omg.PortableServer.POA) will be used.

Parameters:
an_Object_Id - an object id for the given object.
a_servant - a servant that will serve the object with the given Object Id.
Throws:
ObjectAlreadyActive - if the given object id is already in the Active Object Map.
WrongPolicy - if the required RETAIN policy does not apply to this POA.
BAD_PARAM - if the passed object id is invalid due any reason.
ServantAlreadyActive

deactivate_object

void deactivate_object(byte[] the_Object_Id)
                       throws ObjectNotActive,
                              WrongPolicy

Deactivate object with the given id. Client, trying to call method on the deactivated object will either receive the remote exception (OBJECT_NOT_EXIST, minor 0x535503ec), incomplete) or the object will be reactivated and serve the request. The object can be reactivated only if the implicit activation policy applies and the servant activator is set.

The deactivated object will continue to process requests that arrived before decativation. If this POA has the associated servant manager, a ServantActivatorOperations.etherealize(byte[], org.omg.PortableServer.POA, org.omg.PortableServer.Servant, boolean, boolean) is immediately invoked on the passed id. The deactivated object can be reactivated by activate_object_with_id(byte[], org.omg.PortableServer.Servant).

The deactivation will not release thread, port or memory resources, taken by that object. This is due requirement to make the object reactivation possible at any time. To release the resources, you must destroy the POA.

Throws:
WrongPolicy - if the required RETAIN policy does not apply to this POA.
ObjectNotActive

create_reference

Object create_reference(String a_repository_id)
                        throws WrongPolicy
Create the object reference, encapsulating the given repository Id and the Object Id, generated by this POA. The returned object will not be activated by default and may be activated on the first invocation by the servant manager (if it is set and if policies are applicable). The returned object can also be narrowed by helper and used locally. In this case, the servant will be activated on the first local call of any method. The methods on returned object can also be invoked by name, using Request.

Parameters:
a_repository_id - the repository id for the given object. When narrowing the returned object with some helper, it will be checked for equality with value, returned by the the helper id().
Throws:
WrongPolicy - if the required SYSTEM_ID policy does not apply to this POA.

create_reference_with_id

Object create_reference_with_id(byte[] an_object_id,
                                String a_repository_id)

Create the object reference, encapsulating the given repository Id and the given Object Id. The returned object will not be activated by default and may be activated on the first invocation by the servant manager (if it is set and if policies are applicable).

The returned object can also be narrowed by helper and used locally. In this case, the servant will be activated on the first local call of any method. The methods on returned object can also be invoked by name, using Request.

Parameters:
an_object_id - the object id for the object being created. If the POA uses the SYSTEM_ID policy, the portable application must only supply ids, generated by that POA.
a_repository_id - the repository id for the given object. When narrowing the returned object with some helper, it will be checked for equality with value, returned by the the helper id().

get_servant

Servant get_servant()
                    throws NoServant,
                           WrongPolicy
Returns a default servant for this POA.

Returns:
a servant that will be used for requests for which no servant is found in the Active Object Map.
Throws:
NoServant - if there is no default servant associated with this POA.
WrongPolicy - if the USE_DEFAULT_SERVANT policy is not active.

set_servant

void set_servant(Servant a_servant)
                 throws WrongPolicy
Sets the default servant for this POA.

Parameters:
a_servant - a servant that will be used for requests for which no servant is found in the Active Object Map.
Throws:
WrongPolicy - if the USE_DEFAULT_SERVANT policy is not active.

set_servant_manager

void set_servant_manager(ServantManager a_manager)
                         throws WrongPolicy
Set a servant manager for this POA.

Parameters:
a_manager - servant manager being set. If the RETAIN policy applies, the manager must implement a ServantActivator. If the NON_RETAIN policy applies, the manager must implement a ServantLocator.
Throws:
WrongPolicy - if the required USE_SERVANT_MANAGER policy does not apply to this POA.
OBJ_ADAPTER - minor code 4 if the passed manager does not implement the required interface (ServantActivator, ServantLocator).
BAD_INV_ORDER - minor code 6 if the method is called more than once on the same POA. The manager can be set only once.

get_servant_manager

ServantManager get_servant_manager()
                                   throws WrongPolicy
Get the servant manager, associated with this POA.

Returns:
the associated servant manager or null if it has been previously set.
Throws:
WrongPolicy - if the required USE_SERVANT_MANAGER policy does not apply to this POA.

id

byte[] id()
Get the unique Id of the POA in the process in which it is created. This Id is needed by portable interceptors. The id is unique for the life span of the POA in the process. For persistent POAs, if a POA is created in the same path with the same name as another POA, these POAs are identical have the same id. All transient POAs are assumed unique.


id_to_reference

Object id_to_reference(byte[] the_Object_Id)
                       throws ObjectNotActive,
                              WrongPolicy
Returns the reference to the active object with the given Id.

Parameters:
the_Object_Id - the object id.
Throws:
ObjectNotActive - if there is no active object with such Id.
WrongPolicy - if the required RETAIN policy does not apply to this POA.

id_to_servant

Servant id_to_servant(byte[] the_Object_Id)
                      throws ObjectNotActive,
                             WrongPolicy
Returns the servant that serves the active object with the given Id.

Parameters:
the_Object_Id - the object id.
Throws:
ObjectNotActive - if there is no active object with such Id.
WrongPolicy - This method requires either RETAIN or USE_DEFAULT_SERVANT policies and reaises the WrongPolicy if none of them apply to this POA.

reference_to_id

byte[] reference_to_id(Object the_Object)
                       throws WrongAdapter,
                              WrongPolicy
Returns the Object Id, encapsulated in the given object reference.

Parameters:
the_Object - the object that has been previously created with this POA. It need not be active.
Throws:
WrongAdapter - if the passed object has not been previously created with this POA.
WrongPolicy - never (declared for the future extensions only).

reference_to_servant

Servant reference_to_servant(Object the_Object)
                             throws ObjectNotActive,
                                    WrongPolicy,
                                    WrongAdapter
Returns the servant that is serving this object.

Returns:
if the RETAIN policy applies and the object is in the Active Object Map, the method returns the servant, associated with this object. Otherwise, if the USE_DEFAULT_SERVANT policy applies, the method returns the default servant (if one was set).
Throws:
ObjectNotActive - if none of the conditions above are satisfied.
WrongAdapter - if the object reference was not created with this POA.
WrongPolicy - This method requires either RETAIN or USE_DEFAULT_SERVANT policies and reaises the WrongPolicy if none of them apply to this POA.

servant_to_id

byte[] servant_to_id(Servant the_Servant)
                     throws ServantNotActive,
                            WrongPolicy
Returns the id of the object, served by the given servant. The id is found in one of the following ways.

Throws:
ServantNotActive - in all cases, not listed in the list above.
WrongPolicy - The method requres USE_DEFAULT_SERVANT policy or a combination of the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies and throws the WrongPolicy if these conditions are not satisfied.

servant_to_reference

Object servant_to_reference(Servant the_Servant)
                            throws ServantNotActive,
                                   WrongPolicy

Converts the given servant to the object reference. The servant will serve all methods, invoked on the returned object. The returned object reference can be passed to the remote client, enabling remote invocations.

If the specified servant already serves some active object, that object is returned. Otherwise, if the POA has the IMPLICIT_ACTIVATION policy the method activates the servant, creating an new object with the POA-generated Object Id. In this case, if the servant activator is set, the ServantActivatorOperations.incarnate(byte[], org.omg.PortableServer.POA) method will be called.

Returns:
the object, exposing the given servant in the context of this POA.
Throws:
ServantNotActive - if the servant is inactive and no IMPLICIT_ACTIVATION policy applies.
WrongPolicy - This method needs the RETAIN policy and either the UNIQUE_ID or IMPLICIT_ACTIVATION policies.

the_POAManager

POAManager the_POAManager()
Return the POA manager, associated with this POA.

Returns:
the associated POA manager (always available).

the_activator

AdapterActivator the_activator()
Returns the adapter activator, associated with this POA. The newly created POA has no activator (null would be returned). The ORB root POA also initially has no activator.

Returns:
tha adapter activator or null if this POA has no associated adapter activator.

the_activator

void the_activator(AdapterActivator activator)
Set the adapter activator for this POA.

Parameters:
activator - the activator being set.

the_children

POA[] the_children()
The children of this POA.

Returns:
the array of all childs for this POA.

the_name

String the_name()
Return the name of this POA.

Returns:
the name of POA, relative to its parent.

the_parent

POA the_parent()
Return the parent of this POA.

Returns:
the parent POA or null if this is a root POA.

destroy

void destroy(boolean etherealize_objects,
             boolean wait_for_completion)

Destroy this POA and all descendant POAs. The destroyed POAs can be later re-created via AdapterActivator or by invoking create_POA(java.lang.String, org.omg.PortableServer.POAManager, org.omg.CORBA.Policy[]). This differs from POAManagerOperations.deactivate(boolean, boolean) that does not allow recreation of the deactivated POAs. After deactivation, recreation is only possible if the POAs were later destroyed.

The remote invocation on the target, belonging to the POA that is currently destroyed return the remote exception (TRANSIENT, minor code 4).

Parameters:
etherealize_objects - if true, and POA has RETAIN policy, and the servant manager is available, the servant manager method ServantActivatorOperations.etherealize(byte[], org.omg.PortableServer.POA, org.omg.PortableServer.Servant, boolean, boolean) is called for each active object in the Active Object Map. This method should not try to access POA being destroyed. If destroy is called multiple times before the destruction completes, the etherialization should be invoked only once.
wait_for_completion - if true, the method waits till the POA being destroyed completes all current requests and etherialization. If false, the method returns immediately.

create_id_uniqueness_policy

IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue a_value)
Create the IdUniquenessPolicy policy.

Parameters:
a_value - states which one Id uniqueness policy will apply.
Returns:
the created policy.

create_implicit_activation_policy

ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue a_value)
Create the ImplicitActivationPolicy policy.

Parameters:
a_value - states which one activation policy will apply.
Returns:
the created policy.

create_lifespan_policy

LifespanPolicy create_lifespan_policy(LifespanPolicyValue a_value)
Create the LifespanPolicy policy.

Parameters:
a_value - states which one object lifespan policy will apply.
Returns:
the created policy.

create_request_processing_policy

RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue a_value)
Create the RequestProcessingPolicy policy.

Parameters:
a_value - states which one request processing policy will apply.
Returns:
the created policy.

create_servant_retention_policy

ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue a_value)
Create the ServantRetentionPolicy policy.

Parameters:
a_value - states which one servant retention policy will apply.
Returns:
the created policy.

create_thread_policy

ThreadPolicy create_thread_policy(ThreadPolicyValue a_value)
Create the ThreadPolicy policy.

Parameters:
a_value - states which one thread policy will apply.
Returns:
the created policy.

create_id_assignment_policy

IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue value)
Create the ID assignment policy with the given value.

Parameters:
value - states which one ID assignment policy will apply.
Returns:
the created policy.