VisiBroker for C++ API Reference Guide : Error codes : VisiBroker Interceptor and object wrapper interfaces and classes for C++

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.
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.
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.
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.
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.
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.
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:
exception_occurred() is called on the whole interceptor chain.
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.
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.
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” on page 244 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.
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.
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.
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.
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.
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.
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
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.
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
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.
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.
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.
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.
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” on page 251.
Refer to the VisiBroker C++ Developer's Guide for more information about how to use the object wrappers.