VisiBroker Interceptor and object wrapper interfaces and classes for C++

This section describes the interfaces and classes that you can use with VisiBroker interceptors and object wrappers.

For more information, see “Using VisiBroker Interceptors” and “Using Object Wrappers” in the VisiBroker for C++ Developer's Guide.

Introduction

Similar to Portable Interceptors, VisiBroker interceptors offer the VisiBroker ORB services a mechanism to intercept normal flow of execution of the ORB. The table below lists the three forms of VisiBroker interceptor.

Interceptor Type	Description
Client Interceptor	System level interceptors which can be used to hook ORB services such as transactions and security into the client ORB processing.
Server Interceptor	System level interceptors which can be used to hook ORB services such as transactions and security into the server ORB processing.
Object Wrappers	User level interceptors which provide a simple mechanism for users to intercept calls to stubs and skeletons. These allow for simple tracing and data caching among other things.

InterceptorManagers

Interceptors are installed and managed via interceptor managers. The InterceptorManager interface is the generic interceptor manager from which all interceptor-specific managers inherit. An InterceptorManager type is associated with each interceptor type. An InterceptorManager holds a list or chain of a particular kind of interceptors, all of which have the same scope and need to start at the same time. Therefore, global interceptors, such as POALifeCycle and Bind have global InterceptorManagers while scoped interceptors, per-POA and per-object, have an InterceptorManager for each scope. Each scope, either global, POAs, or objects, may hold multiple types of interceptors. You get the right kind of manager for a particular interceptor from an InterceptorManagerControl.

Global interceptors may be handed additional interceptor managers to install localized interceptors, for example, per-POA interceptors use the POAInterceptorManager.

To obtain an instance of the global interceptor manager, InterceptorManager, call ORB.resolve_initial_references and pass the String InterceptorManager as an argument. This value is only available when the ORB is in administrative mode, that is, during ORB initialization. It can only be used to install global interceptors such as, POALifeCycle interceptors or Bind interceptors.

The POA interceptor manager is a per-POA manager and is only available to POALifeCycleInterceptors during their create call. POALifeCycleInterceptors may set up all other server side interceptors during the call to create. The Bind Interceptor Manager is a per-object manager and is only available to Bind interceptors during their bind_succeeded( ) call. Bind interceptors may set up ClientRequest interceptors during the bind_succeeded call.

IOR templates

In addition to the interceptor, the Interoperable Object Reference (IOR) template may be modified directly on the POAIntercptorManager interface during the call to POALifeCycleInterceptor::create( ). The IOR template is a full IOR value with the type_id not set, and all GIOP::ProfileBodyValueshave incomplete object keys. The POA sets the type_id and fills in the object keys of the template before calling the IORCreationInterceptors.

InterceptorManager

class Interceptor::InterceptorManager

This is the base class from which all interceptor managers are derived. Interceptor managers are interfaces which are used to manage the installation and removal of interceptors from the system.

InterceptorManagerControl

class Interceptor::InterceptorManagerControl public CORBA::PseudoObject

This is the class that is responsible for controlling a set of related interceptor managers. It holds all available managers identified by a string that corresponds to the type of interceptors to be managed. There is one InterceptorManagerControl per scope.

Include file

Include the interceptor_c.hh file when you use this class.

InterceptorManagerInterceptor method

InterceptorManager_ptr get_manager(const char name);

This method returns an instance of the InterceptorManager which returns a string identifying the manager.

Parameter	Description
name	The name of the interceptor.

BindInterceptor

class Interceptor::BindInterceptor public VISPseudoInterface

You can use this class to derive your own interceptor for handling bind and rebind events for a client or server application. The Bind Interceptors are global interceptors invoked on the client side before and after binds.

If an exception is thrown during a bind, the remaining interceptors in the chain are not called and the chain is truncated to only those interceptors already called. Exceptions thrown during bind_succeeded or bind_failed are ignored.

Include file

You should include the interceptor_c.hh file when you use this class.

BindInterceptor methods

virtual IOP::IORValue_ptr bind(IOP::IORValue_ptr ior, CORBA::Object_ptr obj, CORBA::Boolean rebind, VISClosure& closure);

