Class gnuPOA

public final AOM aom

The active object map, mapping between object keys, objects and servants.

public final boolean retain_servant

True if the active object map is used by this POA. The value is moved into separate boolean value due necessity of the frequent checks.

public gnuPOA(gnuPOA a_parent,
              String a_name,
              POAManager a_manager,
              Policy[] a_policies,
              ORB_1_4 an_orb)
            throws InvalidPolicy

Create a new abstract POA.

Parameters:

a_parent - the parent of this POA.

a_name - a name for this POA.

a_manager - a manager for this POA. If null, a new gnuPOAManager will be instantiated.

a_policies - an array of policies that apply to this POA.

an_orb - an ORB for this POA.

public Policy _get_policy(int a_policy_type)
            throws BAD_PARAM

Get the policy of the given type, associated with this POA.

Specified by:

_get_policy in interface Object

Overrides:

_get_policy in interface LocalObject

Parameters:

a_policy_type - a type of the requested policy.

Returns:

a policy of the given type, applyting to this POA.

Throws:

BAD_PARAM - if the policy of this type has not been specified for this POA.

public Object _set_policy_override(Policy[] policies,
                                   SetOverrideType how)

The POAs cannot be created by this method.

Specified by:

_set_policy_override in interface Object

Overrides:

_set_policy_override in interface LocalObject

Throws:

NO_IMPLEMENT - always.

public String[] _truncatable_ids()

Required by object reference factory ops.

Specified by:

_truncatable_ids in interface ValueBase

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

Specified by:

activate_object in interface POAOperations

Parameters:

a_servant - a servant that would serve the object with the returned Object Id. If null is passed, under apporoprate policies the servant activator is invoked.

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.

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

Specified by:

activate_object_with_id in interface POAOperations

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. If null is passed, under apporoprate policies the servant activator is invoked.

Throws:

ObjectAlreadyActive - if the given object id is already in the Active Object Map.

ServantAlreadyActive - if the UNIQUE_ID policy applies and this servant is already in use.

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

BAD_PARAM - if the passed object id is invalid due any reason.

public void activate_object_with_id(byte[] an_Object_Id,
                                    Servant a_servant,
                                    boolean use_forwarding)
            throws ServantAlreadyActive,
                   ObjectAlreadyActive,
                   WrongPolicy

Same as activate_object_with_id, but permits gnuForwardRequest forwarding exception. This is used when the activation is called from the remote invocation context and we have possibility to return the forwarding message.

public final boolean applies(Object policy_value)

Check if the given policy value applies to this POA.

Parameters:

policy_value - a policy value to check. The policy values are singletons and unique between the different policies, so the policy type is not passed.

Returns:

true if the policy value applies, false otherwise.

protected void connect_to_orb(byte[] an_Object_Id,
                              Object object)

Connect the given delegate object to orb.

protected POA createPoaInstance(String child_name,
                                POAManager a_manager,
                                Policy[] policies,
                                ORB_1_4 an_orb)
            throws InvalidPolicy

Create an instance of the POA with the given features. This method is not responsible for duplicate checking or adding the returned instance to any possible table.

Parameters:

child_name - the name of the poa being created.

a_manager - the poa manager (never null).

policies - the array of policies.

an_orb - the ORB for this POA.

Returns:

the created POA.

Throws:

InvalidPolicy - for conflicting or otherwise invalid policies.|

public POA create_POA(String child_name,
                      POAManager manager,
                      Policy[] policies)
            throws AdapterAlreadyExists,
                   InvalidPolicy

Creates a new POA as a child of the target POA.

Specified by:

create_POA in interface POAOperations

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.

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:

the_children()

public IdAssignmentPolicy create_id_assignment_policy(IdAssignmentPolicyValue a_value)

Specified by:

create_id_assignment_policy in interface POAOperations

public IdUniquenessPolicy create_id_uniqueness_policy(IdUniquenessPolicyValue a_value)

Specified by:

create_id_uniqueness_policy in interface POAOperations

public ImplicitActivationPolicy create_implicit_activation_policy(ImplicitActivationPolicyValue a_value)

Specified by:

create_implicit_activation_policy in interface POAOperations

public LifespanPolicy create_lifespan_policy(LifespanPolicyValue a_value)

