Contents

21.1 Introduction to Per-process Filters

21.2 Introduction to Per-Object Filters

21.3 Per-Process Filters

21.3.1 An Example Per-Process Filter

21.3.2 Installation of Per-Process Filter

21.3.3 Raising an Exception in a Filter

21.3.4 Piggybacking Extra Data to the Request Buffer

21.3.5 Retrieving the Size of a Request Buffer

21.3.6 Defining an Authentication Filter

21.4 Per-Object Filters

21.4.1 IDL Compiler Switch to Enable Object Filtering

There are two forms of filters: per-process and per-object filters. Per-process filters see all operation and attribute calls leaving or entering a client's or server's address space, irrespective of the target object. Per-object filters apply to individual objects. Both of these filter types are illustrated in Figure 21.1.

Figure 21.1: Per-process and per-object filtering

Note that use of the Dynamic Invocation Interface does not by-pass the filtering mechanism: calls made using the DII will result in the use of all appropriate outgoing and incoming filters, except the filter point in reply post marshal. This filter point must be handled explicitly by a DII programmer, as described in section 19.6.

21.1 Introduction to Per-process Filters

• Defining a class which inherits from class Filter (defined in package IE.Iona.Orbix2.CORBA).
  
• Creating a single instance of the new class.
  

• out request pre marshal: [in the caller's address space] before an operation or attribute request is transmitted from the filter's address space to any object in another address space; in particular, before the operation's parameters have been added to the request packet.
  
• in request pre marshal: [in the target object's address space] once an operation or attribute request has arrived at the filter's address space, but before it has been processed; in particular, before the operation has been sent to the target object and before the operation's parameters have been removed from the request packet.
  
• out reply pre marshal: [in the target object's address space] after the operation or attribute request has been processed by the target object, but before the result has been transmitted to the caller's address space; in particular, before an operation's out parameters and return value have been added to the reply packet.
  
• in reply pre marshal: [in the caller's address space] after the result of an operation or attribute request has arrived at the filter's address space, but before the result has been processed; in particular, before an operation's return parameters and return value have been removed from the reply packet.
  

• out request post marshal: [in the caller's address space] same as `out request pre marshal' but after the operation's parameters have been added to the request packet.
  
• in request post marshal: [in the target object's address space] same as `in request pre marshal' but after the operation's parameters have been removed from the request packet.
  
• out reply post marshal: [in the target object's address space] same as `out reply pre marshal' but after the operation's out parameters and return value have been added to the reply packet.
  
• in reply post marshal: [in the caller's address space] same as `in reply pre marshal' but after the operation's out parameters and return value have been removed from the reply packet.
  

• out reply failure: [in the target object's address space] this is called if the target object raises an exception or if any preceding filter point (`in request' or `out reply') raises an exception or uses its return value to indicate that the call should not be processed any further.
  
• in reply failure: [in the caller's address space] this is called if the target object raises an exception or if any preceding filter point (`out request', `in request', `out reply' or `in reply') raises an exception or uses its return value to indicate that the call should not be processed any further.
  

All monitor points (eight marshalling points and two failure points) are shown in Figure 21.2.

Figure 15.2: Per-process monitor points

A particular filter on the per-process filter chain may perform actions for any number of these filter points, although it is common to handle four filter points, for example:

out request pre marshal

in request pre marshal

out reply pre marshal

in reply pre marshal

Each filter point must indicate how the handling of the request should be continued once the filter point itself has completed. In particular, a filter point can determine whether or not OrbixWeb is to continue to process the request or to return an exception to the caller.

Since per-process filters are applied only when an invocation leaves or arrives at an address space, they are not informed of invocations between collocated objects.

Note that a special form of per-process filters can be used to pass authentication information from a client to a server. This type of filter is called an authentication filter, and it supports the verification of the identity of a caller, which is a fundamental requirement for security. Authentication filters are discussed in section 21.3.6.

21.2 Introduction to Per-Object Filters

• per-object pre: a filter applied to operation invocations on a particular object–before they are passed to the target object.
  
• per-object post: a filter applied to operation invocations on a particular object–after they have been processed by the target object.
  

Per-object filters are created by carrying out the following three steps:

• Derive a new class from the IDL generated class which bears the same name as the target object's IDL interface (for example, inherit from class Grid for an object which implements interface Grid).
  
• Create an instance of this new class. This instance behaves as a per-object filter when it is installed.
  
• Install this filter object as either a pre filter or as a post filter to a particular target object.
  

An object can have a chain of pre-filters and/or a chain of post-filters. For example, a chain of pre-filters can be constructed by attaching a pre-filter to the object, then attaching a pre-filter to that filter, and so on.

Note that per-object filtering can only be used if it was enabled when the corresponding IDL interface was compiled by the IDL compiler (see section 21.4.1).

The parameters to an IDL operation request are readily available for both pre and post per-object filters. Any in and inout parameters are valid for pre filters; in, out and inout parameters and return values are valid for post filters. In contrast, for per-process filters, parameters to the operation request are not in general available.

The per-process `in request' (both pre and post marshal) filters are applied before any per-object pre-filter. The per-object post-filters are applied before any per-process `out reply' (both pre and post marshal) filters.

The remainder of this chapter presents, in turn, the details of per-process and per-object filters.

21.3 Per-Process Filters

Each of these methods takes a single parameter; the marshalling methods (the methods not concerned with failure) return a boolean value to indicate whether or not OrbixWeb should continue to make the request. For example

 public boolean outRequestPreMarshal(Request r)
 	throws IE.Iona.Orbix2.CORBA.SystemException;

The details of the request being made can be obtained by calling methods on the Request parameter (class Request is defined in package IE.Iona.Orbix2.CORBA). Examples of this are shown in section 21.3.1.

Full details of these methods are given inPart II, "Class and Interface Reference" of the OrbixWeb Reference Guide.

The constructor of class Filter adds the newly created filter object into the per-process filter chain. Direct instances of Filter cannot be created (the constructor is protected to enforce this). Derived classes of Filter will normally have public constructors.

Note that each method (except the two failure methods) returns a value to indicate how the call should continue. Redefinitions of these methods in a derived class should retain the same semantics for the return value as specified in the relevant entries in the OrbixWeb Reference Guide.

Programmers should define derived classes of Filter and redefine some subset of the filter point methods to carry out the required filtering. If any of the non-failure monitoring methods is not redefined in a derived class of Filter, then the following implementation is inherited in all cases:

 // Java
 { return true; } // Continue the call.

 // Java
 { return; }

21.3.1 An Example Per-Process Filter

 // Java
 
 import IE.Iona.Orbix2.CORBA.Filter;
 import IE.Iona.Orbix2.CORBA.Request;
 import IE.Iona.Orbix2.CORBA.SystemException;
 
 public class ProcessFilter extends Filter {
 	public boolean 
 		outRequestPreMarshal (Request r) {
 		String s, o;
 		try {
 			s = (r.target ())._object_to_string ();
 			o = r.operation ();
 		}
 		catch (SystemException se) {
 			...
 		}
 		System.out.println ("Request outgoing to "
 			+ s + " with operation name "
 			+ o + ".");
 		return true; // continue the call
 	}
 
 	boolean inRequestPreMarshal (Request r) {
 		String s, o;
 		try {
 			s = (r.target ())._object_to_string ();
 			o = r.operation ();
 		}
 		catch (SystemException se) {
 			...
 		}
 		System.out.println ("Request incoming to "
 			+ s + " with operation name "
 			+ o + ".");
 		return true; // continue the call
 
 	boolean outReplyPreMarshal (Request r) {
 		String o;
 		try {
 			o = r.operation ();
 		}
 		catch (SystemException se) {
 			...
 		}
 		System.out.println ("Incoming operation "
 			+ o + " finished.");
 		return true; // Continue the call.
 	}
 
 	boolean inReplyPreMarshal (Request r) {
 		String o;
 		try {
 			o = r.operation ();
 		}
 		catch (SystemException se) {
 			...
 		}
 		System.out.println ("Outgoing operation "
 			+ o + " finished.");
 		return true; // Continue the call.
 	}
 
 	void outReplyFailure (Request r) {
 		String o;
 		try {
 			o = r.operation ();
 		}
 		catch (SystemException se) {
 			...
 		}
 		System.out.println ("Operation "
 			+ o + " raised exception.");
 		return;
 	}
 
 	void inReplyFailure (Request r) {
 		String o;
 		try {
 			o = r.operation ();
 		}
 		catch (SystemException se) {
 			...
 		}
 		System.out.println ("Operation "
 			+ o + " raised exception.");
 		return;
 	}
 }

The method target() can be applied to a Request to find the object reference of the target object; and the method _object_to_string() can be applied to an object reference to get a string form of an object reference. The method operation() can be applied to a Request to find the name of the operation being called.

21.3.2 Installation of Per-Process Filter

 // Java
 ProcessFilter myFilter = new ProcessFilter ();

21.3.3 Raising an Exception in a Filter

 public boolean outRequestPostMarshal(Request r){
 	if (...) {
 		IE.Iona.Orbix2.CORBA.NO_PERMISSION ex =
 			new IE.Iona.Orbix2.CORBA.NO_PERMISSION(0,
 			IE.Iona.Orbix2.CORBA.CompletionStatus.NO);
 
 		throw ex;
 
 		// The NO_PERMISSION system exception 
 		// has been  raised here, with a
 		// completion status of NO.
 	}
 	...
 }

• Per-process filters can raise only system exceptions. Any such exception is propagated by OrbixWeb back to the caller. However, raising an exception in an inReplyPostMarshal() filter point does not cause the exception to be propagated: at that stage, the invocation is essentially already completed and it is too late to raise an exception.
  
• If any filter point raises an exception, then no further filter points are processed for that invocation, except for one or both of the failure filter points, outReplyFailure() and inReplyFailure().
  
• If one of the filter points
  

   outRequestPreMarshal()
   outRequestPostMarshal()
   inRequestPreMarshal()
   inRequestPostMarshal()
  

raises an exception then the actual operation call is not forwarded to the target application object.

• If the operation implementation raises a user exception and one of the filter points
  

   outReplyFailure()
   inReplyFailure()
  

raises a system exception then the system exception is raised in the calling client (that is, the user exception is overwritten). The programmer of a filter may wish to test whether an exception has already been raised before raising one in the filter. This can be done simply by the Request.isException() method, for example:

 // Java
 if (r.isException()) {
 	// Have exception already.
 }

• If the operation implementation raises a system exception then no further filter points, except one or both of outReplyFailure() and inReplyFailure() are called for this invocation.
  

At each of the four `out' marshalling monitor points, data can be added by using an appropriate insert() method for the Request parameter, for example:

 // Java
 long l = 27;
 ...
 try {
 	r.insertLong (l);
 }
 catch (IE.Iona.Orbix2.CORBA.SystemException se) {
 	...
 }

At each of the `in' marshalling monitor points, data can be extracted using an appropriate extract() method, for example,

 // Java
 long j;
 ...
 try {
 	j = r.extractLong ();
 }
 catch (IE.Iona.Orbix2.CORBA.SystemException se) {
 	...
 }

Care must be taken to correctly match the insertion and extraction points, as follows:

outRequestPreMarshal() matches inRequestPreMarshal()

outReplyPreMarshal() matches inReplyPreMarshal()

outRequestPostMarshal() matches inRequestPostMarshal()

outReplyPostMarshal() matches inReplyPostMarshal()

When only one filter is being used, its outRequestPostMarshal() method can add piggybacked data that the corresponding inRequestPostMarshal() method, on the called side, does not remove. However this would cause problems if more that one filter was being used.

Ensuring that Unexpected Extra Data is not Passed

For example, it will be necessary to include the following code in outRequestPreMarshal() and outRequestPostMarshal() (assuming the Request parameter is r):

 // Java
 // First find the server name:
 String impl;
 
 try {
 	impl = (r.target ())._get_implementation ();
 }
 catch (IE.Iona.Orbix2.CORBA.SystemException se) {
 	...
 }
 
 if (impl.equals ("some_server")) {
 	// Can add extra data.
 }
 else {
 	// Do not add any extra data.
 }

A programmer should be particularly careful not to add data when communicating with the OrbixWeb daemon, IT_daemon. The OrbixWeb classes may communicate with the daemon process, and programmers of filters should ensure that they do not pass extra data to the daemon.

21.3.5 Retrieving the Size of a Request Buffer

 // Java
 int msgLen;
 
 try {
 	msgLen = r.getMessageLength ();
 }
 catch (IE.Iona.Orbix2.CORBA.SystemException se) {
 	...
 }

 // Java
 // in package IE.Iona.Orbix2.CORBA,
 // in class BOA.
 
 public String get_principal 
 	(IE.Iona.Orbix2.CORBA._ObjectRef oref)
 	throws SystemException;

The default authentication filter can be overridden by declaring a derived class of AuthenticationFilter and creating an instance of this class. For example, an alternative authentication filter may use a ticket based authentication system rather than passing the caller's user name.

On the client side, a derived AuthenticationFilter class should override the outRequestPreMarshal() filter point. If this filter point alters the default behaviour, then the server-side authentication filter point inRequestPreMarshal() must be appropriately overridden in all servers with which the client communicates.

21.4 Per-Object Filters

 // IDL
 interface Inc {
 	unsigned long increment(in unsigned long vin);
 };

 // Java
 public class IncImplementation
 	implements _IncOperations {
 	public int increment (int vin)
 		throws IE.Iona.Orbix2.CORBA.SystemException {
 		return (vin+1); 
 	}
 }

 // Java
 Inc.Ref i1, i2;
 
 try {
 	i1 = new _tie_Inc (new IncImplementation ());
 	i2 = new _tie_Inc (new IncImplementation ());
 }
 catch (IE.Iona.Orbix2.CORBA.SystemException se) {
 	...
 }

To perform pre-filtering, the programmer could define a class, say FilterPre, to have the same methods and parameters as a normal implementation class of the corresponding IDL type, and which inherits from the generated class of the same name as the IDL type:

 // Java
 public class FilterPre 
 	extends Inc {
 	public int increment (int vin)
 		throws IE.Iona.Orbix2.CORBA.SystemException {
 		System.out.println 
 			("*** PRE call with parameter " + vin);
 		return 0; // Here any value will do.
 	}
 }

 // Java
 public class FilterPost
 	extends Inc {
 	public int increment (int vin)
 		throws IE.Iona.Orbix2.CORBA.SystemException {
 		System.out.println 
 			("*** POST call with parameter " + vin);
 		return 0; // Here any value will do.
 	}
 }

To apply filters to a specific object, the following should be done:

 // Java
 // Create two filter objects.
 Inc.Ref serverPre, serverPost;
 
 try {
 	serverPre = new _tie_Inc (new FilterPre ());
 	serverPost = new _tie_Inc (new FilterPost ());
 
 // Attach the two filter objects to 
 // the target object pointed to by i1.
 i1._attachPre (serverPre);
 i1._attachPost (serverPost);

Attaching a pre-filter to an object which already has a pre-filter causes the old filter to be removed and the new one to be attached. The same applies to a post filter.

The methods _attachPre() and _attachPost() return, respectively, the previous pre-filter and post-filter, if any, attached to the object. The methods _getPre() and _getPost() return an object's pre-filter and post-filter, respectively.

To attach a chain of per-object pre-filters to an object, _attachPre() can be used to attach the first pre-filter, and then it can be used again to attach a pre-filter to the first pre-filter, and so on. The same applies to post-filters.

If a per-object pre-filter raises an exception in the normal way, then the actual operation call will not be made. Normally this exception is returned to the client to indicate the outcome of the invocation. However, if the pre-filter raises the exception FILTER_SUPPRESS then no exception is returned to the caller¹–the caller cannot tell that the operation call has not been processed as normal.

In the example above, the same filter objects (those pointed to by serverPre and serverPost) could be used to filter invocations to many objects. Other filters, for example a filter holding a pointer to the object it is filtering, can only be used to filter one object.

21.4.1 IDL Compiler Switch to Enable Object Filtering

 // Java
 import IE.Iona.Orbix2.CORBA.FILTER_SUPPRESS;
 import IE.Iona.Orbix2.CORBA.CompletionStatus;
 ...
 
 throw new FILTER_SUPPRESS(0, CompletionStatus.NO);