This method is called during all ORB bind operations.

Parameter	Description
ior	The Interoperable Object Reference (IOR) for the server object to which the client is binding.
obj	The client object which is being bound to the server. The object will not be properly initialized at this time, so do not attempt an operation on it. However, it may be stored in a data structure and used after the bind has completed.
rebind	An attempt to rebind to the server. After a bind( ) has failed, depending on the current quality of service, a rebind may be attempted.
closure	A new closure object for the bind operation. The closure will be used in corresponding calls to either bind_failure or bind_succeeded.
return	Returns a new IOR, if the bind operation is to be continued using this new IOR. Otherwise, it returns a null value and the bind will proceed using the original IOR. Returning the same IOR as the parameter passed in is incorrect and generates an exception at bind time.

virtual IOP::IORValue_ptr bind_failed(IOP::IORValue_ptr ior, CORBA::Object_ptr obj, VISClosure& closure);

This method is called if a bind operation failed.

Parameter	Description
ior	The IOR of the server object on which the bind operation failed.
obj	The client object which is being bound to the server.
closure	The closure object previously given in the bind call.
return	Returns a new IOR if a rebind is to be attempted against this IOR. Otherwise, it returns null, and a rebind is not attempted.

virtual void bind_succeeded(IOP::IORValue_ptr ior, CORBA::Object_ptr obj, CORBA::Long profileIndex, InterceptorManagerControl_ptr interceptorControl, VISClosure& closure);

This method is called if a bind operation succeeded.

Parameter	Description
ior	The IOR of the server object on which the bind operation succeeded.
obj	The client object which is being bound to the server.
profileIndex	Identifies the connection protocol.
interceptorControl	This Manager provides a list of the types of Managers.
closure	The closure object previously given in the bind call.

BindInterceptorManager

class Interceptor::BindInterceptorManager public InterceptorManager, public VISPseudoInterface

This is the class that manages all the global bind interceptors. It only has one public method, which allows you to register interceptors.

The BindInterceptorManager must always be used at ORB_init( ). It has no effect after the orb is initialized. Therefore, it only needs to be used in the context of a loader class that inherits from VISinit.

To obtain a BindInterceptorManager from the InterceptorManagerControl, use InterceptorManagerControl::get_manager( ) with the identification string Bind.

Include file

You should include the interceptor_c.hh file when you use this class.

BindInterceptorManager method

void add (BindInterceptor _ptr interceptor)

This method is used to add a BindInterceptor to the list of interceptors to be started at bind time.

ClientRequestInterceptor

class Interceptor::ClientRequestInterceptor public VISPseudoInterface

You use this class to derive your own client side interceptor. The Client Request interceptors may be installed during the bind_succeeded call of a bind interceptor and remain active for the duration of the connection. The methods defined in your derived class will be invoked by the ORB during the preparation or sending of an operation request, during the receipt of a reply message, or if an exception is raised.

Include file

Include the interceptor_c.hh file when you use this class.

ClientRequestInterceptor methods

virtual void preinvoke_premarshal (CORBA::Object_ptr target, const char* operation, IOP::ServiceContextList& service_contexts, VisClosure& closure);

This method is invoked by the ORB on every request, before the request has been marshaled. An exception thrown from this interceptor results in the request being completed immediately. In this case, the chain is shortened to only those interceptors that have already fired, the request will not be sent, and exception_occurred() is called on all interceptors still in the chain.

Parameter	Description
target	The client object which is being bound to the server.
operation	The name of the operation being invoked.
service_context	The services assigned by the ORB. These services are identified by a tag registered with the OMG.
closure	The closure object previously given in the bind call.

virtual void preinvoke_postmarshal(CORBA::Object_ptr target, CORBA_MarshallOutBuffet& payload, VISClosure& closure);

This method is invoked after every request has been marshaled, but before it was sent.

If an exception is thrown in this method:

•	the rest of the chain is not invoked,

•	the request is not sent to the server, and

•	exception_occurred() is called on the whole interceptor chain.

Parameter	Description
target	The client object which is being bound to the server.
payload	Marshalled buffer.
closure	The closure object previously given in the bind call.