Specified by:

create_lifespan_policy in interface POAOperations

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

Specified by:

create_reference in interface POAOperations

Parameters:

a_repository_id - the repository id for the given object, can be null if to be requested from the servant later.

Throws:

WrongPolicy - if the required SYSTEM_ID policy does not apply to this POA.

public 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 the IMPLICIT_ACTIVATION policy applies).

Specified by:

create_reference_with_id in interface POAOperations

Parameters:

an_object_id - the object id for the object being created. If this POA uses the SYSTEM_ID policy, the portable application should only pass the ids, generated by this POA.

a_repository_id - the repository id for the object being created, can be null if this information should be later requested from the servant.

public RequestProcessingPolicy create_request_processing_policy(RequestProcessingPolicyValue a_value)

Specified by:

create_request_processing_policy in interface POAOperations

public ServantRetentionPolicy create_servant_retention_policy(ServantRetentionPolicyValue a_value)

Specified by:

create_servant_retention_policy in interface POAOperations

public ThreadPolicy create_thread_policy(ThreadPolicyValue a_value)

Specified by:

create_thread_policy in interface POAOperations

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

Deactivate object with the given id. The deactivated object will continue to process requests that arrived before decativation. If this POA has the associated servant manager, a ServantActivatorOperations.etherealize is immediately invoked on the passed id.

Specified by:

deactivate_object in interface POAOperations

Throws:

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

public 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(String,POAManager,Policy[]). This differs from PoaManagerOperations.deactivate 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).

Specified by:

destroy in interface POAOperations

Parameters:

etherealize_objects - if true, and POA has RETAIN policy, and the servant manager is available, the servant manager method ServantActivatorOperations.etherealize 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.

protected void etherealizeAll()

Etherealize all objects, associated with this POA. Invoked from the gnuPOAManager only if it is known that the servant_activator holds non-null value.

public final void excluding(Object policy_value)
            throws WrongPolicy

Check for the absence of the given policy.

Parameters:

policy_value - a policy value to check.

Throws:

WrongPolicy - if the passed policy value is applicable.

protected void finalize()
            throws Throwable

Destroy this POA if it has not been destroyed, destroys it.

Overrides:

finalize in interface Object

public AOM.Obj findIorKey(byte[] ior_key)

Parses the given key, extracts poa and object id and searches for such reference.

public AOM.Obj findKey(byte[] object_id,
                       byte[] poa_id)

Recursively searches for the given key in the POA tree.

Parameters:

Returns:

public AOM.Obj findObject(Object object)

Recursively searches for the given object in the POA tree.

public AOM.Obj findServant(Servant servant)

Recursively searches for the given servant in the POA tree.

public POA find_POA(String poa_name,
                    boolean activate_it)
            throws AdapterNonExistent

Find and optionally activate the child POA with the given name.

Specified by:

find_POA in interface POAOperations

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.

public Policy[] getPolicyArray()

Get the copy of the policy array.

public ObjectReferenceFactory getReferenceFactory()

public ObjectReferenceTemplate getReferenceTemplate()

Get the object reference template of this POA. Instantiate a singleton instance, if required.

public Servant get_servant()
            throws NoServant,
                   WrongPolicy

Returns a default servant for this POA.

Specified by:

get_servant in interface POAOperations

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.

public ServantManager get_servant_manager()
            throws WrongPolicy

Get the servant manager, associated with this POA.

Specified by:

get_servant_manager in interface POAOperations

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.

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

Specified by:

id in interface POAOperations

public byte[] idFormIor(byte[] ior_key)

Extracts the object id from the ior key.

Parameters:

ior_key -

Returns:

the encapsulated object ior key or null if this ior key either refers a different POA or encoding signature mismatch.

public Object id_to_reference(byte[] the_Object_Id)
            throws ObjectNotActive,
                   WrongPolicy

Returns the reference to the active object with the given Id.

Specified by:

id_to_reference in interface POAOperations

Parameters:

the_Object_Id - the object id.

Throws:

ObjectNotActive - if there is no active object with such Id in the scope of this POA.

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

public Servant id_to_servant(byte[] the_Object_Id)
            throws ObjectNotActive,
                   WrongPolicy

