VisiBroker for C++ API Reference Guide : Portable Interceptor interfaces and classes for C++

Portable Interceptor interfaces and classes for C++
This section describes the VisiBroker implementation of Portable Interceptors interfaces and classes as defined by the OMG Specification. For a complete description of these interfaces and classes, refer to OMG Final Adopted Specification, ptc/2001-04-03, Portable Interceptors.
Note
See “Using Portable Interceptors” in the VisiBroker C++ Developer's Guide before using these interfaces.
About Interceptors
The VisiBroker ORB provides a set of APIs known as interceptors which provide a way to plug in additional VisiBroker ORB behavior such as support for transactions and security. Interceptors are hooked into the VisiBroker ORB through which VisiBroker ORB services can intercept the normal flow of execution of the VisiBroker ORB. The following table lists the types of interceptor that VisiBroker supports.
For more information about using portable interceptors, see “Using Portable Interceptors” in the VisiBroker C++ Developer's Guide.
For more information about using interceptors, go to “VisiBroker Interceptor and object wrapper interfaces and classes for C++”, and the VisiBroker for C++ Developer's Guide, “Using Portable Interceptors” section for more information.
The following table lists the two types of portable interceptor.
For more information about using portable interceptors, see “Using Portable Interceptors” in the VisiBroker for C++ Developer's Guide.
ClientRequestInfo
class PortableInterceptor::ClientRequestInfo : public virtual RequestInfo
This class is derived from RequestInfo. It is passed to the client side interceptors point.
Some methods on ClientRequestInfo are not valid at all interception points. The following table shows the validity of each attribute or method. If an attribute is not valid, attempting to access it results in a BAD_INV_ORDER being raised with a standard minor code of 14.
1 When ClientRequestInfo is passed to send_request(), there is an entry in the list for every argument, whether in, inout, or out. But only the in and inout arguments will be available.
2 If the reply_status() does not return LOCATION_FORWARD, accessing this attribute raises BAD_INV_ORDER with a standard minor code of 14.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
ClientRequestInfo methods
virtual CORBA::Object_ptr target() = 0;
This method returns the object which the client called to perform the operation. See effective_target() below.
virtual CORBA::Object_ptr effective_target() = 0;
This method returns the actual object on which the operation will be invoked. If the reply_status() returns LOCATION_FORWARD, then on subsequent requests, effective_target() will contain the forwarded IOR, while target will remain unchanged.
virtual IOP::TaggedProfile* effective_profile() = 0;
This method returns the profile, in the form of IOP::TaggedProfile, that will be used to send the request. If a location forward has occurred for this operation's object and that object's profile changed accordingly, then this profile will be that located profile.
virtual CORBA::Any* received_exception() = 0;
This method returns the data, in the form of CORBA::Any, that contains the exception to be returned to the client.
If the exception is a user exception which cannot be inserted into a CORBA::Any (for example, it is unknown or the bindings don't provide the TypeCode), then this attribute will be a CORBA::Any containing the system exception UNKNOWN with a standard minor code of 1. However, the RepositoryId of the exception is available in the received_exception_id attribute.
virtual char* received_exception_id() = 0;
This method returns the ID of the received_exception to be returned to the client.
virtual IOP::TaggedComponent* get_effective_component(CORBA::ULong _id) = 0;
This methods returns the IOP::TaggedComponent with the given ID from the profile selected for this request.
If there is more than one component for a given component ID, it is undefined which component this operation returns. If there is more than one component for a given component ID, get_effective_components() will be called instead.
If no component exists for the given component ID, this operation will raise BAD_PARAM with a standard minor code of 28.
virtual IOP::TaggedComponentSeq* get_effective_components(
CORBA::ULong _id) = 0;
This method returns all the tagged components with the given ID from the profile selected for this request. This sequence is in the form of an IOP::TaggedComponentSeq.
If no component exists for the given component ID, this operation will raise BAD_PARAM with a standard minor code of 28.
virtual CORBA::Policy_ptr get_request_policy(CORBA::ULong _type) = 0;
This method returns the given policy in effect for this operation.
If the policy type is not valid, either because the specified type is not supported by this ORB or because a policy object of that type is not associated with this Object, INV_POLICY with a standard minor code of 2 is raised.
virtual void add_request_service_context(
const IOP::ServiceContext& _service_context,
CORBA::Boolean _replace) = 0;
This method allows interceptors to add service contexts to the request.
There is no declaration of the order of the service contexts. They may or may not appear in the order in which they are added.
IOP::ServiceContext to be added to the request.
Indicates the behavior of this method when a service context already exists with the given ID. If false, then BAD_INV_ORDER with a standard minor code of 15 is raised. If true, then the existing service context is replaced by the new one.
ClientRequestInterceptor
class PortableInterceptor::ClientRequestInterceptor :
public virtual Interceptor
This ClientRequestInterceptor class is used to derive user-defined client side interceptor. A ClientRequestInterceptor instance is registered with the VisiBroker ORB (go to “ORBInitializer” for more information).
Include file
Include the PortableInterceptor_c.hh file when you use this class.
ClientRequestInterceptor methods
virtual void send_request(ClientRequestInfo_ptr _ri) = 0;
This send_request() interception point allows an interceptor to query request information and modify the service context before the request is sent to the server.
This interception point may raise a system exception. If it does, no other interceptors' send_request() interception points are called. Those interceptors on the Flow Stack are popped and their receive_exception() interception points are called.
This interception point may also raise a ForwardRequest exception (go to “ForwardRequest” for more information). If an Interception raises this exception, no other interceptors' send_request methods are called. The remaining interceptors in the Flow Stack are popped and have their receive_other() interception point called.
ClientRequestInfo instance to be used by interceptor.
virtual void send_poll(ClientRequestInfo_ptr _ri) = 0;
This send_poll() interception point allows an interceptor to query information during a Time-Independent Invocation (TII) polling get reply sequence.
However, as the VisiBroker ORB does not support TII, this send_poll() interception point will never be called.
ClientRequestInfo instance to be used by interceptor.
virtual void receive_reply(ClientRequestInfo_ptr _ri) = 0;
This receive_reply() interception point allows an interceptor to query the information on a reply after it is returned from the server and before control is returned to the client.
This interception point may raise a system exception. If it does, no other interceptors' receive_reply() methods are called. The remaining interceptors in the Flow Stack will have their receive_exception() interception point called.
ClientRequestInfo instance to be used by interceptor.
virtual void receive_exception(ClientRequestInfo_ptr _ri) = 0;
This receive_exception() interception point is called when an exception occurs. It allows an interceptor to query the exception's information before it is raised to the client.
This interception point may raise a system exception. This has the effect of changing the exception which successive interceptors popped from the Flow Stack receive on their calls to receive_exception(). The exception raised to the client will be the last exception raised by an interceptor, or the original exception if no interceptor changes the exception.
This interception point may also raise a ForwardRequest exception (go to “ForwardRequest” for more information). If an interceptor raises this exception, no other interceptors' receive_exception() interception points are called. The remaining interceptors in the Flow Stack are popped and have their receive_other() interception point called.
ClientRequestInfo instance to be used by interceptor.
virtual void receive_other(ClientRequestInfo_ptr _ri) = 0;
This receive_other() interception point allows an interceptor to query the information available when a request results in something other than a normal reply or an exception. For example, a request could result in a retry (for example, a GIOP Reply with a LOCATION_FORWARD status was received), or on asynchronous calls, the reply does not immediately follow the request, but control will return to the client and an ending interception point will be called.
For retries, depending on the policies in effect, a new request may or may not follow when a retry has been indicated. If a new request does follow, while this request is a new request, with respect to interceptors, there is one point of correlation between the original request and the retry: because control has not returned to the client, the request scoped PortableInterceptor::Current for both the original request and the retrying request is the same (go to “Current” for more information).
This interception point may raise a system exception. If it does, no other interceptors' receive_other() interception points are called. The remaining interceptors in the Flow Stack are popped and have their receive_exception() interception point called.
This interception point may also raise a ForwardRequest exception (go to “ForwardRequest” for more information). If an interceptor raises this exception, successive interceptors' receive_other() methods are called with the new information provided by the ForwardRequest exception.
ClientRequestInfo instance to be used by interceptor.
Codec
class IOP::Codec
The formats of IOR components and service context data used by ORB services are often defined as CDR encapsulations encoding instances of IDL defined data types. Codec provides a mechanism to transfer these components between their IDL data types and their CDR encapsulation representations.
A Codec is obtained from the CodecFactory. The CodecFactory is obtained through a call to ORB::resolve_initial_references("CodecFactory").
Include file
Include the IOP_c.hh file when you use this class.
Codec Member Classes
class Codec::InvalidTypeForEncoding : public CORBA_UserException
This exception is raised by encode() or encode_value() when an invalid type is specified for the encoding.
class Codec::FormatMismatch : public CORBA_UserException
This exception is raised by decode() or decode_value() when the data in the octet sequence cannot be decoded into a CORBA::Any.
class Codec::TypeMismatch : public CORBA_UserException
This exception is raised by decode_value() when the given TypeCode does not match the given octet sequence.
Codec Methods
virtual CORBA::OctetSequence* encode(const CORBA::Any& _data) = 0;
This method converts the given data in the form of a CORBA::Any into an octet sequence based on the encoding format effective for this Codec. This octet sequence contains both the TypeCode and the data of the type.
This operation may raise InvalidTypeForEncoding.
Data, in the form of a CORBA::Any, to be encoded into an octet sequence.
virtual CORBA::Any* decode(const CORBA::OctetSequence& _data) = 0;
This method decodes the given octet sequence into a CORBA::Any object based on the encoding format effective for this Codec.
This method raises FormatMismatch if the octet sequence cannot be decoded into a CORBA::Any.
virtual CORBA::OctetSequence* encode_value(const CORBA::Any& _data) = 0;
This method converts the given CORBA::Any object into an octet sequence based on the encoding format effective for this Codec. Only the data from the CORBA::Any is encoded, not the TypeCode.
This operation may raise InvalidTypeForEncoding.
virtual CORBA::Any* decode_value(const CORBA::OctetSequence& _data,CORBA::TypeCode_ptr _tc) = 0;
This method decodes the given octet sequence into a CORBA::Any based on the given TypeCode and the encoding format effective for this Codec.
This method raises FormatMismatch if the octet sequence cannot be decoded into a CORBA::Any.
TypeCode to be used to decode the data.
CodecFactory
class IOP::CodecFactory
This class is used to obtained a Codec. The CodecFactory is obtained through a call to ORB::resolve_initial_references("CodecFactory").
Include file
Include the IOP_c.hh file when you use this class.
CodecFactory Member
class CodecFactory::UnknownEncoding : public CORBA_UserException
This exception is raised if CodecFactory cannot create a Codec. See create_codec() function below.
CodecFactory Method
virtual Codec_ptr create_codec(const Encoding& _enc) = 0;
This create_codec() method creates a Codec of the given encoding.
This method raises UnknownEncoding if this factory cannot create a Codec of the given encoding.
Current
class PortableInterceptor::Current: public virtual CORBA::Current, public virtual CORBA_Object
The Current class is merely a slot table, the slots of which are used by each service to transfer their context data between their context and the request's or reply's service context.
Each service which wishes to use Current reserves a slot or slots at initialization time (go to “virtual CORBA::ULong allocate_slot_id() = 0;” for more information) and uses those slots during the processing of requests and replies.
Before an invocation is made, Current is obtained by way of a call to ORB::resolve_initial_references("PICurrent").
From within the interception points, the data on Current that has moved from the thread scope to the request scope is available by way of the get_slot() method on the RequestInfo object. A Current can still be obtained by way of resolve_initial_references(), but that is the interceptor's thread scope Current.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
Current Methods
virtual CORBA::Any* get_slot(CORBA::ULong _id);
A service can get the slot data it sets in PICurrent by way of the get_slot() method. The data is in the form of a CORBA::Any object.
If the given slot has not been set, a CORBA::Any containing a type code with a TCKind value of tk_null, no value is returned.
If get_slot() is called on a slot that has not been allocated, InvalidSlot is raised.
If get_slot() is called from within an ORB initializer, BAD_INV_ORDER with a minor code of 14 is raised.
SlotId of the slot from which the data will be returned.
virtual void set_slot(CORBA::ULong _id, const CORBA::Any& _data);
A service sets data in a slot with set_slot(). The data is in the form of a CORBA::Any object.
If data already exists in that slot, it is overridden.
If set_slot() is called on a slot that has not been allocated, InvalidSlot is raised.
If set_slot() is called from within an ORB initializer (go to “ORBInitializer” for more information) BAD_INV_ORDER with a minor code of 14 is raised.
SlotId of the slot from which the data will be set.
data, in the form of a CORBA::Any object, which will be set to the identified slot.
Encoding
struct IOP::Encoding
This structure defines the encoding format of a Codec. It details the encoding format, such as CDR Encapsulation encoding, and the major and minor versions of that format.
The supported encodings are:
ENCODING_CDR_ENCAPS, version 1.0;
ENCODING_CDR_ENCAPS, version 1.1;
ENCODING_CDR_ENCAPS, version 1.2;
ENCODING_CDR_ENCAPS for all future versions of GIOP as they arise.
Include file
Include the IOP_c.hh file when you use this struct.
Members
CORBA::Short format;
This member holds the encoding format for a Codec.
CORBA::Octet major_version;
This member holds the major version number for a Codec.
CORBA::Octet minor_version;
This member holds minor version number for a Codec.
ExceptionList
class Dynamic::ExceptionList
Use this class to hold exceptions information returned from the method exceptions() in the class RequestInfo. It is an implementation of variable-length array of type CORBA::TypeCode. The length of ExceptionList is available at run time.
For more information, go to “virtual Dynamic::ExceptionList* exceptions() = 0;”.
Include file
Include the Dynamic_c.hh file when you use this class.
ForwardRequest
class PortableInterceptor::ForwardRequest : public CORBA_UserException
The ForwardRequest exception is the means by which an interceptor can indicate to the ORB that a retry of the request should occur with the new object given in the exception. This behavior of causing a retry only occurs if the ORB receives a ForwardRequest from an interceptor. If ForwardRequest is raised anywhere else, it is passed through the ORB as is normal for a user exception.
If an interceptor raises a ForwardRequest exception in response to a call of an interceptor, no other interceptors are called for that interception point. The remaining interceptors in the Flow Stack will have their appropriate ending interception point called: receive_other() on the client, or send_other() on the server. The reply_status() in the receive_other() or send_other() will return LOCATION_FORWARD.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
Interceptor
class PortableInterceptor::Interceptor
This is the base class from which all interceptors are derived.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
Interceptor methods
virtual char* name() = 0;
This method returns the name of the interceptor. Each interceptor may have a name which can be used to order the lists of interceptors. Only one interceptor of a given name can be registered with the VisiBroker ORB for each interceptor type. An interceptor may be anonymous, such as it has an empty string as the name attribute. Any number of anonymous interceptors may be registered with the VisiBroker ORB.
virtual void destroy() = 0;
This method is called during ORB::destroy(). When ORB::destroy() is called by an application, the VisiBroker ORB:
1
2
calls the Interceptor::destroy() method for each interceptor
3
Method invocations from within Interceptor::destroy() on object references for objects implemented on the ORB being destroyed result in undefined behavior. However, method invocations on objects implemented on VisiBroker ORB, other than the one being destroyed, are permitted. (This means that the VisiBroker ORB being destroyed is still capable of acting as a client, but not as a server.)
IORInfo
class PortableInterceptor::IORInfo
The IORInfo interface provides the server side ORB service with access to the applicable policies during IOR construction and the ability to add components. The ORB passes an instance of its implementation of this interface as a parameter to IORInterceptor::establish_components().
The table below defines the validity of each attribute or method in IORInfo in the methods defined in the IORInterceptor.
If an illegal call is made to an attribute or method in IORInfo, the BAD_INV_ORDER system exception is raised with a standard minor code value of 14.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
IORInfo Methods
virtual CORBA::Policy_ptr get_effective_policy(CORBA::ULong _type) = 0;
An ORB service implementation may determine what server side policy of a particular type is in effect for an IOR being constructed by calling the get_effective_policy() method. When the IOR being constructed is for an object implemented using a POA, all Policy objects passed to the PortableServer::POA::create_POA() call that created that POA are accessible via get_effective_policy.
If a policy for the given type is not known to the ORB, then this method will raise INV_POLICY with a standard minor code of 3.
CORBA::PolicyType specifying the type of policy to return.
virtual void add_ior_component(const IOP::TaggedComponent& _a_component) = 0;
This method is called from establish_components() to add a tagged component to the set which will be included when constructing IORs. The components in this set will be included in all profiles.
Any number of components may exist with the same component ID.
virtual void add_ior_component_to_profile(const IOP::TaggedComponent& _a_component, CORBA::ULong _profile_id) = 0;
This method is called from establish_components() to add a tagged component to the set which will be included when constructing IORs. The components in this set will be included in the specified profile.
Any number of components may exist with the same component ID.
If the given profile ID does not define a known profile or it is impossible to add components to that profile, BAD_PARAM is raised with a standard minor code of 29.
IOP::ProfileId of the profile to which this component will be added.
virtual CORBA::Long manager_id() = 0;
This method returns the attribute that provides an opaque handle to the manager of the adapter. This is used for reporting state changes in adapters managed by the same adapter manager.
virtual CORBA::Short state() = 0;
This method returns the current state of the adapter. This must be one of HOLDING, ACTIVE, DISCARDING, INACTIVE, NON_EXISTENT.
virtual ObjectReferenceTemplate_ptr adapter_template() = 0;
This method returns the attribute that provides a means to obtain an object reference template whenever an IOR interceptor is invoked. There is no standard way to directly create an object reference template. The value of adapter_template() returns is the template created for the adapter policies and IOR interceptor calls to add_component() and add_component_to_profile(). The value of the adapter_template() returns is never changed for the lifetime of the object adapter.
virtual ObjectReferenceFactory_ptr current_factory() = 0;
This method returns the attribute that provides access to the factory that will be used by the adapter to create object references. current_factory() initially has the same value as the adapter_template attribute, but this can be changed by setting current_factory to another factory. All object references created by the object adapter must be created by calling the make_object() method on current_factory.
virtual void current_factory(ObjectReferenceFactory_ptr _current_factory) = 0;
This method sets the current_factory attribute. The value of the current_factory attribute that is used by the adapter can only be set during the call to the components_established method.
current_factory object which is to be set.
IORInfoExt
class IORInfoExt: public PortableInterceptor::IORInfo
This is the VisiBroker extensions to Portable Interceptors to allow installing of a POA scoped Server Request Interceptor. This IORInfoExt interface is inherited from IORInfo interface and has additional methods to support POA scoped Server Request Interceptor.
Include file
Include the PortableInterceptorExt_c.hh file when you use this class.
IORInfoExt Methods
virtual void add_server_request_interceptor (
ServerRequestInterceptor_ptr _interceptor) = 0;
This method is used to add a POA-scoped server side request interceptor to a service.
virtual char* full_poa_name();
This method return the full POA name.
IORInterceptor
class PortableInterceptor::IORInterceptor : public virtual Interceptor
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.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
IORInterceptor Methods
virtual void establish_components(IORInfo_ptr _info) = 0;
A server side ORB calls the establish_components() method on all registered IORInterceptor instances when it is assembling the list of components that will be included in the profile(s) of an object reference. This method is not necessarily called for each individual object reference. In the case of the POA, these calls are made each time POA::create_POA() is called. In other adapters, these calls would typically be made when the adapter is initialized. The adapter template is not available at this stage since information (the components) needed in the adapter template is being constructed.
IORInfo instance used by the ORB service to query applicable policies and add components to be included in the generated IORs.
virtual void components_established(IORInfo_ptr _info) = 0;
After all of the establish_components() methods have been called, the components_established() methods are invoked on all registered IOR interceptors. The adapter template is available at this stage. The current_factory attribute may be get or set at this stage.
Any exception that occurs in components_established() is returned to the caller of components_established(). In the case of the POA, this causes the create_POA call to fail, and an OBJ_ADAPTER exception with a standard minor code of 6 is returned to the invoker of create_POA().
IORInfo instance used by the ORB service to access applicable policies.
virtual void adapter_manager_state_changed(CORBA::Long _id, CORBA::Short _state) = 0;
Any time the state of an adapter manager changes, the adapter_manager_state_changed() method is invoked on all registered IOR interceptors.
If a state change is reported through adapter_manager_state_changed(), it is not reported through adapter_state_changed().
IORInfo instance used by the ORB service to access applicable policies.
virtual void adapter_state_changed(const ObjectReferenceTemplateSeq& _templates, CORBA::Short _state) = 0;
Object adapter state changes are reported to this method any time the state of one or more adapters changes for reasons unrelated to adapter manager state changes. The templates argument identifies the object adapters that have changed state by the template ID information. The sequence contains the adapter templates for all object adapters that have made the state transition being reported.
ORBInitializer
class PortableInterceptor::ORBInitializer
An interceptor is registered by registering an associated ORBInitializer object which implements the ORBInitializer class. When an ORB is initializing, it calls each registered ORBInitializer, passing it an ORBInitInfo object which is used to register its interceptor.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
ORBInitializer Methods
virtual void pre_init(ORBInitInfo_ptr _info) = 0;
This method is called during ORB initialization. If it is expected that initial services registered by an interceptor will be used by other interceptors, then those initial services are registered at this point via calls to ORBInitInfo::register_initial_reference().
virtual void post_init(ORBInitInfo_ptr _info) = 0;
This method is called during ORB initialization. If a service must resolve initial references as part of its initialization, it can assume that all initial references will be available at this point.
Calling the post_init() methods is not the final task of ORB initialization. The final task, following the post_init() calls, is attaching the lists of registered interceptors to the ORB. Therefore, the ORB does not contain the interceptors during calls to post_init(). If an ORB-mediated call is made from within post_init(), no request interceptors will be invoked on that call. Likewise, if a method is performed which causes an IOR to be created, no IOR interceptors will be invoked.
ORBInitInfo
class PortableInterceptor::ORBInitInfo
This ORBInitInfo class is passed to ORBInitializer object for registering interceptors.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
ORBInitInfo Member Classes
class DuplicateName : public CORBA_UserException;
Only one interceptor of a given name can be registered with the ORB for each interceptor type. If an attempt is made to register a second interceptor with the same name, DuplicateName is raised.
An interceptor may be anonymous, such as it has an empty string as the name attribute. Any number of anonymous interceptors may be registered with the ORB, so if the interceptor being registered is anonymous, the registration operation will not raise DuplicateName.
class InvalidName: public CORBA_UserException
This exception is raised by register_initial_reference() and resolve_initial_references().
register_initial_reference() raises InvalidName if:
resolve_initial_references() raises InvalidName if the name to be resolved is invalid.
ORBInitInfo Methods
virtual CORBA::StringSequence* arguments() = 0;
This method returns the arguments passed to ORB_init(). They may or may not contain the ORB's arguments.
virtual char* orb_id() = 0;
This method returns the ID of the ORB being initialized.
virtual IOP::CodecFactory_ptr codec_factory() = 0;
This method returns the IOP::CodecFactory. The CodecFactory is normally obtained via a call to ORB::resolve_initial_references("CodecFactory"), but since the ORB is not yet available and interceptors, particularly when processing service contexts, will require a Codec, a means of obtaining a Codec is necessary during ORB initialization.
virtual void register_initial_reference(const char* _id, CORBA::Object_ptr _obj) = 0;
If this method is called with an id, "Y", and an object, YY, then a subsequent call to register_initial_reference() will return object YY.
This method is identical to ORB::register_initial_reference(). This same functionality exists here because the ORB, not yet fully initialized, is not yet available but initial references may need to be registered as part of Interceptor registration. The only difference is that the version of this method on the ORB uses PIDL (CORBA::ORB::ObjectId and CORBA::ORB::InvalidName) whereas the version in this interface uses IDL defined in this interface; the semantics are identical.
register_initial_reference() raises InvalidName if:
virtual CORBA::Object_ptr resolve_initial_references(const char* _id) = 0;
This method is only valid during post_init(). It is identical to ORB::resolve_initial_references(). This same functionality exists here because the ORB, not yet fully initialized, is not yet available but initial references may be required from the ORB as part of Interceptor registration.
If the name to be resolved is invalid, resolve_initial_references() will raise InvalidName.
virtual void add_client_request_interceptor(ClientRequestInterceptor_ptr _interceptor) = 0;
This method is used to add a client side request interceptor to the list of client side request interceptors.
If a client side request interceptor has already been registered with this interceptor's name, DuplicateName will be raised.
virtual void add_server_request_interceptor(
ServerRequestInterceptor_ptr _interceptor) = 0;
This method is used to add a server side request interceptor to the list of server side request interceptors.
If a server side request interceptor has already been registered with this interceptor's name, DuplicateName is raised.
virtual void add_ior_interceptor(IORInterceptor_ptr _interceptor) = 0;
This method is used to add an IOR interceptor to the list of IOR interceptors.
If an IOR interceptor has already been registered with this interceptor's name, DuplicateName is raised.
IORInterceptor to be added.
virtual CORBA::ULong allocate_slot_id() = 0;
returns the index to the slot which has been allocated.
A service calls allocate_slot_id to allocate a slot on PortableInterceptor::Current.
Note
While slot id's can be allocated within an ORB initializer, the slots themselves cannot be initialized. Calling set_slot() or get_slot() on the Current within an ORB initializer will raise a BAD_INV_ORDER with a minor code of 14.
virtual void register_policy_factory(CORBA::ULong _type, PolicyFactory_ptr _policy_factory) = 0;
This method registers a PolicyFactory for the given PolicyType.
If a PolicyFactory already exists for the given PolicyType, BAD_INV_ORDER is raised with a standard minor code of 16.
CORBA::PolicyType that the given PolicyFactory serves.
factory for the given CORBA::PolicyType.
Parameter
struct Dynamic::Parameter
This structure holds the parameter information. This structure is the element used in ParameterList (go to “ParameterList” for more information).
Include file
Include the Dynamic_c.hh file when you use this struct.
Members
CORBA::Any argument;
This member stores the parameter data in the form of CORBA::Any.
CORBA::ParameterMode mode;
This member specifies the mode of a parameter. Its value can be one of the enum values: PARAM_IN, PARAM_OUT or PARAM_INOUT.
ParameterList
class Dynamic::ParameterList
This class is used to pass parameters information returned from the method arguments() in the class RequestInfo. It is an implementation of variable-length array of type Parameter. The length of ParameterList is available at run-time.
For more information, go to “virtual Dynamic::ParameterList* arguments() = 0;”.
Include file
Include the Dynamic_c.hh file when you use this class.
PolicyFactory
class PortableInterface::PolicyFactory
A portable ORB service implementation registers an instance of the PolicyFactory interface during ORB initialization. The POA is required to preserve any policy which is registered with ORBInitInfo in this manner.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
PolicyFactory Method
virtual CORBA::Policy_ptr create_policy(CORBA::ULong _type, const CORBA::Any& _value) = 0;
The ORB calls create_policy() on a registered PolicyFactory instance when CORBA::ORB::create_policy() is called for the PolicyType under which the PolicyFactory has been registered. The create_policy() method then returns an instance of the appropriate interface derived from CORBA::Policy whose value corresponds to the specified CORBA::Any. If it cannot, it will raise an exception as described for CORBA::ORB::create_policy().
A CORBA::PolicyType specifying the type of policy being created.
An CORBA::Any containing data with which to construct the CORBA::Policy.
RequestInfo
class PortableInterceptor::RequestInfo
This is the base class from which ClientRequestInfo and ServerRequestInfo are derived. Each interception point is given an object through which the Interceptor can access request information. client side and server side interception points are concerned with different information, so there are two information objects: ClientRequestInfo is passed to the client side interception points and ServerRequestInfo is passed to the server side interception points. But there is information that is common to both, so they both inherit from this common interface: RequestInfo.
Include file
Include the PortableInterceptor_c.hh file when you use this class.
RequestInfo methods
virtual CORBA::ULong request_id() = 0;
This method returns the ID which uniquely identifies an active request / reply sequence. Once a request / reply sequence is concluded this ID may be reused.
Note
This ID is not the same as the GIOP request_id. If GIOP is the transport mechanism used, then these IDs may very well be the same, but this is not guaranteed nor required.
virtual char* operation() = 0;
This method returns name of the operation being invoked.
virtual Dynamic::ParameterList* arguments() = 0;
This method returns a Dynamic::ParameterList containing the arguments on the operation being invoked. If there are no arguments, this attribute will be a zero length sequence.
virtual Dynamic::ExceptionList* exceptions() = 0;
This method returns a Dynamic::ExceptionList describing the TypeCodes of the user exceptions that this operation invocation may raise. If there are no user exceptions, this attribute will be a zero length sequence.
virtual CORBA::StringSequence* contexts() = 0;
This method returns a CORBA::StringSequence describing the contexts that may be passed on this operation invocation. If there are no contexts, this attribute will be a zero length sequence.
virtual CORBA::StringSequence* operation_context() = 0;
This method returns a CORBA::StringSequence containing the contexts being sent on the request.
virtual CORBA::Any* result() = 0;
This method returns the data, in the form of CORBA::Any, that contains the result of the operation invocation. If the operation return type is void, this attribute will be a CORBA::Any containing a type code with a TCKind value of tk_void and no value.
virtual CORBA::Boolean response_expected() = 0;
This method returns a boolean value which indicates whether a response is expected.
On the client, a reply is not returned when response_expected() is false, so receive_reply() cannot be called. receive_other() is called unless an exception occurs, in which case receive_exception() is called.
virtual CORBA::Short sync_scope() = 0;
This method returns an attribute, defined in the Messaging specification, is pertinent only when response_expected() is false. If response_expected() is true, the value of sync_scope() is undefined. It defines how far the request will progress before control is returned to the client. This attribute may have one of the following values:
On the server, for all scopes a reply will be created from the return of the target operation call, but the reply will not return to the client. Although it does not return to the client, it does occur, so the normal server side interception points are followed (for example, receive_request_service_contexts(), receive_request(), send_reply() or send_exception()).
For SYNC_WITH_SERVER and SYNC_WITH_TARGET, the server does send an empty reply back to the client before the target is invoked. This reply is not intercepted by server side Interceptors.
virtual CORBA::Short reply_status() = 0;
This method returns an attribute which describes the state of the result of the operation invocation. Its value can be one of the following:
On the client:
Within the receive_reply interception point, this attribute will only be SUCCESSFUL.
Within the receive_exception interception point, this attribute will be either SYSTEM_EXCEPTION or USER_EXCEPTION.
Within the receive_other interception point, this attribute will be any of: SUCCESSFUL, LOCATION_FORWARD, or TRANSPORT_RETRY. SUCCESSFUL means an asynchronous request returned successfully. LOCATION_FORWARD means that a reply came back with LOCATION_FORWARD as its status. TRANSPORT_RETRY means that the transport mechanism indicated a retry - a GIOP reply with a status of NEEDS_ADDRESSING_MODE, for instance.
On the server:
Within the send_reply interception point, this attribute will only be SUCCESSFUL.
Within the send_exception interception point, this attribute will be either SYSTEM_EXCEPTION or USER_EXCEPTION.
Within the send_other interception point, this attribute will be any of: SUCCESSFUL, or LOCATION_FORWARD. SUCCESSFUL means an asynchronous request returned successfully. LOCATION_FORWARD means that a reply came back with LOCATION_FORWARD as its status.
virtual CORBA::Object_ptr forward_reference() = 0;
If the reply_status() returns LOCATION_FORWARD, then this method returns an object to which the request will be forwarded. It is indeterminate whether a forwarded request will actually occur.
virtual CORBA::Any* get_slot(CORBA::ULong _id) = 0;
This method returns the data, in the form of a CORBA::Any, from the given slot of the PortableInterceptor::Current that is in the scope of the request.
If the given slot has not been set, then a CORBA::Any containing a type code with a TCKind value of tk_null is returned.
If the ID does not define an allocated slot, InvalidSlot is raised.
Go to “Current” for an explanation of slots and the PortableInterceptor::Current.
SlotId of the slot which is to be returned.
virtual IOP::ServiceContext* get_request_service_context(CORBA::ULong _id) = 0;
This method returns a copy of the service context with the given ID that is associated with the request.
If the request's service context does not contain an entry for that ID, BAD_PARAM with a standard minor code of 26 is raised.
IOP::ServiceContext of the slot which is to be returned.
virtual IOP::ServiceContext* get_reply_service_context(CORBA::ULong _id) = 0;
This method returns a copy of the service context with the given ID that is associated with the reply.
If the request's service context does not contain an entry for that ID, BAD_PARAM with a standard minor code of 26 is raised.
IOP::ServiceContext of the slot which is to be returned.
ServerRequestInfo
class PortableInterceptor::ServerRequestInfo : public virtual RequestInfo
This class is derived from RequestInfo. It is passed to server side interception points.
Some methods on ServerRequestInfo are not valid at all interception points. The table below shows the validity of each attribute or method. If it is not valid, attempting to access it will result in a BAD_INV_ORDER being raised with a standard minor code of 14.
1When ServerRequestInfo is passed to receive_request(), there is an entry in the list for every argument, whether in, inout, or out. But only the in and inout arguments will be available.
2If the reply_status() does not returns LOCATION_FORWARD, accessing this attribute will raise BAD_INV_ORDER with a standard minor code of 14.
3If the servant locator caused a location forward, or raised an exception, this attribute / method may not be available in this interception point. NO_RESOURCES with a standard minor code of 1 will be raised if it is not available.
4The method is not available in this interception point because the necessary information requires access to the target object's servant, which may no longer be available to the ORB. For example, if the object's adapter is a POA that uses a ServantLocator, then the ORB invokes the interception point after it calls ServantLocator::postinvoke().
Include file
Include the PortableInterceptor_c.hh file when you use this class.
ServerRequestInfo methods
virtual CORBA::Any* sending_exception() = 0;
This method returns data, in the form CORBA::Any, that contains the exception to be returned to the client.
If the exception is a user exception which cannot be inserted into a CORBA::Any (e.g., it is unknown or the bindings don't provide the TypeCode), then this attribute will be an CORBA::Any containing the system exception UNKNOWN with a standard minor code of 1.
virtual char* server_id() = 0;
This method returns the value that was passed into the ORB::init call using the -ORBServerId argument when the ORB was created.
virtual char* orb_id() = 0;
The method returns 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.
virtual CORBA::StringSequence* adapter_name() = 0;
The method returns the name for the object adapter, in the form of CORBA::StringSequence, that services requests for the invoked object. In the case of the POA, the adapter_name is the sequence of names from the root POA to the POA that services the request. The root POA is not named in this sequence.
virtual CORBA::OctetSequence* object_id() = 0;
This method returns the opaque object_id, in the form of CORBA::OctetSequence, that describes the target of the operation invocation.
virtual CORBA::OctetSequence* adapter_id() = 0;
This method returns opaque identifier for the object adapter, in the form of CORBA::OctetSequence.
virtual char* target_most_derived_interface() = 0;
This method returns the RepositoryID for the most derived interface of the servant.
virtual CORBA::Policy_ptr get_server_policy(CORBA::ULong _type) = 0;
This method returns the policy in effect for this operation for the given policy type. The returned CORBA::Policy object will only be a policy whose type was registered via register_policy_factory().
If a policy for the given type was not registered via register_policy_factory, this method will raise INV_POLICY with a standard minor code of 3.
The CORBA::PolicyType which specifies the policy to be returned.
virtual void set_slot(CORBA::ULong _id, const CORBA::Any& _data) = 0;
This method allows an Interceptor to set a slot in the PortableInterceptor::Current that is in the scope of the request. If data already exists in that slot, it will be overwritten.
If the ID does not define an allocated slot, InvalidSlot is raised.
Go to “Current” for an explanation of slots and PortableInterceptor::Current.
The SlotId of the slot.
The data, in the form of a CORBA::Any, to store in that slot.
virtual CORBA::Boolean target_is_a(const char* _id) = 0;
This method returns true if the servant is the given RepositoryId, false if it is not.
virtual void add_reply_service_context(const IOP::ServiceContext& _service_context,CORBA::Boolean _replace) = 0;
This method allows Interceptors to add service contexts to the request.
There is no declaration of the order of the service contexts. They may or may not appear in the order that they are added.
The IOP::ServiceContext to add to the reply.
Indicates the behavior of this method when a service context already exists with the given ID. If false, then BAD_INV_ORDER with a standard minor code of 15 is raised. If true, then the existing service context is replaced by the new one.
ServerRequestInterceptor
class PortableInterceptor::ServerRequestInterceptor :
public virtual Interceptor
This ServerRequestInterceptor class is used to derive user-defined server side interceptor. A ServerRequestInterceptor instance is registered with the ORB (go to “ORBInitializer” for more information).
Include file
Include the PortableInterceptor_c.hh file when you use this class.
ServerRequestInterceptor methods
virtual void receive_request_service_contexts(
ServerRequestInfo_ptr _ri) = 0;
At this receive_request_service_contexts() interception point, Interceptors must get their service context information from the incoming request and transfer it to PortableInterceptor::Current's slots.
This interception point is called before the servant manager is called. Operation parameters are not yet available at this point. This interception point may or may not execute in the same thread as the target invocation.
This interception point may raise a system exception. If it does, no other Interceptors' receive_request_service_contexts() interception points are called. Those Interceptors on the Flow Stack are popped and their send_exception() interception points are called.
This interception point may also raise a ForwardRequest exception (go to “ForwardRequest” for more information). If an Interceptor raises this exception, no other Interceptors' receive_request_service_contexts() methods are called. Those Interceptors on the Flow Stack are popped and their send_other interception points are called.
This is the ServerRequestInfo instance to be used by Interceptor.
virtual void receive_request(ServerRequestInfo_ptr _ri) = 0;
This receive_request() interception point allows an Interceptor to query request information after all the information, including method parameters, are available. This interception point will execute in the same thread as the target invocation.
In the DSI model, since the parameters are first available when the user code calls arguments(), receive_request() is called from within arguments(). It is possible that arguments() is not called in the DSI model. The target may call set_exception() before calling arguments(). The ORB will guarantee that receive_request() is called once, either through arguments() or through set_exception(). If it is called through set_exception(), requesting the arguments() will result in NO_RESOURCES being raised with a standard minor code of 1.
This interception point may raise a system exception. If it does, no other Interceptors' receive_request() methods are called. Those Interceptors on the Flow Stack are popped and their send_exception interception points are called.
This interception point may also raise a ForwardRequest exception (go to “ForwardRequest” for more information). If an Interceptor raises this exception, no other Interceptors' receive_request() methods are called. Those Interceptors on the Flow Stack are popped and their send_other() interception points are called.
This is the ServerRequestInfo instance to be used by Interceptor.
virtual void send_reply(ServerRequestInfo_ptr _ri) = 0;
This send_reply() interception point allows an Interceptor to query reply information and modify the reply service context after the target operation has been invoked and before the reply is returned to the client. This interception point will execute in the same thread as the target invocation.
This interception point may raise a system exception. If it does, no other Interceptors' send_reply() interception points are called. The remaining Interceptors in the Flow Stack will have their send_exception() interception point called.
This is the ServerRequestInfo instance to be used by Interceptor.
virtual void send_exception(ServerRequestInfo_ptr _ri) = 0;
This send_exception() interception point is called when an exception occurs. It allows an Interceptor to query the exception information and modify the reply service context before the exception is raised to the client. This interception point will execute in the same thread as the target invocation.
This interception point may raise a system exception. This has the effect of changing the exception which successive Interceptors popped from the Flow Stack receive on their calls to send_exception. The exception raised to the client will be the last exception raised by an Interceptor, or the original exception if no Interceptor changes the exception.
This interception point may also raise a ForwardRequest exception (go to “ForwardRequest” for more information). If an Interceptor raises this exception, no other Interceptors' send_exception() interception points are called. The remaining Interceptors in the Flow Stack will have their send_other interception points called.
virtual void send_other(ServerRequestInfo_ptr _ri) = 0;
This send_other() interception point allows an Interceptor to query the information available when a request results in something other than a normal reply or an exception. For example, a request could result in a retry (e.g., a GIOP Reply with a LOCATION_FORWARD status was received). This interception point will execute in the same thread as the target invocation.
This interception point may raise a system exception. If it does, no other Interceptors' send_other() methods are called. The remaining Interceptors in the Flow Stack will have their send_exception interception points called.
This interception point may also raise a ForwardRequest exception.