virtual void postinvoke(CORBA::Object_ptr target,
const IOP::ServiceContextList& Service_contexts,
CORBA_MarshallInBuffet& payload,
CORBA::Environment_ptr env, VISClosure& closure);

This method is invoked after a request completes correctly or by throwing an exception. It is called after the ServantLocator has been invoked. Should an interceptor in the chain throw an exception, that interceptor also calls exceptionoccurred()and all remaining interceptors in the chain call exception()instead of calling postinvoke().

The CORBA::Environment parameter is changed to reflect this exception, even when a two-way call had already written an exception in that argument.

Parameter	Description
target	The client object which is being bound to the server.
service_context	The client object which is being bound to the server. Service context length is 0 for one-way calls and during exception.
payload	Marshalled buffer.
env	Contains information on the exception that was raised.
closure	The closure object previously given in the bind call.

virtual void exception_occurred(CORBA::Object_ptr target, CORBA::Environment_ptr env, VISClosure& closure);

This method is invoked by the ORB when an exception is thrown before the invocation. All exceptions thrown after the invocation are gathered in the environment parameter of the postinvoke method.

Parameter	Description
target	The client object which is being bound to the server.
env	Contains information on the exception that was raised.
closure	The closure object previously given in the bind call.

ClientRequestInterceptorManager

class Interceptor::ClientRequestInterceptorManager : public InterceptorManager, public VISPseudoInterface

This is the class that holds the chain of ClientRequestInterceptors for the current object.

A ClientRequestInterceptorManager should be used inside of the BindInterceptor::bind_succeeded( ) method within the scope set by the InteceptorManagerControl passed as an argument to bind_succeeded( ).

Include file

Include the interceptor_c.hh when you use this class.

ClientRequestInterceptorManager methods

virtual void add (ClientRequestInterceptor_ptr interceptor);

This method may be invoked to add a ClientRequestInterceptor to the local chain.

virtual void remove (ClientRequestInterceptor_ptr interceptor);

This method removes a ClientRequestInterceptorManager.

POALifeCycle Interceptor

class InterceptorManager::POALifeCycletInterceptor public VISPseudoInterface

The POALifeCycleInterceptor is a global interceptor which is invoked every time a POA is created or destroyed. All other server side interceptors may be installed either as global interceptors or for specific POAs. You install the POALifeCycleInterceptor through the POALifeCycleInterceptorManager interface. Go to “POALifeCycleInterceptorManager” for more information. The POALifeCycleInterceptor is called during POA creation and destruction.

Include file

Include the PortableServerExt_c.hh file when you use this class.

POALifeCycleInterceptor methods

virtual void create(PortableServer::POA_ptr poa, CORBA::PolicyList& policies IOP::IORValue*& iorTemplate, interceptor::InterceptorManagerControl_ptr poaAdmin);

This method is invoked when a new POA is created either explicitly through a call to create_POA or via AdapterActivator. With AdapterActivator, the interceptor is called only after the unknown_adapter method successfully returns from the AdapterActivator. The create method is passed as a reference to the recently created POA and as a reference to that POA instance's POAInterceptorManager.

Parameter	Description
poa	The ID associated with the current POA being created.
policies	The policies for the POA being created.
iorTemplate	The IOR template is a full IOR value with the type_id not set, and all GIOP::ProfileBodyValues will have incomplete object keys.
poaAdmin	The control for the POA being created. Go to “InterceptorManagerControl” for more information.

virtual void destroy(PortalServer::POA_ptr poa);

This method is called before a POA is destroyed and all of its objects have been etherealized. It guarantees that destroy will be called on all interceptors before create will be called again for a POA with the same name. If the destroy operation throws a system exception, the exception is ignored, and the remaining interceptors are called.

Parameter	Description
poa	Portable Object Adapter (POA) being destroyed.

POALifeCycleInterceptorManager

class InterceptorExt::POALifeCycleInterceptorManager public interceptor::InterceptorManager, public VISPseudoInterface

This class manages all POALifeCycle global interceptors. There is a single instance of the POALifeCycleInterceptorManager defined in an ORB.