Returns the servant that serves the active object with the given Id.

Specified by:

id_to_servant in interface POAOperations

Parameters:

the_Object_Id - the object id.

Throws:

ObjectNotActive - if there is no active object with such Id or it is not currently active.

public Object make_object(String a_repository_id,
                          byte[] an_object_id)

Create the object (needed by the factory interface).

Specified by:

make_object in interface ObjectReferenceFactory

public ORB orb()

Get the ORB, where this POA is connected.

public byte[] reference_to_id(Object the_Object)
            throws WrongAdapter,
                   WrongPolicy

Returns the Object Id, encapsulated in the given object reference.

Specified by:

reference_to_id in interface POAOperations

Parameters:

the_Object - the object that has been previously created with this POA. It need not be active.

Throws:

WrongAdapter - if the passed object is not known for this POA.

WrongPolicy - never (declared for the future extensions only).

public Servant reference_to_servant(Object the_Object)
            throws ObjectNotActive,
                   WrongPolicy,
                   WrongAdapter

Returns the servant that is serving this object.

Specified by:

reference_to_servant in interface POAOperations

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.

public final void required(Object policy_value)
            throws WrongPolicy

Check for the presence of the required policy.

Parameters:

policy_value - a policy value to check.

Throws:

WrongPolicy - if the required policy value is not applicable.

public byte[] servant_to_id(Servant the_Servant)
            throws ServantNotActive,
                   WrongPolicy

Returns the id of the object, served by the given servant (assuming that the servant serves only one object). The id is found in one of the following ways.

• If the POA has both the RETAIN and the UNIQUE_ID policy and the specified servant is active, the method return the Object Id associated with that servant.
• 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 inactive, the method activates the servant using a POA-generated Object Id and the Interface Id associated with the servant, and returns that Object Id.
• If the POA has the USE_DEFAULT_SERVANT policy, the servant specified is the default servant, and the method is being invoked in the context of executing a request on the default servant, the method returns the ObjectId associated with the current invocation.

Specified by:

servant_to_id in interface POAOperations

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.

public 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 is active, it is returned. Otherwise, if the POA has the IMPLICIT_ACTIVATION policy the method activates the servant. In this case, if the servant activator is set, the ServantActivatorOperations.incarnate method will be called.

Specified by:

servant_to_reference in interface POAOperations

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.

public void setReferenceFactory(ObjectReferenceFactory factory)

public void set_servant(Servant a_servant)
            throws WrongPolicy

Sets the default servant for this POA.

Specified by:

set_servant in interface POAOperations

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.

public void set_servant_manager(ServantManager a_manager)
            throws WrongPolicy

Set a servant manager for this POA.

Specified by:

set_servant_manager in interface POAOperations

Parameters:

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). The POA, that has the RETAIN policy uses servant managers that are ServantActivators. When the POA has the NON_RETAIN policy it uses servant managers that are ServantLoacators.

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.

public POAManager the_POAManager()

Return the POA manager, associated with this POA.

Specified by:

the_POAManager in interface POAOperations

Returns:

the associated POA manager (always available).

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

Specified by:

the_activator in interface POAOperations

Returns:

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

public void the_activator(AdapterActivator an_activator)

Set the adapter activator for this POA.

Specified by:

the_activator in interface POAOperations

Parameters:

an_activator - the activator being set.

public POA[] the_children()

The children of this POA.

Specified by:

the_children in interface POAOperations

Returns:

the array of all childs for this POA.

public String the_name()

Return the name of this POA.

Specified by:

the_name in interface POAOperations

Returns:

the name of POA, relative to its parent.

public POA the_parent()

Return the parent of this POA.

Specified by:

the_parent in interface POAOperations

Returns:

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

public byte[] toIORKey(byte[] object_id)

Converts the object Id into the IOR key. IOR key must be unique in the scope of the ORB, and Ids only in the scope of POA. Hence the IOR key includes the POA identifiers.

public String toString()

Returns the representation of this POA tree.

Overrides:

toString in interface Object

protected boolean validatePolicies(Policy[] a)
            throws InvalidPolicy

Check if the policy set is valid.

public void waitWhileRunning()

Wait while at least one of the threads in this POA is actively processing one of requests.