|
|
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 WLE (WLE) application. When you have an interceptor installed and registered with an ORB on a particular machine, the interceptor is involved with all the WLE 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 WLE environment. Implementing them is considered an advanced programming task.
The WLE system supports two categories of interceptors:
The WLE 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, in C++ it is often convenient to implement the interceptors in a single source file. In the Java programming language, the client- and target-side interceptors must be implemented separately; however, the implementations for both interceptors can be packaged together.
The following figure shows the relationship between request-level interceptors and the WLE system.
Note the following about WLE interceptors:
Interceptor Architecture
During the course of a single, successful request-response cycle of an invocation, a client-side interceptor is called twice by the ORB:
During the course of a single request-response cycle of an invocation, a target-side interceptor is called twice by the ORB:
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.
Request-level interceptors are especially useful for implementing several different types of service applications, such as:
Capabilities and Limitations
The following are current limitations on WLE interceptors:
These interfaces are not used in the WLE 5.0 product. These interfaces are defined in the WLE software so that you do not need to recompile your WLE application if an implementation of these interfaces is ever provided in a future release of WLE. 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.
The following sections explain what happens during the execution of an application in a WLE environment 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:
Execution Flow
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:
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-side Execution
The flow of execution of a WLE 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).
In Figure 1-1, note the following events that are called out:
Figure 1-1 Client-side Interceptor
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.
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-side Execution
The flow of execution of a WLE 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).
In Figure 1-2, note the following events that are called out:
Figure 1-2 Target-side Interceptor
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.
Every interceptor has the exception_occurred
method, which the ORB may call under the following circumstances:
The exception_occurred Method
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 sections Implementing the Interceptor's Response Operation (C++) or Implementing the Interceptor's Response Operation (Java).
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.
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.)
In Figure 1-3, note the following events that are called out:
About Short-Circuit Behavior
Using Multiple Request-Level Interceptors
Figure 1-3 Multiple Interceptors on an ORB
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:
In this instance, the ORB ceases to propagate the request to remaining interceptors or to the transport. The ORB thus short-circuits the request.
In this instance, the interceptor passes an exception back to the ORB, overriding any previous result of the request.
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:
Multiple Target-side Interceptors
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.
In this instance, the interceptor passes an exception back to the ORB, overriding any previous result of the request.
Interceptors implemented in C++ can be invoked only by client applications or other entities that are also implemented in C++, and likewise for Java. If your WLE application contains both C++ and Java entities that need to be intercepted, you need to implement the interceptors in both languages and register them individually.
Note the following behavior about interceptors implemented in Java:
Interceptors and Implementation Languages
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:
Interceptors and Meta-operations
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.
|
Copyright © 1999 BEA Systems, Inc. All rights reserved.
|