Introduction to CORBA Request-Level Interceptors

Notes:

The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, should only be used to help implement/run third party Java ORB libraries, and for programmer reference only.

Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs.

A request-level interceptor is a user-written CORBA object that provides a means to insert functionality, such as security or monitoring components, into the invocation path between the client and server components of a CORBA application. When you have an interceptor installed and registered with an Object Request Broker (ORB) on a particular machine, the interceptor is involved with all the CORBA applications on that machine. You can use interceptors to insert any additional functionality into the invocation path of an object invocation, at either the client, or the server, or both ends of the invocation.

Request-level interceptors are not usually part of a typical CORBA environment. Implementing them is considered an advanced programming task.

The CORBA environment in the Oracle Tuxedo system supports two categories of interceptors:

•	Client-side interceptors, which are called by the ORB at the client side of an invocation and are run in the process of an entity making a request. Client-side interceptors inherit from the ClientRequestInterceptor class.

•

Target-side interceptors, which are called by the ORB at the target side of an invocation and are run with the target application process. The target of an invocation may be a CORBA server application or a CORBA joint client/server application. Target-side interceptors inherit from the TargetRequestInterceptor class.

The CORBA environment Oracle Tuxedo system is very flexible about where you can install and use interceptors, with respect to the relative location of the client and target objects. It is transparent to a client application whether the target of its request is in the same or a different process.

Although client- and target-side interceptors inherit from separate interfaces, it is often convenient to implement the interceptors in a single source file.

Interceptor Architecture

The following figure shows the relationship between request-level interceptors and the Oracle Tuxedo system.

Note the following about the Oracle Tuxedo implementation of CORBA interceptors:

•	Interceptors are registered administratively and are called by the ORB at the appropriate time during the execution of the application.

•	When a client-side interceptor is installed and registered with an ORB, that interceptor is called with every request coming from any CORBA client application on that machine.

During the course of a single, successful request-response cycle of an invocation, a client-side interceptor is called twice by the ORB:

a.	When the request is first issued from the client application and arrives at the ORB (the client_invoke operation)

b.	When the target response arrives back at the client application process (the client_response operation)

•	When a target-side interceptor is installed and registered with an ORB, that interceptor is called with every request that arrives for any target object on that machine.

During the course of a single request-response cycle of an invocation, a target-side interceptor is called twice by the ORB:

a.	When the client request first arrives at the ORB (the target_invoke operation)

b.	When the target object response arrives at the ORB (the target_response operation)

•	You can install and register multiple client- or target-side interceptors with an ORB.

•	Interceptors are independent of each other, and they do not require knowledge about the potential presence of other interceptors.

•	Interceptors can short-circuit an invocation by returning a response directly to the client without involving the target object at all.

•	Interceptors impact overall application performance because they add an additional step in the execution of every request.

The ORB maintains a list of registered interceptors. Registering an interceptor is something you do as an administrative task. During application run time, the ORB uses this list to determine when to call the interceptors and in what order, because multiple interceptors can be installed and created. When you have multiple interceptors registered, the ORB executes each interceptor consecutively. Establishing the order in which multiple interceptors are called is also an administrative task.

Capabilities and Limitations

Request-level interceptors are especially useful for implementing several different types of service applications, such as:

•	Instrumentation points for collecting statistics

•	Probe points that include monitoring or tracing facilities

•	Security checks to determine whether a particular type of invocation should be permitted, or whether a specific bit of information can be returned to a client application. For more information about interceptors and security, see Chapter 6, “InterceptorSec Sample Interceptors.”

The following are current limitations on CORBA interceptors:

•	Interceptors are called only by an ORB. Neither CORBA client nor server applications can call an interceptor directly.

•	Interceptors implemented in a specific programming language can intercept invocations only from entities that are also implemented in that same language.

•	Interceptors cannot write to the DataInputStream object.

•	Interceptors cannot pass or manipulate the service context object.

•	Interceptors cannot pass or manipulate the transaction current object.

•	Interceptors cannot invoke methods on the Tobj_Bootstrap object.

•	The REPLY_NO_EXCEPTION return status value is not supported, although it appears in the method signatures operations on interceptor classes.

•

An interceptor can make invocations on other objects; however, those invocations are subject to interception as well. When an interceptor invokes an object, make sure the interceptor doesn’t intercept its own invocation in an infinite loop—which will happen if the object being invoked is in the same server process as the interceptor. In such a situation, the system can hang.

