Network Filters

What is a Filter?

A filter is a mechanism for plugging into the low-level TCMP stream protocol. Every message that is sent across the network by Coherence is streamed through this protocol. Coherence supports custom filters. By writing a filter, the contents of the network traffic can be modified. The most common examples of modification are encryption and compression. Coherence includes a CompressionFilter which uses the java.util.zip package.

Configuring Filters

There are two steps to configuring a filter. The first is to declare the filter in the <filters> XML element of the tangosol-coherence.xml file:

<filter>
  <filter-name>my-gzip-filter</filter-name>
  <filter-class>com.tangosol.net.CompressionFilter</filter-class>
  <init-params>
    <init-param>
      <param-name>strategy</param-name>
      <param-value>gzip</param-value>
    </init-param>
  </init-params>
</filter>

For more information on the structure of the <filters> XML element of the tangosol-coherence.xml file, see the documentation in the coherence.dtd file, which is also located inside coherence.jar.

The second step is to attach the filter to one or more specific services, or to make the filter global (for all services). To specify the filter for a specific service, for example the ReplicatedCache service, add a <filter-name> element to the <use-filters> element of the service declaration in the tangosol-coherence.xml file:

<service>
  <service-type>ReplicatedCache</service-type>
  <service-component>ReplicatedCache</service-component>
  <use-filters>
    <filter-name>my-gzip-filter</filter-name>
  </use-filters>
  <init-params>
    ...
  </init-params>
</service>

To add the filter to all services, do the same under the <outgoing-message-handler> XML element instead of under a <service> XML element:

<outgoing-message-handler>
  <use-daemon>false</use-daemon>
  <use-filters>
    <filter-name>default-compression</filter-name>
  </use-filters>
</outgoing-message-handler>

Filters should be used in an all-or-nothing manner: If one cluster member is using a filter and other is not, the messaging protocol will fail. You should stop the entire cluster before configuring filters.

Creating a Custom Filter

To create a new filter, create a Java class that implements the com.tangosol.io.WrapperStreamFactory interface and optionally implements the com.tangosol.run.xml.XmlConfigurable interface. The WrapperStreamFactory interface provides the stream to be wrapped ("filtered") on input (received message) or output (sending message) and expects a stream back that wraps the original stream. These methods are called for each incoming and outgoing message.

If the filter class implements the XmlConfigurable interface, then Coherence will configure the filter after instantiating it. For example, consider the following filter declaration in the tangosol-coherence.xml file:

<filter>
  <filter-name>my-gzip-filter</filter-name>
  <filter-class>com.tangosol.net.CompressionFilter</filter-class>
  <init-params>
    <init-param>
      <param-name>strategy</param-name>
      <param-value>gzip</param-value>
    </init-param>
    <init-param>
      <param-name>buffer-length</param-name>
      <param-value>1024</param-value>
    </init-param>
  </init-params>
</filter>

If the filter is associated with a service type, every time a new service is started of that type, Coherence will instantiate the CompressionFilter class and will hold it with the service until the service stops. If the filter is associated with all outgoing messages, Coherence will instantiate the filter on startup and will hold it until the cluster stops. After instantiating the filter, Coherence will call the setConfig method (if the filter implements XmlConfigurable) with the following XML element:

<config>
  <strategy>gzip</strategy>
  <buffer-length>1024</buffer-length>
</config>