| Previous | Table of Contents | Next |
Each POA object has an associated POAManager object. A POA manager may be associated with one or more POA objects. A POA manager
encapsulates the processing state of the POAs it is associated with. Using operations on the POA manager, an application can
cause requests for those POAs to be queued or discarded, and can cause the POAs to be deactivated.
Each POAManager has a unique string as its identity. The scope of the POAManager identity is the ORB, so no two POAManagers
within the same ORB can have the same identity (but POAManagers in different ORBs can). The POAManager for the Root POA has
the name "RootPOAManager".
If a POAManager is created implicitly (as part of the creation of a new POA), it is assigned a unique identity by the ORB
run time. If a POAManager is created explicitly (using the POAManagerFactory), its identity is the string passed to the factory
operation. (An empty identity string is legal.) A POAManager is destroyed implicitly, when the last of its POAs is destroyed.
POAManager is a local interface.
11.3.2.1 Processing States
A POA manager has four possible processing states; active, inactive, holding, and discarding. The processing state determines
the capabilities of the associated POAs
and the disposition of requests received by those POAs. Figure 11-3 on page 11-17
illustrates the processing states and the transitions between them. For simplicity of presentation, this specification sometimes
describes these states as POA states, referring to the POA or POAs that have been associated with a particular POA manager.
A POA manager is created in the holding state. The root POA is therefore initially in the holding state.
For simplicity in the figure and the explanation, operations that would not cause a state change are not shown. For example,
if a POA is in “active? state, it does not change state due to an activate operation. Such operations complete successfully
with no special notice.
The only exception is the inactive state: a “deactivate? operation raises an exception just the same as every other attempted
state change operation.
destroy
deactivate
discard_requests
deactivate
Figure 11-3 Processing States
Active State
When a POA manager is in the active state, the associated POAs will receive and start processing requests (assuming that appropriate
thread resources are available). Note that even in the active state, a POA may need to queue requests depending upon the ORB
implementation and resource limits. The number of requests that can be received and/or queued is an implementation limit.
If this limit is reached, the POA should return a TRANSIENT system exception, with standard minor code 1, to indicate that
the client should re-issue the request.
A user program can legally transition a POA manager from the active state to either the discarding, holding, or inactive state
by calling the discard_requests, hold_requests, or deactivate operations, respectively. The POA enters the active state through
the use of the activate operation when in the discarding or holding state.
Discarding State
When a POA manager is in the discarding state, the associated POAs will discard all incoming requests (whose processing has
not yet begun). When a request is discarded, the TRANSIENT system exception, with standard minor code 1, must be returned
to the client-side to indicate that the request should be re-issued. (Of course, an ORB may always reject a request for other
reasons and raise some other system exception.)
In addition, when a POA manager is in the discarding state, the adapter activators registered with the associated POAs will
not get called. Instead, requests that require the invocation of an adapter activator will be discarded, as described in the
previous paragraph.
The primary purpose of the discarding state is to provide an application with flow-control capabilities when it determines
that an object's implementation or POA is being flooded with requests. It is expected that the application will restore the
POA manager to the active state after correcting the problem that caused flow-control to be needed.
A POA manager can legally transition from the discarding state to either the active, holding, or inactive state by calling
the activate, hold_requests, or deactivate operations, respectively. The POA enters the discarding state through the use of
the discard_requests operation when in the active or holding state.
Holding State
When a POA manager is in the holding state, the associated POAs will queue incoming requests. The number of requests that
can be queued is an implementation limit. If this limit is reached, the POAs may discard requests and return the TRANSIENT
system exception, with standard minor code 1, to the client to indicate that the client should reissue the request. (Of course,
an ORB may always reject a request for other reasons and raise some other system exception.)
In addition, when a POA manager is in the holding state, the adapter activators registered with the associated POAs will not
get called. Instead, requests that require the invocation of an adapter activator will be queued, as described in the previous
paragraph.
A POA manager can legally transition from the holding state to either the active, discarding, or inactive state by calling
the activate, discard_requests, or deactivate operations, respectively. The POA enters the holding state through the use
of the hold_requests operation when in the active or discarding state. A POA manager is created in the holding state.
Inactive State
The inactive state is entered when the associated POAs are to be shut down. Unlike the discarding state, the inactive state
is not a temporary state. When a POA manager is in the inactive state, the associated POAs will reject new requests. The rejection
mechanism used is specific to the vendor. The GIOP location forwarding mechanism and CloseConnection message are examples
of mechanisms that could be used to indicate the rejection. If the client is co-resident in the same process, the ORB could
raise the OBJ_ADAPTER system exception, with standard minor code 1, to indicate that the object implementation is unavailable.
In addition, when a POA manager is in the inactive state, the adapter activators registered with the associated POAs will
not get called. Instead, requests that require the invocation of an adapter activator will be rejected, as described in the
previous paragraph.
The inactive state is entered using the deactivate operation. It is legal to enter the inactive state from either the active,
holding, or discarding states.
If the transition into the inactive state is a result of calling deactivate with an etherealize_objects parameter of
• TRUE - the associated POAs will call etherealize for each active object associated with the POA once all currently executing requests have completed processing (if the POAs have the RETAIN and USE_SERVANT_MANAGER policies). If a servant manager has been registered for the POA, the POA will get rid of the object. If there are any queued requests that have not yet started executing, they will be treated as if they were new requests and rejected.
• FALSE - No deactivations or etherealizations will be attempted.
11.3.2.2 activate
void activate()raises (AdapterInactive);
This operation changes the state of the POA manager to active. If issued while the POA manager is in the inactive state, the
AdapterInactive exception is raised. Entering the active state enables the associated POAs to process requests.
11.3.2.3 hold_requests
void hold_requests( in boolean wait_for_completion )raises(AdapterInactive);
This operation changes the state of the POA manager to holding. If issued while the POA manager is in the inactive state,
the AdapterInactive exception is raised. Entering the holding state causes the associated POAs to queue incoming requests.
Any requests that have been queued but have not started executing will continue to be queued while in the holding state.
If the wait_for_completion parameter is FALSE, this operation returns immediately after changing the state. If the parameter
is TRUE and the current thread is not in an invocation context dispatched by some POA belonging to the same ORB as this POA,
this operation does not return until either there are no actively executing requests in any of the POAs associated with this
POA manager (that is, all requests that were started prior to the state change have completed) or the state of the POA manager
is changed to a state other than holding. If the parameter is TRUE and the current thread is in an invocation context dispatched
by some POA belonging to the same ORB as this POA the BAD_INV_ORDER system exception with standard minor code 3 is raised
and the state is not changed.
11.3.2.4 discard_requests
void discard_requests( in boolean wait_for_completion ) raises (AdapterInactive);
This operation changes the state of the POA manager to discarding. If issued while the POA manager is in the inactive state,
the AdapterInactive exception is raised. Entering the discarding state causes the associated POAs to discard incoming requests.
In addition, any requests that have been queued but have not started executing are discarded. When a request is discarded,
a TRANSIENT system exception with standard minor code 1 is returned to the client.
If the wait_for_completion parameter is FALSE, this operation returns immediately after changing the state. If the parameter
is TRUE and the current thread is not in an invocation context dispatched by some POA belonging to the same ORB as this POA,
this operation does not return until either there are no actively executing requests in any of the POAs associated with this
POA manager (that is, all requests that were started prior to the state change have completed) or the state of the POA manager
is changed to a state other than discarding. If the parameter is TRUE and the current thread is in an invocation context dispatched
by some POA belonging to the same ORB as this POA the BAD_INV_ORDER system exception with standard minor code 3 is raised
and the state is not changed.
11.3.2.5 deactivate
void deactivate( in boolean etherealize_objects, in boolean wait_for_completion);raises (AdapterInactive);
This operation changes the state of the POA manager to inactive. This operation has no affect on the POA manager's state if
it is already in the inactive state, but may still block if wait_for_completion is TRUE and another call to deactivate on
the same POA manager is pending. Entering the inactive state causes the associated POAs to reject requests that have not begun
to be executed as well as any new requests.
After changing the state, if the etherealize_objects parameter is
• TRUE - the POA manager will cause all associated POAs that have the RETAIN and USE_SERVANT_MANAGER policies to perform the etherealize operation on the associated servant manager for all active objects.
• FALSE - the etherealize operation is not called. The purpose is to provide developers with a means to shut down POAs in a crisis (for example, unrecoverable error) situation.
If the wait_for_completion parameter is FALSE, this operation will return immediately after changing the state. If the parameter
is TRUE and the current thread is not in an invocation context dispatched by some POA belonging to the same ORB as this POA,
this operation does not return until there are no actively executing requests in any of the POAs associated with this POA
manager (that is, all requests that were started prior to the state change have completed) and, in the case of a TRUE etherealize_objects,
all invocations of etherealize have completed for POAs having the RETAIN and USE_SERVANT_MANAGER policies. If the parameter
is TRUE and the current thread is in an invocation context dispatched by some POA belonging to the same ORB as this POA the
BAD_INV_ORDER system exception with standard minor code 3 is raised and the state is not changed.
If deactivate is called multiple times before destruction is complete (because there are active requests), the etherealize_objects
parameter applies only to the first call of deactivate; subsequent calls with conflicting etherealize_objects settings will
use the value of the etherealize_objects from the first call. The wait_for_completion parameter will be handled as defined
above for each individual call (some callers may choose to block, while others may not).
11.3.2.6 get_state
enum State {HOLDING, ACTIVE, DISCARDING, INACTIVE}; State get_state();
This operation returns the state of the POA manager.
11.3.2.7 get_id
string get_id();
This operation returns the POAManager's unique identity. The id of the POAManager for the Root POA is "RootPOAManager".
11.3.3 POAManagerFactory Interface
POAManagers can be created implicitly, by passing a nil POAManager reference to the create_POA operation, or can be created
explicitly using a POAManagerFactory. Explicit creation of a POAManager permits application control of the POAManager's identity,
whereas implicit creation results in creation of a unique identity by the ORB run time. Explicit creation of a POAManager
also permits the application to assign policies to the new POAManager.
11.3.3.1 create_POAManager
exception ManagerAlreadyExists {};
POAManager create_POAManager( in string id, in CORBA::PolicyList policies ) raises(ManagerAlreadyExists, CORBA::PolicyError);
This operation creates a new POAManager with the given id. If a POAManager with the given id exists already within the ORB,
the operation raises ManagerAlreadyExists. (Note that placing a POAManager into the inactive state does not necessarily result
in destruction of the POAManager because destruction of a POAManager only occurs once the last of its POAs has been destroyed.
create_POAManager succeeds in creation of a new POAManager with the same identity as a previous POAManager only once the previous
POAManager's POAs are destroyed.)
The policies parameter permits an arbitrary number of policies to be passed; these policies can be used by an ORB implementation
to influence the POAManager's behavior in some way; for example, an ORB may choose to use this mechanism to pass configuration
information to the factory. The policies passed to create_POAManager are deep-copied during creation; modification of a policy
sequence after creation has therefore no effect on already existing POAManagers. If one or more of the policies are invalid,
create_POAManager raises CORBA::PolicyError.
The newly created POAManager is in the Holding state.
11.3.3.2 list
typedef sequence<POAManager> POAManagerSeq; POAManagerSeq list();
The list operation returns all POAManagers (whether created implicitly or explicitly) that currently exist within the ORB.
11.3.3.3 find
POAManager find(in string id);
The find operation return the POAManager with the specified id. If no such POAManager exists, find returns a nil reference.