21.5.1 Overview

In some cases, a portable ORB service implementation may need to add information describing the server’s or object’s ORB service related capabilities to object references in order to enable the ORB service implementation in the client to function properly.

This is supported through the IORInterceptor and IORInfo interfaces.

The IOR Interceptor is used to establish tagged components in the profiles within an IOR.

21.5.2 An Abstract Model for Object Adapters

Using the IORInterceptor to support the object reference template imposes certain requirements on Object Adapters. While the POA is the only (current) standard object adapter, it is deemed inappropriate to impose the POA architecture on all possible proprietary object adapters. Consequently only the abstract properties that are required, and how these map to the particular case of the POA, are presented here.

Object Adapters have the following requirements:

• They have a unique name so that different instances of a particular object adapter may be identified.

• Object adapters typically have some kind of request processing state to indicate whether the adapter is currently accepting, rejecting, or performing some other kind of action on incoming requests. There is some representation of adapter instance state so that a server activation framework built on the object reference template can correctly process requests as the adapter instances states change.

• If an object adapter supports large numbers of adapter instances, reporting state changes that affect a number of adapter instances simultaneously could be expensive in the amount of data required. The POA has the concept of an adapter manager (the POAManager) that controls the state of a number of POA instances. They must have an abstract adapter manager that can be used for reporting relevant state changes.

21.5.2.1 Adapter Names

If an Object Adapter supports multiple adapter instances, there is a need for some kind of adapter name to distinguish the instances. For this purpose, an adapter name is defined as a sequence of strings. Several interpretations of an adapter name are possible:

• If the Object Adapter supports only a single instance, a fixed name can be used.

• If the namespace for an Object Adapter is flat, sequences of length 1 can be used.

• If the namespace is hierarchical (e.g., the POA), a more complex name sequence can be used.

In the case of the POA, the adapter name shall be the sequence of names starting with the root POA that is required to reach the POA using the find_POA call. The name of the root POA is the sequence containing only the string “RootPOA?.

21.5.2.2 Adapter States

Object adapters may be in one of several states that describe how the adapter behaves when a new request is dispatched to the adapter: In the case of the POA, HOLDING, ACTIVE, DISCARDING, and INACTIVE map to the same named states of the POAManager. NON_EXISTENT does not map directly to a particular POAManager state, but is used to indicate that a POA has been destroyed. A POA whose state is INACTIVE will transition to state NON_EXISTENT after the destruction process has completed.


HOLDING	The request is held off temporarily in response to a transient resource limit or a application program request. An IMR could either choose to forward the request to the server and let the server hold it off, or else to hold off the request at the IMR until the state changes.
ACTIVE	The request is dispatched to the servant and processed. An IMR should forward the request to the server in this case.

DISCARDING INACTIVE NON_EXISTENT	The request is discarded. This is indicated to the client with some kind of error. An IMR could either forward the request to the server, or else reject the request directly. The POA specification requires that a TRANSIENT/1 system exception be returned to the client in this case.

The request is discarded. The adapter is in the process of shutting down, and will eventually end up in the NON_EXISTENT state. An IMR could reject the request directly, typically with an OBJ_ADAPTER/1 error.
The adapter has been destroyed. The IMR should attempt to reactivate the server and adapter as necessary to satisfy the request. The IMR should hold off the request until the adapter becomes active again.

While non-POA adapters may have different detailed states than the POA, it should be possible to map other adapter’s states onto a subset of the above states.

21.5.2.3 Adapter Managers

Some object adapters have a concept of a group of adapters that undergo state transitions together. In such cases it is useful to capture the grouping abstractly. We define the adapter manager to represent this grouping. The only standard attribute of the adapter manager is the adapter manager id, which is an opaque id. This ID serves to distinguish different adapter manager instances, and to associate an adapter manager instance with its adapter instances. The adapter manager id is only locally significant within the ORB instance that defines the adapter manager. The id is transient, and can be compared for equality within the defining ORB instance. All adapter instances that share the same adapter manager must have the same adapter manager id.