Then scope of this interface is global, per-ORB. This class is only active during ORB_init( ) time.

Include file

Include the PortalServerExt_c.hh file when you use this class.

POALifeCycleInterceptorManager method

virtual void add(POALifeCycleInterceptor_ptr interceptor);

This method may be invoked to add a POALifeCycleInterceptor to the global chain of POALifeCycle interceptors.

Parameter	Description
interceptor	The interceptor to be added.

ActiveObjectLifeCycleInterceptor

class PortableServerExt::ActiveObjectLifeCycleInterceptor public VISPseudoInterface

The ActiveObjectLifeCycleInterceptor interceptor is called when objects are added and removed from the active object map. Only used when POA has RETAIN policy. This class is a POA-scoped interceptor which may be installed by a POALifeCycleInterceptor when the POA is created.

Include file

Include the PortableServerExt_c.hh file when you use this class.

ActiveObjectLifeCycleInterceptor methods

virtual void create(const PortableServer::ObjectId& oid, PortableServer::ServantBase* servant, PortableServer::POA_ptr adapter);

This method is invoked after an object has been added to the Active Object Map, either through explicit or implicit activation, using either direct APIs or a ServantActivator. The object reference and the POA of the new active object are passed as parameters.

Parameter	Description
oid	Object ID for the object currently activated.
servant	Associated servant
adapter	The Portable Object Adapter (POA) being created or destroyed.

virtual void destroy(const PortableServer::ObjectId& oid, PortableServer::ServantBase* servant, PortableServer::POA_ptr adapter);

This method is called after an object has been deactivated and etherealized. The object reference and the POA of the object are passed as parameters.

Parameter	Description
oid	Object ID for the object currently activated
servant	Associated servant
adapter	The Portable Object Adapter (POA) being created or destroyed.

ActiveObjectLifeCycleInterceptorManager

class PortableServerExt::ActiveObjectLifeCycleInterceptorManager public interceptor::InterceptorManager, public VISPseudoInterface

This is the class that manages all ActiveObjectLifeCycleInterceptors registered in its scope. Each POA has one single ActiveObjectLifeCycleInterceptorManager.

Include file

Include the PortableServerExt_c.hh file when you use this class.

ActiveObjectLifeCycleInterceptorManager method

virtual void add(ActiveObjectLifeCycleInterceptor interceptor_ptr interceptor);

This method may be invoked to add an ActiveObjectLifeCycleInterceptor to the chain.

ServerRequestInterceptor

class Interceptor::ServerRequestInterceptor public VISPseudoInterface

The ServerRequestInterceptor class is a POA-scoped interceptor which may be installed by a POALifeCycleInterceptor at POA creation time. This class may be used to perform access control, to examine and insert service contexts, and to change the reply status of a request.

Include file

Include the interceptor_c.hh file when you use this class.

ServerRequestInterceptor methods

virtual void preinvoke(CORBA::Object_ptr _target, const char* operation,
const IOP::ServiceContextList& service_contexts,
CORBA::MarshalInBuffer& payload, VISClosure& closure) raises(ForwardRequestException);

This method is invoked by the ORB on every request, before the request is demarshaled. An exception thrown from this interceptor results in the request being completed immediately. This method is called before any ServantLocators are invoked. The result may be that the servant may not be available while this method is running.

Parameter	Description
target	The client object which is being bound to the server.
operation	Identifies the name of the operation being invoked.
service_contexts	Identifies the services assigned by the Orb. These services are registered with the OMG.
payload	Marshalled buffer.
closure	May contain data saved by one interceptor method that can be retrieved later by another interceptor method.

virtual void postinvoke_premarshal(CORBA::Object_ptr target,IOP::ServiceContextList& ServiceContextList,CORBA::Environment_ptr env, VISClosure& closure);

This method is invoked after an upcall to the servant but before marshaling the reply. An exception here is handled by interrupting the chain: the request is not sent to the server and exceptionoccurred() is called on all interceptors in the chain

