Product: OpenFusion Notification Service

Version: ALL

Description:

Why use Custom Filters?

Resolution:

One of the main advantages of custom filters is that they can provide large performance gains over using the EXTENDED_TCL language.

The custom filter would be used for a situation where the designer is aware of the specific nature/structure of the events being sent, and can write a filter based specifically on this information.
Another advantage of a custom filter is that it allows for filtering that can not be easily achieved with e.g. the TCL grammar. One example of this would be an event that has data in a tree-like structure in the filterable body of the event. Such a structure would be hard to filter using a constraint expression, but can be filtered as required through the use of code in a custom filter.

Design considerations

A critical aspect of custom filters is that they can become very specific (e.g. based around a certain event structure). The advantage is that it allows more powerful filtering to be done in cases where the TCL grammar is not sufficient. The disadvantage is that such a custom filter can become too specific, and only handle one certain type of event.

The filters that accept the EXTENDED_TCL as a valid grammar require a lot of error and type checking. This is because these types of filters are intended for use with almost any types of event. Although it may be more appropriate to write a different custom filter for every event with a different event structure, this does not have to be the case. If this is done, many small custom filters that will only filter on a very small set of event structures will have to be produced. However, writing many small custom filters may not be the best solution.
An alternative would be to write a custom filter for differing event types. This is not to say that a custom filter should only be designed for use with one event type, but it may support two or three event types. In this way, the filter can subscribe to certain event types. This means that it can tell important objects that pass the events onto the filter to only pass events of a certain event type to the filter. This can make designing custom filters a lot less complicated since you are certain except for certain universal event types only to receive events of the filters subscribed types. If each event type has a static structure then it is very easy to filter on the data of the events that the filter will receive.

Constraints

It is possible to change the behaviour of a filter at run-time. This is done by dynamically changing the set of constraints that a filter encapsulates. A constraint is an expression that the filter is designed to parse and understand. The expression is of type string. The filter then uses the constraints and compares them with each event that it is given. The way in which the comparison occurs is entirely dependant on the custom filter. Each custom filter will only understand a certain filter language, and the language can include anything that can be expressed as a string. The constraints that are to be associated with the filter must then be made up of elements taken from the filter language.

Custom Filter Structure

The structure of a custom filter is split into three sets of methods, with one exception. The three sets are:

• Methods used to change the constraints currently associated with the filter
• Methods used to change the subscribers for the filter
• Methods used by the NotificationService to determine if an event satisfies any of the constraints currently associated with the filter match methods.

The one exception is a method that allows a client to query the grammar that the filter is using to evaluate events with the constraints. The method to return the grammar being used by the filter is called constraint_grammar and it takes no parameters and returns a string that is the name of the language the filter is currently associated with.

Constraint Methods

There are five constraint methods: add_constraints, modify_constraints, get_constraints, get_all_constraints, remove_all_constraints.

Constraints are organised within the filter as a list such that each constraint must be associated with a unique ID. This ID is a number. The reason for this is that clients using the filter must be able to refer to the constraints, and there must be a mechanism for ensuring that the clients can uniquely refer to constraints.

add_constraints
This method is used to dynamically add constraints to this filter object. The constraints have to be within the confines of the language currently being used by the filter. If the confines are not met then the method is able to refuse the constraints and the set of constraints that is associated with the filter must remain unchanged.

modify_constraints
This method can be used to remove and change constraints that are associated with the filter. The method accepts two parameters: a list of ID's, and a list of constraint information. The list of ID's is used to specify which constraints that are currently associated with the filter should be removed. All of the ID's that are supplied should be one of the unique identifiers that is currently associated with the filter object. If one of them is not the method can reject the ID list, and leave the constraint list associated with the filter unchanged. The second parameter is a list of constraint information. The information consists of a constraint expression and a number that is intended to be a unique identifier. The purpose of this information is to change one of the constraints currently associated with the filter. One element of the constraint information will contain the ID of the existing constraint that is to be changed, and a constraint expression that the constraint with the ID is to be changed to. If any of the ID's supplied in the constraint information does not exist, then the method can reject the modify request and leave the constraint list unchanged. Similarly, if any of the constraint expressions given in the constraint information list is not a valid constraint within the constraint language currently associated with the filter object, the method can reject the request to modify the constraint list, and leave the constraint list unchanged.

get_constraints
This method accepts a list of unique ID's. The method will return all the constraint expressions that are currently associated with the unique ID list, along with their unique ID's in the form of a constraint information list. If any of the supplied ID's do not exist, then the method can reject the request to get the constraint information.

