Package org.omg.PortableServer

The Portable Object Adapter (POA) provides more control on the request processing than it is possible when connecting objects directly to the ORB.

See:
Description

Interface Summary

AdapterActivator	Adapter activators are associated with POAs and supply the the ability to create child POAs on demand.
AdapterActivatorOperations	Defines the operations, applicable to the AdapterActivator.
Current	Provides the Id of the object currently being served and POA to that this object is connected.
CurrentOperations	Provides the Id of the object currently being served and POA to that this object is connected.
ID_ASSIGNMENT_POLICY_ID	Holds an integer IdAssignmentPolicy identifier.
ID_UNIQUENESS_POLICY_ID	Holds an integer IdUniquenessPolicy identifier.
IdAssignmentPolicy	Specifies the Object Id assignment policy.
IdAssignmentPolicyOperations	Defines the operations, applicable to the IdAssignmentPolicy.
IdUniquenessPolicy	Specfies the Id uniqueness policy.
IdUniquenessPolicyOperations	Defines the operations, applicable to the IdUniquenessPolicy.
IMPLICIT_ACTIVATION_POLICY_ID	Holds an integer ImplicitActivationPolicy identifier.
ImplicitActivationPolicy	Specifies the implicit activation policy.
ImplicitActivationPolicyOperations	Defines the operations, applicable to the ImplicitActivationPolicy.
LIFESPAN_POLICY_ID	Holds an integer LifespanPolicy identifier.
LifespanPolicy	Specifies the object life span policy, if they can outlive the POA with that they were first created.
LifespanPolicyOperations	Defines the operations, applicable to the LifespanPolicy.
POA	The Portable Object Adapter (POA) provides more control on the request processing than it is possible when connecting objects directly to the ORB.
POAManager	A POA manager is associated with one or more POAs and provides means to regulate they activity.
POAManagerOperations	Defines the operations, applicable to the POAManager.
POAOperations	Defines the operations, applicable to the POA.
REQUEST_PROCESSING_POLICY_ID	Holds an integer RequestProcessingPolicy identifier.
RequestProcessingPolicy	Specifies the behaviour in the case when the requested object is not found in the Active Object Map or that map is not in use.
RequestProcessingPolicyOperations	Defines the operations, applicable to the RequestProcessingPolicy.
SERVANT_RETENTION_POLICY_ID	Holds an integer ServantRetentionPolicy identifier.
ServantActivator	The POA, that has the RETAIN policy uses servant managers that are ServantActivators.
ServantActivatorOperations	Defines the operations, applicable to the ServantActivator.
ServantLocator	When the POA has the NON_RETAIN policy it uses servant managers that are ServantLoacators.
ServantLocatorOperations	Defines the operations, applicable to the ServantLocator.
ServantManager	A servant manager is associated with POA and provide possibility to activate objects on demand.
ServantManagerOperations	This interface would define the operations, applicable to the ServantManager.
ServantRetentionPolicy	Specifies if the active servants should be retained in the Active Object Map.
ServantRetentionPolicyOperations	Defines the operations, applicable to the ServantRetentionPolicy.
THREAD_POLICY_ID	Holds an integer ThreadPolicy identifier.
ThreadPolicy	Defines the POA thread policy.
ThreadPolicyOperations	Defines the operations, applicable to the ThreadPolicy.

Class Summary

_ServantActivatorStub	This ServantActivator stub is an optional base for the servant activators.
_ServantLocatorStub	The ServantLocator stub is an optional base for the servant locators.
CurrentHelper	The helper operations for the CORBA object Current.
DynamicImplementation	This class is used for servants that support calling via server request.
ForwardRequestHelper	The helper operations for the exception ForwardRequest.
IdAssignmentPolicyValue	Specifies the Object Id assignment policy.
IdUniquenessPolicyValue	Specifies the Object Id uniqueness policy.
ImplicitActivationPolicyValue	Specifies the implicit activation policy.
LifespanPolicyValue	Specifies the object life span policy.
POAHelper	The helper operations for the CORBA object POA.
RequestProcessingPolicyValue	Specifies the behaviour in the case when the requested object is not found in the Active Object Map or that map is not in use.
Servant	The servant is responsible for handling the method invocation on the target object.
ServantActivatorHelper	The helper operations for the CORBA object ServantActivator.
ServantActivatorPOA	This ServantActivator stub is an optional base for the servant activators.
ServantLocatorHelper	The helper operations for the CORBA object ServantLocator.
ServantLocatorPOA	The ServantLocator stub is an optional base for the servant locators.
ServantRetentionPolicyValue	Specifies the servant retention policy.
ThreadPolicyValue	Defines the possible values for the POA thread policy.