Parameter	Description
target	The client object which is being bound to the server.
ServiceContextList	Identifies the services assigned by the Orb. These services are registered with the OMG.
env	Contains information on the exception that was raised.
closure	May contain data saved by one interceptor method that can be retrieved later by another interceptor method.

virtual void postinvoke_postmarshal(CORBA::Object_ptr _target,CORBA::MarshalOutBuffer& _payload, VISClosure& _closure);

This method is invoked after marshaling the reply but before sending the reply to the client. Exceptions thrown here are ignored. The entire chain is guaranteed to be called.

Parameter	Description
target	The object to which that application was attempting to bind.
payload	Marshalled buffer.
closure	May contain data saved by one interceptor method that can be retrieved later by another interceptor method.

virtual void exception_occurred(CORBA::Object_ptr _target,CORBA::Environment_ptr _env, VISClosure& _closure);

This method is invoked by the ORB when an exceptionoccurred interceptor is called on all remaining interceptors in the chain after an exception occurred in one of the prepare_reply interceptors. An exception thrown during this call replaces the existing exception in the environment

Parameter	Description
target	The client object which is being bound to the server.
env	Contains information on the exception that was raised.
closure	May contain data saved by one interceptor method that can be retrieved later by another interceptor method.

ServerRequestInterceptorManager

class Interceptor::ServerRequestInterceptorManager public InterceptorManager, public VISPseudoInterface

This is the class that manages all ServerRequestInterceptors registered in its scope. Each POA has one single ServerRequestInterceptorManager.

Include file

Include the interceptor_c.hh file when you use this class.

ServerRequestInterceptorManager method

virtual void add(ServerRequestInterceptor_ptr interceptor);

Invoke this method to add a ServerRequestInterceptor to the chain.

IORCreationInterceptor

class PortableServerExt::IORInterceptor public VISPseudoInterface

The IORCreationInterceptor is a per-POA interceptor which may be installed by a POALifeCycleInterceptor at POA creation time. The interceptor may be used to modify IORs by adding additional profiles or components. This class is typically used to support services such as transactions or firewall.

This kind of interceptor is used to automatically change the IOR templates on certain classes of POAs whose names and identities may not be known at development time. This may be the case with services such as Transaction and Firewall.

Note

To change all the IORs created by a POA, simply modify the IORTemplate for that POA. The change will apply only to newly created IORs and not to any existing ones.

Making radical changes to the IOR is not recommended.

Include file

Include the PortableServerExt_c.hh file when you use this class.

IORInterceptor method

virtual void create(PortableServer::POA poa, IOP::IORValue*& ior);

The method is called whenever the POA needs to create an object reference. It takes the POA and the IORValue for the reference as arguments. The interceptor may modify the IORValue by adding additional profiles or components, or changing the existing profiles or components.

Parameter	Description
poa	The ID associated with the current PAO being created.
ior	The IOR for the server object to which the client is binding.

IORCreationInterceptorManager

class PortableServerExt::IORCreationInterceptorManager public interceptor::InterceptorManager, public VISPseudoInterface

This is the class that is used to manage (add) IOR interceptors to the local chain. Each POA has one single IORInterceptorManager.

Include file

Include the PortableServerExt_c.hh file when you use this class.

IORCreationInterceptorManager method

virtual void add(IORCreationInterceptor_ptr _interceptor);

This method may be invoked to add an IORInterceptor to the local chain.

VISClosure

struct VISClosure

This structure is used to store data so that it can be shared between different invocations of interceptor methods. The data that is stored is un-typed and can represent state information related to an operation request or a bind or locate request. It is used in conjunction with the VISClosureData class.

Include file

Include the vclosure.h file when you use this class.

VISClosure members

CORBA::ULong id

You can use this data member to uniquely identify this object if you are using more than one VISClosure object.

void *data

This data member points to the un-typed data that may be stored or accessed by an interceptor method.

VISClosureData *managedData

This data member points to the VISClosureData class that represents the actual data. You may cast your managed data to this type.

VisExtendedClosure

class VISExtendedClosure : public VISClosure {
public:
interceptor::RequestInfo reqInfo;
CORBA::MarshalInBuffer_ptr payload;
};

This interface is a derived class of VISClosure and contains a RequestInfo for read only attribute.