Use of an adapter manager allows state transitions for all adapters managed by the same adapter manager to be efficiently reported. The only assumption made about the semantics of an adapter manager is that a state change reported for an adapter manager is reflected in all adapter instances managed by the adapter manager.

In the case of the POA, the POAManager is an adapter manager.

21.5.2.4 Adapter State Changes

Some adapters may support mechanisms independent of the adapter manager for changing states. In such cases, a means needs to be provided for reporting the state changes.

In the case of the POA, a subtree of POAs may all transition to the NON_EXISTENT state as a result of the POA::destroy call.

21.5.3 Object Reference Template

21.5.3.1 Definition

The Object Reference Template is defined in IDL as an abstract valuetype.

An object reference template is associated with an object adapter. Typically the template is created when the object adapter is created, used within the adapter to create object references, and destroyed when the adapter is destroyed. Different adapters may support very different styles of object creation.

The object reference template is defined as follows:

module PortableInterceptor { typedef string ServerId ; typedef string ORBId ; typedef CORBA::StringSeq AdapterName ; typedef CORBA::OctetSeq ObjectId ;

abstract valuetype ObjectReferenceFactory { Object make_object( in string repositoryId, in ObjectId id ) ; };

abstract valuetype ObjectReferenceTemplate : ObjectReferenceFactory { readonly attribute ServerId server_id ; readonly attribute ORBId orb_id ; readonly attribute AdapterName adapter_name;

};

typedef sequence<ObjectReferenceTemplate> ObjectReferenceTemplateSeq; };

The ObjectReferenceFactory valuetype provides the capability to create new object references, while the ObjectReferenceTemplate valuetype extends the factory capability with the identity of the template. This division is convenient because the current_factory attribute in IORInfo (see Section 21.5.5, “IORInfo Interface,? on page 21-46) only requires the capability to create an object reference, while the adapter_template attribute (also in Section 21.5.5) also requires identity information.

Concrete definitions and implementations of ObjectReferenceTemplate and ObjectReferenceFactory are ORB implementation specific and are not defined as they are not expected to be exchanged between ORB implementations.

21.5.3.2 The ObjectReferenceFactory abstract valuetype

The ObjectReferenceFactory provides only the capability to create an object reference. Note that a factory is immutable: after it has been created, it cannot be modified.

Also, note that it is possible to create a concrete valuetype (unknown to the ORB implementation) that subclasses the ObjectReferenceFactory valuetype, and to use this factory in the IOR interceptor as current_factory (see Section 21.5.5.7, “current_factory,? on page 21-48). In such cases, the implementation must either be immutable after it is created, or the implementation must not change the behavior of make_object. Failure to observe this requirement may result in undefined behavior.

21.5.3.3 make_object

make_object creates an Object Reference from this factory using the given repository ID and object ID. All Object References created from the same factory share the same profiles and tagged components in their profiles. They may also share some of the data in their object keys, but this is not required.

21.5.3.4 The ObjectReferenceTemplate abstract valuetype

The ObjectReferenceTemplate extends the ObjectReferenceFactory with the identity of the object adapter. Note that the template, like the factory, is immutable: after it has been created, it cannot be modified.

21.5.3.5 server_id

The value of the server_id attribute is the value that was passed into the ORB::init call (see Section 4.5.1.1, “Server ID,? on page 4-27) using the -ORBServerId argument when the ORB was created.

21.5.3.6 orb_id

The value of the orb_id attribute is the value that was passed into the ORB::init call.

In Java, this is accomplished using the -ORBid argument in the ORB.init call that created the ORB containing the object adapter that created this template. What happens if the same ORBid is used on multiple ORB::init calls in the same server is currently undefined.

21.5.3.7 adapter_name

The adapter_name attribute defines a name for the object adapter that services requests for the invoked object.

21.5.1 Overview

DISCARDING

INACTIVE

NON_EXISTENT

The request is discarded. This is indicated to the client with some kind of error. An IMR could either forward the request to the server, or else reject the request directly. The POA specification requires that a TRANSIENT/1 system exception be returned to the client in this case.