Using Portable Interceptors

This chapter provides an overview of Portable Interceptors. Portable Interceptor example code is available in your VisiBroker for .NET installation.

Portable Interceptors overview

VisiBroker for .NET 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 ORB.

At its simplest usage, the interceptor is useful for tracing through code. Because you can see the messages being sent between clients and servers, you can determine exactly how the ORB is processing requests.

If you are building a more sophisticated application such as a monitoring tool or security layer, interceptors give you the information and control you need to enable these lower-level applications. For example, you could develop an application that monitors the activity of various servers and performs load balancing.

Types of Portable Interceptors

There are two kinds of Portable Interceptors defined by the OMG specification:

•	Request Interceptors can enable the ORB services to transfer context information between clients and servers. Request Interceptors are further divided into Client Request Interceptors and Server Request Interceptors.

•

An IOR interceptor is used to enable an ORB service to add information in an IOR describing the server's or object's ORB-service-related capabilities. For example, a security service (like SSL) can add its tagged component into the IOR so that clients recognizing that component can establish the connection with the server based on the information in the component.

Portable Interceptor classes and interfaces

All Portable Interceptors implement one of the following base interceptor API classes which are defined and implemented by VisiBroker for .NET:

•	ClientRequestInterceptor

•	ServerRequestInterceptor

•	IORInterceptor

Interceptor class

All the interceptor classes mentioned above are derived from a common class: Interceptor. This Interceptor class has defined common methods that are available to its inherited classes.

Request Interceptor

A request interceptor is used to intercept 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 ORB gives an object through which the Interceptor can access request information. There are two kinds of request interceptors and their respective request information interfaces:

•	ClientRequestInterceptor and ClientRequestInfo

•	ServerRequestInterceptor and ServerRequestInfo

ClientRequestInterceptor

ClientRequestInterceptor has its interception points implemented on the client side. There are five interception points defined in ClientRequestInterceptor by OMG as shown in the following table.

Interception Points	Description
SendRequest	Lets a client-side Interceptor query a request and modify the service context before the request is sent to the server.
SendPoll	Lets a client-side Interceptor query a request during a Time-Independent Invocation (TII)1 polling get reply sequence.
ReceiveReply	Lets a client-side Interceptor query the reply information after it is returned from the server and before the client gains control.
ReceiveException	Lets a client-side Interceptor query the exception's information, when an exception occurs, before the exception is sent to the client.
ReceiveOther	Lets a client-side Interceptor query the information which is available when a request result other than normal reply or an exception is received.

1TII is not implemented in VisiBroker for .NET. As a result, the SendPoll( ) interception point will never be invoked.

Client-side rules

The following are the client-side rules:

•	The starting interception points are: SendRequest and SendPoll. On any given request/reply sequence, one and only one of these interception points is called.

•	The ending interception points are: ReceiveReply, ReceiveException and ReceiveOther.

•	There is no intermediate interception point.

•	An ending interception point is called if and only if SendRequest or SendPoll runs successfully.

•	A ReceiveException 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 ReceiveException is called with the system exception TRANSIENT with a minor code of 3 if a request is canceled for any other reason.

Successful invocations	SendRequest is followed by ReceiveReply - a start point is followed by an end point
Retries	SendRequest is followed by ReceiveOther - a start point is followed by an end point

ServerRequestInterceptor

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.

Interception Points	Description
ReceiveRequestService Contexts	Lets a server-side Interceptor get its service context information from the incoming request and transfer it to PortableInterceptor.Current's slot.
ReceiveRequest	Lets a server-side Interceptor query request information after all information, including operation parameters, is available.
SendReply	Lets a server-side Interceptor 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.
SendException	Lets a server-side Interceptor query the exception's information and modify the reply service context, when an exception occurs, before the exception is sent to the client.
SendOther	Lets a server-side Interceptor query the information which is available when a request result other than normal reply or an exception is received.

Server-side rules

The server-side rules are listed as below:

•	The starting interception point is: ReceiveRequestServiceContexts. This interception point is called on any given request/reply sequence.

•	The ending interception points are: SendReply, SendException and SendOther. On any given request/reply sequence, one and only one of these interception points is called.

•	The intermediate interception point is ReceiveRequest. It is called after ReceiveRequestServiceContexts and before an ending interception point.

•	On an exception, ReceiveRequest may not be called.

•	An ending interception point is called if and only if ReceiveRequestServiceContext runs successfully.

•	A SendException 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 SendException is called with the system exception TRANSIENT with a minor code of 3 if a request is canceled for any other reason.

Successful invocations

The order of interception points: ReceiveRequestServiceContexts, ReceiveRequest, SendReply - a start point is followed by an intermediate point which is followed by an end point .

IORInterceptor

IORInterceptor gives applications the ability to add information describing the server's or object's ORB service related capabilities to object references to enable the ORB service implementation in the client to function properly. This is done by calling the interception point, EstablishComponents. An instance of IORInfo is passed to the interception point.

PortableInterceptor (PI) Current

The PortableInterceptor.Current object (hereafter referred to as PICurrent) is a table of slots that can be used by Portable Interceptors implementations to associate thread-specific information with the currently active request context. Use of PICurrent is optional, and would typically be used if a client's thread-specific information is required within an Interceptor.

PICurrent is obtained through a call to:

ORB.ResolveInitialReferences("PICurrent");

Codec

The Codec provides a mechanism for interceptors to transfer components between their IDL data types and their CDR encapsulation representations.

CodecFactory

This class is used to create a Codec object by specifying the encoding format, the major and minor versions. CodecFactory can be obtained a call to:

ORB.ResolveInitialReferences("CodecFactory");

Creating a Portable Interceptor

The generic steps to create a Portable Interceptor are:

1	The Interceptor must be inherited from one of the following Interceptor interfaces:

• ClientRequestInterceptor

• ServerRequestInterceptor

• IORInterceptor

2	The Interceptor implements one or more interception points that are available to the Interceptor.

3	The Interceptor can be named or anonymous. All names must be unique among all Interceptors of the same type. However, any number of anonymous Interceptors can be registered with the ORB.

Registering Portable Interceptors

Portable Interceptors must be registered with the ORB before they can be used. To register a Portable Interceptor the janeva.orb.init property is provided.

-janeva.orb.init pi_class_name[,assembly_name]

Note, that it is possible to specify a list of janeva.pi.init settings to configure multiple Portable Interceptors:

-janeva.orb.init pi_1 -janeva.orb.init pi_2 -janeva.orb.init pi_n

Each janeva.orb.init instance does not overwrite the previous one, but adds it to a Portable Interceptor list.

VisiBroker for .NET extensions to Portable Interceptors

POA scoped Server Request Interceptors

Portable Interceptors specified by OMG are scoped globally. VisiBroker for .NET 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.

IORInfoExt Interface

using PortableInterceptor;

namespace PortableInterceptorExt {

public interface IORInfoExt : IORInfo {

void AddServerRequestInterceptor(

ServerRequestInterceptor interceptor);

string FullPoaName();

}

}

Limitations of the Portable Interceptors Implementation

The following are limitations of the Portable Interceptor implementation.

ClientRequestInfo

•	Arguments, Result, Exceptions, Contexts, and OperationContexts are only available for DII invocations.

•	ReceivedException and ReceivedExceptionId will always return a CORBA.UNKNOWN exception and its respective repository id if a user exception is thrown by the application.

ServerRequestInfo

•	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.

•	SendingException 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 OperationContexts are only available for DSI invocations.