Code sample

This sample shows the RequestInfo IDL.

struct RequestInfo {

CORBA::Boolean response_expected;

CORBA::ULong request_id;

};

You can cast the VISClosure object passed to the ServerRequestInterceptor and ClientRequestInterceptor to its subclass, VISExtendedClosure. VISExtendedClosure can be used to extract the RequestInfo, from which you can extract the request_id and response_expected. The request_id is the unique id assigned to the request. The response_expected flag indicates whether the request is a one-way call.

CORBA::Boolean response_expected =

((VISExtendedClosure)closure).reqInfo.response_expected;

CORBA::ULong request_id = ((VISExtendedClosure)closure).reqInfo.request_id;

For more information, please see the example in examples/interceptor/client_server.

VISClosureData

class VISClosureData

This class represents managed data that can be shared between different invocations of interceptor methods.

VISClosureData methods

virtual void _VisClosureData();

This is the default destructor.

virtual void _release();

Releases this object and decrements the reference count. When the reference count reaches 0, the object is deleted.

ChainUntypedObjectWrapperFactory

class VISObjectWrapper::ChainUntypedObjectWrapperFactory: public UntypedObjectWrapperFactory

This interface is used by a client or server application to add or remove an UntypedObjectWrapperFactory object. An UntypedObjectWrapperFactory is used to create an UntypedObjectWrapper for each object a client application binds to or for each object implementation created by a server application.

See “Using object wrappers” in the VisiBroker C++ Developer's Guide for more information about how to use the object wrappers.

Include file

Include the vobjwrap.h file when you use this class.

ChainUntypedObjectWrapperFactory methods

void add(UntypedObjectWrapperFactory_ptr factory,Location loc);

This method adds the specified un-typed object wrapper factory for a client application, server application, or collocated application.

If your application is acting as both a client application and a server application, that is, a collocated application, you can install an un-typed object wrapper factory. If you do so, the wrapper's methods are invoked for both invocations on bound objects and operation requests received by object implementations. In other words, they are invoked on both the client and server portions of the application.

Note

On the client side, un-typed object wrapper factories must be defined before any objects are bound. On the server side, un-typed object wrapper factories must be defined before an invocation for an object implementation is received.

Parameter	Description
factory	A pointer to the factory to be registered.
loc	The location of the factory being added, which should be one of the following values: VISObjectWrapper::Client VISObjectWrapper::Server VISObjectWrapper::Both

void remove(UntypedObjectWrapperFactory_ptr factory, Location loc);

This method removes the specified un-typed object wrapper factory from the specified location.

If your application is acting as both a client and a server, you can remove the object wrapper factories for either the client side objects, server side implementations, or both.

Note

Removing one or more object wrapper factories from a client does not affect objects of that class which are already bound by the client. Only subsequently bound objects will be affected.

Removing object wrapper factories from a server does not affect object implementations that have already serviced requests. Only subsequently created object implementations will be affected.

Parameter	Description
factory	A pointer to the factory to be registered.
loc	The location of the factory being removed; one of the following values: VISObjectWrapper::Client VISObjectWrapper::Server VISObjectWrapper::Both

static CORBA::ULong count(Location loc);

This static method returns the number of un-typed object wrapper factories installed for the specified location.

Parameter	Description
loc	The location of the factories: VISObjectWrapper::Client VISObjectWrapper::Server VISObjectWrapper::Both

UntypedObjectWrapper

class VISObjectWrapper::UntypedObjectWrapper : public VISResource

You use this class to derive and implement an un-typed object wrapper for a client application, a server application, or collocated application. When you derive an un-typed object wrapper from this class, you define a pre_method method that is invoked before a request is issued by a client application or before it is processed by an object implementation on the server side. You also define a post_method method that will be invoked after an operation request is processed by an object implementation on the server side or after a reply has been received by a client application.

You must also derive a factory class that will create your un-typed wrapper objects. Derive it from the UntypedObjectWrapperFactory class, described in “UntypedObjectWrapper”.

Refer to the VisiBroker C++ Developer's Guide for more information about how to use the object wrappers.