Exception Summary

ForwardRequest

This exception is raised by ServantManager to indicate that the invocation target has moved to another known location.

Package org.omg.PortableServer Description

The Portable Object Adapter (POA) provides more control on the request processing than it is possible when connecting objects directly to the ORB. The POA model defines a tree structure of POAs, the root POA being connected directly to the ORB. Any branch of this tree can be temporary or permanently inactivated using POAManager. The same manager can control several branches in the POA tree. Also, any branch in this tree can have different processing options (policies).

The newly created POA is in holding state, just queuing requests. To start processing requests, it must be turned into the active state by its POAManagerOperations.activate().

The previously monolite object implementation is now divided into object (that implements Object) and servant (that implements either InvokeHandler or DynamicImplementation). Frequently each object has its own servant, but it can also be a single servant per multiple objects and also default servant for POA (see POAOperations.set_servant(org.omg.PortableServer.Servant)). Each object has its own Object Id, unique in the scope of the POA, where the object is connected. These Ids need not be different for objects belonging to different POAs, even if these POAs are connected to the same ORB. Under the USER_ID is assignment policy this Id can be a specified by user in POAOperations.activate_object_with_id(byte[], org.omg.PortableServer.Servant), encapsulating some meaningful information about the object. The Id of the object being currently served can be identified with Servant._object_id(). This approach is used in cases when it is possible to encapsulate all object-related data into the Object Id. Such system only needs one servant, one server socket and one socket port per POA that can handle thounsands of objects.

Instead of being connected directly to the ORB, objects are now connected to one of the ORBs POAs. Since JDK 1.4 the application specific implementation base is derived from the Servant, having a different name pattern (*POA.java instead of the previous _*ImplBase.java). This *POA suffix does not mean that these servants implement or are derived from POA. They are different classes that can be connected to one of the POAs, by instance, using POAOperations.servant_to_reference(org.omg.PortableServer.Servant). The implementation base also inherits an *Operations interface, containing definitions of the application specific methods. The application programmer writes a descendent of the implementation base, implementing these methods for the application - specific functionality.

The POA objects support the method invocation by name, using Request. This alternative method works without the service-specific classes that may not be available at run time.

The objects in POA can also be activated and inactivated independently. It is possible to set a listener (ServantActivator) that would register the object activations ("incarnations") and deactivations ("etherializations"). The servant need not be specifyed when creating an object. Under the IMPLICIT_ACTIVATION ImplicitActivationPolicy the ServantActivator can provide the servant in response to the first (local or remote) call of any method on the previously incative object.

The root POA is obtained by resolving the initial reference "RootPOA" for the orb. In the simpliest case the objects can be connected directly to that root POA without creating the POA tree. The policies, used by the root POA, are defined by OMG as following:

Policy type	Accepted policy
IdAssignmentPolicy	SYSTEM_ID (Ids are created by POA)
IdUniquenessPolicy	UNIQUE_ID (single object (and Id) per servant)
ImplicitActivationPolicy	IMPLICIT_ACTIVATION (if inactive, activate)
LifespanPolicy	TRANSIENT (the POA objects cannot outlive POA)
RequestProcessingPolicy	USE_ACTIVE_OBJECT_MAP_ONLY (the servant is provided during activation)
ServantRetentionPolicy	RETAIN (retain servants for subsequent invocations)
ThreadPolicy	ORB_CTRL_MODEL (single thread per request and single server socket per object)

These values are also default for the child POAs The policies are never inherited from the parent POA.

This set of policies means that each object will have a separate serving thread, separate network socket port and usually a separate servant. It is appropriate when the expected number of objects is not too large. If the expected number of objects is larger than the supportable number of threads and socket ports, the SINGLE_THREAD_MODEL ThreadPolicy is used. Then all objects in POA with this policy are served in a single thread, using the same server socket, connected to a single port. If the request processing policy is additionally set to USE_DEFAULT_SERVANT, all objects of this POA share the same (default) servant.