get_all_constraints
This method will return all the constraints that are currently associated with this filter object in the form of a constraint information list. Each element in the list consists of a constraint expression and a unique ID that is associated with the constraint.

remove_all_constraints
This method will remove all the constraints that are currently associated with the filter object.

Subscriber Methods

There are three subscriber methods: attach_callback , detach_callback and get_callbacks.
The filter should maintain a list of subscribers. At the very least, the NotificationService will attach itself to the filter object. As explained before, the custom filter will normally only be interested in certain event type. The mechanism of subscribers allows the filter to tell it's attached subscribers which event types it is interested in. If this is done, it will be certain to only receive events of that type. This takes a lot of business logic out of the filter, and allows the filter to concentrate on the filtering logic.
There is one exception to this rule: An event type that has a domain_name and type_name set to the empty string is considered a universal event type. This event type is therefore always passed onto the filter even if the filter has not subscribed to it in any of it's subscribers.

attach_callback
This method takes a parameter that is a subscriber. The filter should identify which event types it is interested in and then add the filter to the current list of attached callbacks. There should be a unique identifier associated with each callback, so clients are able to identify each individual callback. As such, this method should return the unique identifier that it has given to this callback.

detach_callback
This method takes a parameter that is intended to be one of the unique identifiers of one of the callbacks currently in the filters list of callbacks. If the unique identifier does not exist, then the method should reject the request to detach a callback, and leave it's list of attached callbacks unchanged. If successful, however, the method should remove the callback associated with the given unique identifier from its list of callbacks currently associated with the filter.

get_callbacks
This method should return a list of unique identifiers associated with all the callbacks currently attached to this filter object.

Match methods

There are three match methods: match, match_structured , match_typed.
The match methods are used by the NotificationService to determine what an event that qualifies for filtering evaluates to. The match methods should return false if the event supplied to the method should be filtered and true if the event passes through the filter. The match methods should contain all the filtering logic specific to the custom filter. How the filter is implemented depends entirely on the design of the custom filter. It can effectively do anything it likes as long as the method returns a boolean value. One custom filter match methods may be completely different to another custom filters match methods, so the details of the methods is not given here. If the match methods are given an event that it is not supposed to filter for example, the structure of the event might not be the structure it was expecting then the methods are able to reject the evaluation of the event, and return neither true nor false.

match
The match method is used to evaluate an event passed to the NotificationService in the form of a org.omg.CORBA.Any object. The method takes a CORBA.Any object that represents the event sent to the NotificationService. The method can then perform evaluation of the event against all the constraints currently associated with the filter object, and return a boolean value depending on the result of the evaluation. As said before, the method is able to do anything it likes, hence it is not restricted to using the list of constraints currently associated with the filter. It is able to perform evaluation dependent on some other variable or the evaluation can be completely static

match_structured
The match_structured method is used to evaluate an event passed to the NotificationService in the form of a org.omg.CosNotification.StructuredEvent object. The method takes a CosNotification.StructuredEvent object that represents the event sent to the NotificationService. The method can then perform evaluation of the event against all the constraints currently associated with the filter object, and return a boolean value depending on the result of the evaluation. As said before, the method is able to do anything it likes, hence it is not restricted to using the list of constraints currently associated with the filter. It is able to perform evaluation dependent on some other variable or the evaluation can be completely static In the case of StructuredEvents, the evaluation should be performed only on the filterable_body section of the StructuredEvent except in a few cases. The filterable_data section of the event should be filled in by a supplier that supplies events to the channel with data that should be used by filters. The few exceptions are important filtering information that is normally used by the NotificationService. An example of this is the priority of an event, which is stored in the variable_header section of a StructuredEvent.

match_typed
This method is used by the NotificationService to evaluate typed events, i.e. it is used to evaluate an event passed to the NotificationService in the form of a org.omg.CORBA.Any object. The method takes a sequence of Property objects that represents the event sent to the TypedNotificationService. The method can then perform evaluation of the event against all the constraints currently associated with the filter object, and return a boolean value depending on the result of the evaluation. As said before, the method is able to do anything it likes, hence it is not restricted to using the list of constraints currently associated with the filter. It is able to perform evaluation dependent on some other variable or the evaluation can be completely static An important piece of information that needs to be noted is that, in this case, the first element in the Property list passed as an input parameter is always filled with information describing the typed event type. Unless this itself is information that needs to be filtered, it can safely be ignored. An example of a simple custom filter is available. If you would like to receive the SimpleTCLFilter example please log a ticket in our web support system requesting this information.