RTI Connext Java API  Version 5.1.0
Creating Custom Content Filters

Working with custom content filters. More...

Working with custom content filters.

Introduction

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:

The Custom Content Filter API

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

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

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

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.

Example Using C format strings

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.

Writing the Compile Function

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.

public void compile(
ObjectHolder new_compile_data, String expression,
StringSeq parameters, TypeCode type_code, String type_class_name,
Object old_compile_data) {
new_compile_data.value = parameters.get(0);
}

Writing the Evaluate 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.

public boolean evaluate(
Object compile_data, Object sample, FilterSampleInfo meta_data) {
String parameter = (String)compile_data;
int x;
Foo foo_sample = (Foo)sample;
x = Integer.parseInt(parameter);
return (foo_sample.x > x ? false : true);
}

Writing the Finalize 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.

public void finalize(
Object compile_data) {
/* nothing to do since no resource are allocated */
}

Registering the Filter

Before the custom filter can be used, it must be registered with RTI Connext:

ContentFilter myCustomFilter = new MyContentFilter();
participant.register_contentfilter("MyCustomFilter", myCustomFilter);

Unregistering the Filter

When the filter is no longer needed, it can be unregistered from RTI Connext:

participant.unregister_contentfilter("MyCustomFilter");


RTI Connext Java API Version 5.1.0 Copyright © Mon Feb 3 2014 Real-Time Innovations, Inc