The operations, supported by POA are defined separately in POAOperations.

The typical POA usage scenarios

POA converts servant to the object reference

In the simpliest case, the servant implementation is connected to POA by POAOperations.servant_to_reference(org.omg.PortableServer.Servant), the returned object being a target of remote and local invocations. It may be converted into the stringified reference, registered with the naming service, used locally or, when serving or invoking local or remote method, passed as a parameter or return value having the CORBA Object type. The object obtains Id from POA and is activated due default implicit activation policy. This scenario is supported by the default policy set and is used in the most of the "hello world" examples.

Servant provides to the object reference

The servant can be connected to an ORB by Servant._this_object(org.omg.CORBA.ORB), obtaining the object reference. The overridable Servant._default_POA() specifies POA to that the servant will be connected. The default method connects to the root poa. IDL compilers frequently generate the _this(ORB) metod for servants for getting the object reference that is already narrowed to the exact object type.

Explicit activation with POA assigned ids

The objects are activated by calling the POAOperations.activate_object(org.omg.PortableServer.Servant) on the POA with the object in question. The POA allocates, assigns, and returns a unique identity value for the object. This scenario requires the SYSTEM_ID IdAssignmentPolicy.

Explicit Activation with User-assigned Ids

The POA supports an explicit activation operation, POAOperations.activate_object_with_id(byte[], org.omg.PortableServer.Servant), that associates a servant with the user-defined Object Id. This scenario requires the USER_ID IdAssignmentPolicy. The servant manager may be or may not be used.

References before activation

It may be useful to create references for objects before activating them. Such reference can be created using POAOperations.create_reference(java.lang.String) or POAOperations.create_reference_with_id(byte[], java.lang.String), both methods also requiring to give the object repository id. Such object may be later activated either by POAOperations.activate_object_with_id(byte[], org.omg.PortableServer.Servant) or automatically, if the IMPLICIT_ACTIVATION policy applies.

Multiple Ids per servant

If the MULTIPLE_ID policy applies, the servant may be activated many times. Under this policy, POAOperations.servant_to_reference(org.omg.PortableServer.Servant) and POAOperations.servant_to_id(org.omg.PortableServer.Servant) during each call create a new object and object reference for the used servant.

One servant for all objects

If the USE_DEFAULT_SERVANT policy applies, that default servant serves all objects, belonging this POA. This approach is used when there is very little data associated with each object, so little that the data can be encoded in the Object Id. Also, it may be needed when a very large number of objects is expected. If the RETAIN applies, it is possible to activate an object explicitly setting the servant other than default. If NO_RETAIN applies, the default servant will serve all known an unknown objects for that POA.

Single Servant, Many Objects and Types

Combining USER_ID, USE_DEFAULT_SERVANT and RETAIN, it is possible to create and serve objects "on the fly". The servant must determine the object type (for instance, from the value of the agreed attribute, shared by all supported types, or from the Object Id) and be able to handle the method, named in request. If the names and parameter lists of the object methods are also created "on the fly", the requests to such object can still be submitted using Request. This method is used when the created object represents some entity in the complex database.

The ServantLocator finds a servant for each call

The ServantLocator is used by POAs that combinine NON_RETAIN and USE_SERVANT_MANAGER policies. It provides a new or reused servant every time the invocation is made. The servant locator must provide a servant in response of calling ServantLocatorOperations.preinvoke(byte[], org.omg.PortableServer.POA, java.lang.String, org.omg.PortableServer.ServantLocatorPackage.CookieHolder). This method has access the the Id of the object being served and the name of the method being called. It must return the appropriate instance of the servant or throw an exception, forwarding the request to another object (usually in another server). After the invocation, a ServantLocatorOperations.postinvoke(byte[], org.omg.PortableServer.POA, java.lang.String, java.lang.Object, org.omg.PortableServer.Servant) is called. It should be not assumed that the call of preinvoke will be followed by the call of the postinvoke; in multithreaded environment these calls are not serialized in this way. If the preinvoke has to tell something this-call-specific to the postinvoke, it must use the provided cookie holder. The preinvoke/postinoke are also called to provide a servant during each local invocation on the objects, belonging to the described POA.

All these scenarios must work with the current GNU Classpath release.