•	The method signatures for operations on classes derived from the RequestLevelInterceptor interface include parameters for the following interfaces:

•	RequestLevelInterceptor::DataOutputStream

•	RequestLevelInterceptor::ServiceContextList

These interfaces are not used in the Oracle Tuxedo product. These interfaces are defined in the Oracle Tuxedo software so that you do not need to recompile your CORBA application if an implementation of these interfaces is ever provided in a future release of the Oracle Tuxedo product. The ORB will always pass a nil object for the actual argument. You should not attempt to use these arguments; doing so will likely end the process with a serious error.

Execution Flow

The following sections explain what happens during the execution of a CORBA application that uses interceptors. In general, request-level interceptors are instantiated and initialized only when the ORB is initialized. At no other time can request-level interceptors be instantiated.

The return status of an interceptor controls the execution flow of the ORB run-time and any other request-level interceptors that may be installed.

Depending on the return status of an interceptor after it has been called, one of the following events may occur:

•	The invocation resumes its normal path to the target object, back to the client application, or to another interceptor.

•

The interceptor on either the client or the server side services the client request and sends an exception back to the client. (In this case, the request may never be sent to the target object, or the target object may provide a response that the interceptor replaces with an exception. This would happen transparently to the client application.)

Multiple request-level interceptors can be involved in a single invocation, and no interceptor needs to know about any other interceptor.

The events that take place during a request-response cycle of an invocation are presented in two categories:

•	Client-side execution

•	Target-side execution

Client-side Execution

Each interceptor is called twice during the request-response cycle of an invocation: once when a request is going from the client towards the target, and again when a response returns back to the client. The client interceptor class, ClientRequestInterceptor, has two corresponding operations, among others, for these two calls:

•	client_invoke()—called when the request made on an object reference arrives at the client-side ORB.

•	client_response()—called when the response is returned back towards the entity making the request.

The flow of execution of a CORBA application that uses a client-side interceptor is shown in Figure 1‑1. This figure shows a basic and successful request-response invocation cycle (that is, no exceptions are raised).

Figure 1‑1 Client-side Interceptor

In Figure 1‑1, note the following events that are called out:

1.	The request leaves the client and arrives at the ORB.

2.	The ORB calls the client_invoke operation on the client-side interceptor. (The section “Using Multiple Request-Level Interceptors,” explains what happens when you have multiple client-side interceptors installed.)

3.	The client-side interceptor processes the request and returns a status code to the ORB.

4.	If no exception is returned as a result of the client_invoke operation, the request resumes its path toward the target object.

5.	The target object processes the request and issues a response.

6.	The response arrives back at the ORB, and the ORB calls the client_response operation on the interceptor.

7.	The interceptor processes the response and returns a status code to the ORB.

8.	The response is sent to the client application.

Client-side Exception Handling

The client_invoke and client_response operations each return a status value that indicates whether the client interceptor processing should continue. The interceptors may return exception status values, which cause exception handling to take place. Table 1‑1 shows what happens depending on what status value is returned from these operations, and shows how the interceptors, together with the ORB, handle exceptions.

 

Table 1‑1 Client Interceptor Return Status Values

Operation	Return Status Value	What Happens
client_invoke()	INVOKE_NO_EXCEPTION	The ORB continues normal processing of the request toward the target, calling other interceptors, if any.
	REPLY_NO_EXCEPTION   (In version 8.0 of the Oracle Tuxedo product, the ORB cannot process this return value, so do not implement this as a return value in your interceptors.)	The interceptor has serviced the request and no further process toward the target is needed. The request will be considered serviced as if the target processed it. Thus, the ORB short circuits the invocation and starts calling interceptors back towards the client. The client_response operation is not called on the same interceptor, but this operation on any previously invoked interceptor is called.
	REPLY_EXCEPTION	The interceptor returns an exception to the ORB. The ORB then calls each previous client-side interceptors’ exception_occurred operation. The exception_occurred method gives these previous interceptors an opportunity to clean up state before the ORB returns an exception back to the client application. Thus, the ORB short circuits the invocation, and the invocation is now complete. For more information about the exception_occurred method, see the section “The exception_occurred Method” on page 1‑12.
client_response()	RESPONSE_NO_EXCEPTION	The ORB continues normal processing of the request toward the client, calling other interceptors, if any.
	RESPONSE_EXCEPTION	The interceptor passes an exception back to the ORB, overriding any previous result of the request. The ORB invokes the exception_occurred method on each previous interceptor back towards the client, then returns an exception to the client application.

Target-side Execution

As on the client side, a target-side interceptor is called twice during a request-response cycle. Target-side interceptors inherit from the TargetRequestInterceptor class, which includes the following operations:

•	target_invoke()—called when the request arrives at the ORB that is part of the target object process.

•	target_response()—called when the response is sent back to the client.

The flow of execution of a CORBA application that uses a target-side interceptor is shown in Figure 1‑2. This figure shows a basic and successful request-response invocation cycle (that is, no exceptions are raised).

Figure 1‑2 Target-side Interceptor

In Figure 1‑2, note the following events that are called out:

1.	The client request arrives at the ORB.

2.	The ORB calls the target_invoke operation on the target-side interceptor. (The section “Using Multiple Request-Level Interceptors,” explains what happens when you have multiple target-side interceptors installed.)

3.	The target-side interceptor processes the request and returns a status code to the ORB.

4.	If no exception is raised during the execution of the target_invoke operation, the request resumes its path toward the target object.

5.	The target object processes the request and issues a response.

6.	The target-side ORB calls the target_response operation on the interceptor.

7.	The interceptor processes the response and returns a status code to the ORB.

8.	The response is sent to the client application.

Target-side Exception Handling

Table 1‑2 shows what happens to an invocation on the target side depending on what status values are returned by the target_invoke and target_response operations, explaining what happens when exceptions are thrown.

 

Table 1‑2 Target Interceptor Return Status Values

Operation	Return Status Value	What Happens
target_invoke()	INVOKE_NO_EXCEPTION	The ORB continues normal processing of the request toward the target (the object implementation), calling other interceptors, if any.
	REPLY_NO_EXCEPTION   (In version 8.0 of the Oracle Tuxedo product, the ORB cannot process this return value, so do not implement this as a return value in your interceptors.)	The interceptor has serviced the request and no further process toward the target is needed. The request will be considered serviced as if the target processed it. Thus, the ORB short circuits the invocation and starts calling interceptors back towards the client. The target_response operation is not called on the same interceptor, but this operation on any previously invoked interceptor is called.
	REPLY_EXCEPTION	The interceptor returns an exception to the ORB. The ORB then calls each previous target-side interceptors’ exception_occurred operation. The exception_occurred method gives these previous interceptors an opportunity to clean up state before the ORB returns an exception back to the client ORB. Thus, the target ORB short circuits the invocation, and the invocation is now complete. For more information about the exception_occurred method, see the section “The exception_occurred Method” on page 1‑12.
target_response()	RESPONSE_NO_EXCEPTION	The ORB continues normal processing of the request toward the client, calling other interceptors, if any.
	RESPONSE_EXCEPTION	The interceptor passes a new exception back ORB, overriding any previous result of the request. Instead of calling the target_response operation for interceptors on the way back to the client, the ORB calls the exception_occurred operation on those interceptors instead.

The exception_occurred Method

Every interceptor has the exception_occurred method, which the ORB may call under the following circumstances:

•	The ORB has found an internal problem; for example, an operating system resource error or a communication problem.

•

A different interceptor has set an exception (rather than an exception being generated by the ORB or the method). For example, the ORB is calling Interceptors A and B, respectively. Interceptor A has set an exception, so the ORB then calls the exception_occurred method on Interceptor B instead of the client_response or target_response methods. Your interceptor can take advantage of this behavior to examine both the context in which the response containing the exception is being processed and the actual value of the exception without reading the exception from the DataInputStream structure.

•	The client application is using a deferred synchronous DII invocation on a Request object and then releases the Request object. In this case no response is delivered to the client.

When one of the preceding situations has occurred, calling the exception_occurred method is an alternative to calling the client_response or target_response methods; however, the effect is essentially the same in that the client invocation is complete.

For more information about keeping track of requests, see the section “Implementing the Interceptor’s Response Operation” on page 2‑5.

About Short-circuit Behavior

As mentioned earlier, an interceptor can short-circuit a client request by servicing the request itself or by returning an exception. In either case, the client request is never actually serviced by the target object.

This short-circuit behavior works only in the client_invoke or target_invoke methods. It doesn’t apply to the client_response or target_response methods.

Using Multiple Request-Level Interceptors

Multiple request-level interceptors are installed in a queue such that the ORB can execute one after the other in a sequential order. The ORB gives each request-level interceptor the request in succession until there are no more request-level interceptors left in the queue to execute. If all interceptors indicate success, the request is processed. The ORB delivers the resulting response to the transport in the client case, or to the object implementation in the target case. The ORB executes the interceptors servicing a response in the reverse order than that of servicing a request.

When an interceptor does not indicate success, a short circuit response results. This short circuit can be performed by the client_invoke or target_invoke operations. The status returned from the interceptor tells the ORB that the interceptor itself has decided to respond to the request with an exception, rather than to allow the target object to handle the request. (An interceptor’s client_response or target_response operation cannot perform any short-circuit behavior, but it can replace the target response.)

Each interceptor is normally unaware of the other interceptors, unless they explicitly share information. This independent programming model is preserved by the execution semantics with regards to short circuits: When an interceptor indicates that a response should be short-circuited and not reach its intended destination (which is the transport on the client side, and the object implementation on the target side), the response circulates back through the interceptors through which it has successfully passed. For example, if Interceptor A returns the status value INVOKE_NO_EXCEPTION after processing a client_invoke operation, expecting the request to be delivered, and the next Interceptor, B, denies the request with an exception, that exception gets put into the response and is delivered to Interceptor A’s exception_occurred operation. The analogous execution model on the target side is in effect also.

Figure 1‑3 shows the sequence of execution when multiple client-side interceptors are installed on an ORB. (A similar series of operations occur with multiple target-side interceptors.)

Figure 1‑3 Multiple Interceptors on an ORB

In Figure 1‑3, note the following events that are called out:

1.	The client request arrives in the ORB, and the ORB calls Interceptors A through D in sequence.

2.	The request goes to the target object.

3.	The target object processes the request and returns a response.

4.	The response arrives back at the ORB with the client-side interceptors. The ORB then calls each of the registered interceptors in a sequence that’s the reverse of the order in which they were called when the request went out.

5.	The response arrives back at the client application.

Multiple Client-side Interceptors

When the ORB receives a request, the ORB calls each client-side interceptor’s client_invoke operation in turn. If the return value INVOKE_NO_EXCEPTION is returned from each client_invoke operation (the normal case), the resulting request is marshaled into a message by the ORB and sent to the target object.

Under the following circumstances, instead of calling the client_response operation on remaining interceptors back towards the client, the ORB calls the exception_occurred on those interceptors, and then returns an exception back to the client application:

•	The return value from any client_invoke operation is REPLY_EXCEPTION.

In this instance, the ORB ceases to propagate the request to remaining interceptors or to the transport. The ORB thus short-circuits the request.

•	The return value from any client_response operation is RESPONSE_EXCEPTION.

In this instance, the interceptor passes an exception back to the ORB, overriding any previous result of the request.

Multiple Target-side Interceptors

As with the client-side interceptor processing, the ORB calls each target-side interceptor’s target_invoke operation in succession. If the return value INVOKE_NO_EXCEPTION is returned from each target_invoke operation, the request is passed onto the target object.

Under the following circumstances, instead of calling the target_response operation on remaining interceptors back towards the client, the ORB calls the exception_occurred on those interceptors, and then returns an exception back towards the client application:

•	The return value from any target_invoke operation is REPLY_EXCEPTION.

In this instance, the ORB ceases to propagate the request to any remaining interceptors and the target object. At this point the ORB returns a response to the client ORB, and the target ORB short-circuits the request.

•	The return value from any target_response operation is RESPONSE_EXCEPTION.

In this instance, the interceptor passes an exception back to the ORB, overriding any previous result of the request.

Interceptors and Meta-Operations

Meta-operations are operations that support the CORBA Object interface, such as is_a, get_interface, and non_existent. Some meta-operations can be performed by the ORB without issuing an invocation, but other operations sometimes need to invoke the object; namely, the is_a, get_interface, and non_existent methods. These operations can thus trigger interceptors.

The CORBA-specified language binding of these operations converts the operation names from the names defined in IDL to the following:

•

_is_a

•	_interface

•	_non_existent (or _not_existent)

If you are implementing a security-based interceptor, be aware of this behavior because the ORB may invoke these operations as part of a client request. You typically should avoid the situation where an interceptor permits only a specific set of client requests to be sent to a target object, but fails to take these meta-operations into account.