RTI Connext Java API Version 7.3.0
|
Working with custom content filters.
Working with custom content filters.
By default, RTI Connext creates content filters with the DDS_SQL_FILTER, which implements a superset of the DDS-specified SQL WHERE clause. However, in many cases this filter may not be what you want. Some examples are:
This HOWTO explains how to write your own custom filter and is divided into the following sections:
A custom content filter is created by calling the com.rti.dds.domain.DomainParticipant.register_contentfilter function with a com.rti.dds.topic.ContentFilter that contains a compile, an evaluate function and a finalize function. com.rti.dds.topic.ContentFilteredTopic can be created with com.rti.dds.domain.DomainParticipant.create_contentfilteredtopic_with_filter to use this filter.
A custom content filter is used by RTI Connext at the following times during the life-time of a com.rti.dds.topic.ContentFilteredTopic (the function called is shown in parenthesis).
The compile function is used to compile a filter expression and expression parameters. Please note that the term compile is intentionally loosely defined. It is up to the user to decide what this function should do and return.
See com.rti.dds.topic.ContentFilter.compile for details.
The evaluate function is called each time a sample is received to determine if a sample should be filtered out and discarded.
See com.rti.dds.topic.ContentFilter.evaluate for details.
The finalize function is called when an instance of the custom content filter is no longer needed. When this function is called, it is safe to free all resources used by this particular instance of the custom content filter.
See com.rti.dds.topic.ContentFilter.finalize for details.
Assume that you have a type Foo.
You want to write a custom filter function that will drop all samples where the value of Foo.x > x and x is a value determined by an expression parameter. The filter will only be used to filter samples of type Foo.
The first thing to note is that we can ignore the filter expression, since we already know what the expression is. The second is that x is a parameter that can be changed. By using this information, the compile function is very easy to implement. Simply return the parameter string. This string will then be passed to the evaluate function every time a sample of this type is filtered.
Below is the entire compile function.
The next step is to implement the evaluate function. The evaluate function receives the parameter string with the actual value to test against. Thus the evaluate function must read the actual value from the parameter string before evaluating the expression. Below is the entire evaluate function.
The last function to write is the finalize function. It is safe to free all resources used by this particular instance of the custom content filter that is allocated in compile. Below is the entire finalize function.
Before the custom filter can be used, it must be registered with RTI Connext:
When the filter is no longer needed, it can be unregistered from RTI Connext: