The VisiBroker ORB provides a set of interfaces known as interceptors which provide a framework for plugging-in additional ORB behavior such as security, transactions, or logging. These interceptor interfaces are based on a callback mechanism. For example, using the interceptors, you can be notified of communications between clients and servers, and modify these communications if you wish, effectively altering the behavior of the VisiBroker ORB.
|
Figure 32
|
The two kinds of Portable Interceptors defined by the OMG specification are: Request Interceptors and IOR interceptors.
|
Can enable the VisiBroker ORB services to transfer context information between clients and servers. Request Interceptors are further divided into Client Request Interceptors and Server Request Interceptors.
|
For additional information on using both Portable Interceptors and VisiBroker Interceptors, see “Using VisiBroker Interceptors”.
See also the VisiBroker for Java APIs documentation.
All the interceptor classes listed above are derived from a common class: Interceptor. This Interceptor class has defined common methods that are available to its inherited classes.
A request interceptor is used to intercept the flow of a request/reply sequence at specific interception points so that services can transfer context information between clients and servers. For each interception point, the VisiBroker ORB gives an object through which the interceptor can access request information. There are two kinds of request interceptor and their respective request information interfaces:
|
•
|
ClientRequestInterceptor and ClientRequestInfo
|
|
•
|
ServerRequestInterceptor and ServerRequestInfo
|
|
Figure 33
|
For more detail information on Request Interceptors, see the VisiBroker for Java APIs documentation.
ClientRequestInterceptor has its interception points implemented on the client-side. There are five interception points defined in ClientRequestInterceptor by the OMG as shown in the following table:
|
Lets a client-side Interceptor query a request during a Time-Independent Invocation (TII)1 polling get reply sequence.
|
|
1 TII is not implemented in the VisiBroker ORB. As a result, the send_poll( ) interception point will never be invoked.
For more information on each interception point, see the VisiBroker for Java APIs documentation.
|
•
|
The starting interception points are: send_request and send_poll. On any given request/reply sequence, one and only one of these interception points is called.
|
|
•
|
|
•
|
|
•
|
A receive_exception is called with the system exception BAD_INV_ORDER with a minor code of 4 (ORB has shutdown) if a request is canceled because of ORB shutdown.
|
|
•
|
A receive_exception is called with the system exception TRANSIENT with a minor code of 3 if a request is canceled for any other reason.
|
|
send_request is followed by receive_reply; a start point is followed by an end point
|
|
|
send_request is followed by receive_other; a start point is followed by an end point
|
ServerRequestInterceptor has its interception points implemented on the server-side. There are five interception points defined in ServerRequestInterceptor. The following table shows the ServerRequestInterceptor Interception points.
|
Lets a server-side Interceptor get its service context information from the incoming request and transfer it to PortableInterceptor::Current's slot.
|
|
For more detail on each interception point, see the VisiBroker for Java APIs documentation.
ServerRequestInterceptor Interface:
|
•
|
The starting interception point is: receive_request_service_contexts. This interception point is called on any given request/reply sequence.
|
|
•
|
The ending interception points are: send_reply, send_exception and send_other. On any given request/reply sequence, one and only one of these interception points is called.
|
|
•
|
The intermediate interception point is receive_request. It is called after receive_request_service_contexts and before an ending interception point.
|
|
•
|
On an exception, receive_request may not be called.
|
|
•
|
|
•
|
A send_exception is called with the system exception BAD_INV_ORDER with a minor code of 4 (ORB has shutdown) if a request is canceled because of ORB shutdown.
|
|
•
|
A send_exception is called with the system exception TRANSIENT with a minor code of 3 if a request is canceled for any other reason.
|
|
The order of interception points: receive_request_service_contexts, receive_request, send_reply; a start point is followed by an intermediate point which is followed by an end point.
|
IORInterceptor give applications the ability to add information describing the server's or object's ORB service related capabilities to object references to enable the VisiBroker ORB service implementation in the client to function properly. This is done by calling the interception point, establish_components. An instance of IORInfo is passed to the interception point. For more information on IORInfo, see the VisiBroker for Java APIs documentation.
The PortableInterceptor::Current object (hereafter referred to as PICurrent) is a table of slots that can be used by Portable Interceptors to transfer thread context information to request context. Use of PICurrent may not be required. However, if client's thread context information is required at interception point, PICurrent can be used to transfer this information.
PICurrent is obtained through a call to:
PortableInterceptor.Current interface:
Codec provides a mechanism for interceptors to transfer components between their IDL data types and their CDR encapsulation representations. A Codec is obtained from CodecFactory. For more information, see “CodecFactory”.
The Codec interface:
This class is used to create a Codec object by specifying the encoding format, the major and minor versions. CodecFactory can be obtained with a call to:
The CodecFactory interface:
Portable Interceptors must be registered with the VisiBroker ORB before they can be used. To register a Portable Interceptor, an ORBInitializer object must be implemented and registered. Portable Interceptors are instantiated and registered during ORB initialization by registering an associated ORBInitializer object which implements its pre_init( ) or post_init( ) method, or both. The VisiBroker ORB will call each registered ORBInitializer with an ORBInitInfo object during the initializing process.
The ORBInitializer interface:
The ORBInitInfo interface:
To register an ORBInitializer, the global method register_orb_initializer is provided. Each service that implements Interceptors provides an instance of ORBInitializer. To use a service, an application:
|
1
|
|
2
|
makes an instantiating ORB_Init( ) call with a new ORB identifier to produce a new ORB.
|
Since the register_orb_initializer( ) is a global method, it would break applet security with respect to the ORB. As a result, ORBInitializers are registered with VisiBroker ORB by using Java ORB properties instead of calling register_orb_initializer( ).
where <Service> is the string name of a class which implements org.omg.PortableInterceptor.ORBInitializer.
During ORB.init( ):
|
1
|
these ORB properties which begin with org.omg.PortableInterceptor.ORBInitializerClass are collected.
|
|
2
|
the <Service> portion of each property is collected.
|
|
3
|
an object is instantiated with the <Service> string as its class name.
|
|
4
|
A client-side monitoring tool written by company ABC may have the following ORBInitializer implementation:
The following command may be used to run a program called MyApp using this monitoring service:
Portable Interceptors specified by OMG are scoped globally. VisiBroker has defined “POA scoped Server Request Interceptor”, a public extension to the Portable Interceptors, by adding a new module call PortableInterceptorExt. This new module holds a local interface, IORInfoExt, which is inherited from PortableInterceptor::IORInfo and has additional methods to install POA scoped server request interceptor.
The IORInfoExt interface:
To conveniently insert and extract SystemExceptions to and from an Any, a utility helper class is provided only for VisiBroker for Java. The com.inprise.vbroker.PortableInterceptor.SystemExceptionHelper class provides the methods to insert and extract the SystemExceptions into and out of an Any respectively. You need to import the following package:
|
•
|
arguments(), result(), exceptions(), contexts(), and operation_contexts() are only available for DII invocations. For more information, see “Using the Dynamic Skeleton Interface”.
|
|
•
|
received_exception() and received_exception_id() will always return a CORBA::UNKNOWN exception and its respective repository id if a user exception is thrown by the application.
|
|
•
|
exceptions() does not return any value; it will raise a CORBA::NO_RESOURCES exception in both dynamic invocations and static stub based invocation.
|
|
•
|
contexts() returns the list of contexts that are available during operation invocation.
|
|
•
|
sending_exception() returns the correct user exception only in the case of dynamic invocation (provided the user exception can be inserted into an Any or its TypeCode information is available).
|
|
•
|
arguments(), result(), contexts(), and operation_contexts() are only available for DSI invocations. For more information, see “Using the Dynamic Skeleton Interface”.
|
This section discusses how applications are actually written to make use of Portable Interceptors and how each request interceptor is implemented. Each example consists of a set of client and server applications and their respective interceptors written in Java. For more information on the definition of each interface, see the VisiBroker for Java APIs documentation.
|
•
|
If you are using any Portable Interceptors exceptions, such as DuplicateName or InvalidName, the ORBInitInfoPackage is optional.
To load a client-side request interceptor, a class that uses the ORBInitializer interface must be implemented. This is also applicable for server-side request interceptor as far as initialization is concerned. The following example shows the code for loading:
Each object that implements the interface, ORBInitializer, is also required to inherit from the object LocalObject. This is necessary because the IDL definition of ORBInitializer uses the keyword local.
During the initialization of the ORB, each request Interceptor is added through the implementation of the interface, pre_init(). Inside this interface, the client request Interceptor is added through the method, add_client_request_interceptor(). The related client request interceptor is required to be instantiated before adding itself into the ORB.
where <Service> is the string name of a class which implements org.omg.PortableInterceptor.ORBInitializer. For more information, see “Developing the Client and Server Application”.
At this stage, the client request interceptor should already have been properly instantiated and added. Subsequent code thereafter only provides exception handling and result display. Similarly, on the server-side, the server request interceptor is also done the same way except that it uses the, add_server_request_interceptor() method to add the related server request interceptor into the ORB.
Upon implementation of either client- or server-side request interceptor, two other interfaces must be implemented. They are name() and destroy().
The name() is important here because it provides the name to the ORB to identify the correct interceptor that it will load and call during any request or reply. According to the CORBA specification, an interceptor may be anonymous, for example, it has an empty string as the name attribute. In this example, the name, SampleClientInterceptor, is assigned to the client-side interceptor and SampleServerInterceptor is assigned to the server-side interceptor.
For the client request interceptor, it is necessary to implement the ClientRequestInterceptor interface for the request interceptor to work properly.
send_request—provides an interception point for querying request information and modifying the service context before the request is sent to the server.
send_poll—provides an interception point for querying information during a Time-Independent Invocation (TII) polling to get the reply sequence.
receive_reply—provides an interception point for querying information on a reply after it is returned from the server and before control is returned to the client.
receive_exception—provides an interception point for querying the exception's information before it is raised to the client.
receive_other—provides an interception point for querying information 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. However, the control is returned to the client and an ending interception point is called.
receive_request_service_contexts—provides an interception point for getting service context information from the incoming request and transferring it to PortableInterceptor::Current slot. This interception point is called before the Servant Manager. For more information, see “Using servants and servant managers”.
receive_request—provides an interception point for querying all the information, including operation parameters.
send_reply—provides an interception point for querying reply information and modifying the reply service context after the target operation has been invoked and before the reply is returned to the client.
send_exception—provides an interception point for querying the exception information and modifying the reply service context before the exception is raised to the client.
send_other—provides an interception point for querying 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 (such as, a GIOP Reply with a LOCATION_FORWARD status was received); or, on asynchronous calls, the reply does not immediately follow the request, but control is returned to the client and an ending interception point is called.
The following code example shows the complete implementation of the server-side request interceptor:
The OMG specification has been strictly followed to implement the mappings of register_orb_initializer, which is registered using Java ORB properties. In the example, the client and server applications actually read the property files, client.properties, and server.properties containing the property
where <Service> is the string name of a class which implements org.omg.PortableInterceptor.ORBInitializer. In this case, the two classes are SampleClientLoader and SampleServerLoader.
or double-click the batch file icon if the environment variable, <install_dir>\bin, has already been added to the environment variable, PATH).