geode-docs/developing/events/filtering_multisite_events.html.md.erb

---
title:  Filtering Events for Multi-Site (WAN) Distribution
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

You can optionally create gateway sender and/or gateway receiver filters to control which events are queued and distributed to a remote site, or to modify the data stream that is transmitted between <%=vars.product_name%> sites.

You can implement and deploy two different types of filter for multi-site events:

-   `GatewayEventFilter`. A `GatewayEventFilter` implementation determines whether a region event is placed in a gateway sender queue and/or whether an event in a gateway queue is distributed to a remote site. You can optionally add one or more `GatewayEventFilter` implementations to a gateway sender, etiher in the `cache.xml` configuration file or using the Java API.

    <%=vars.product_name%> makes a synchronous call to the filter's `beforeEnqueue` method before it places a region event in the gateway sender queue. The filter returns a boolean value that specifies whether the event should be added to the queue.

    <%=vars.product_name%> asynchronously calls the filter's `beforeTransmit` method to determine whether the gateway sender dispatcher thread should distribute the event to a remote gateway receiver.

    For events that are distributed to another site, <%=vars.product_name%> calls the listener's `afterAcknowledgement` method to indicate that is has received an ack from the remote site after the event was received.

-   GatewayTransportFilter. Use a `GatewayTransportFilter` implementation to process the TCP stream that sends a batch of events that is distributed from one <%=vars.product_name%> cluster to another over a WAN. A `GatewayTransportFilter` is typically used to perform encryption or compression on the data that distributed. You install the same `GatewayTransportFilter` implementation on both a gateway sender and gateway receiver.

    When a gateway sender processes a batch of events for distribution, <%=vars.product_name%> delivers the stream to the `getInputStream` method of a configured `GatewayTransportFilter` implementation. The filter processes and returns the stream, which is then transmitted to the gateway receiver. When the gateway receiver receives the batch, <%=vars.product_name%> calls the `getOutputStream` method of a configured filter, which again processes and returns the stream so that the events can be applied in the local cluster.

## <a id="topic_E97BB68748F14987916CD1A50E4B4542__section_E20B4A8A98FD4EDAAA8C14B8059AA7F7" class="no-quick-link"></a>Configuring Multi-Site Event Filters

You install a `GatewayEventFilter` implementation to a configured gateway sender in order to decide which events are queued and distributed. You install a `GatewayTransportFilter` implementation to both a gateway sender and a gateway receiver to process the stream of batched events that are distributed between two sites:

-   **XML example**

    ``` pre
    <cache>
      <gateway-sender id="remoteA" parallel="true" remote-distributed-system-id="1"> 
        <gateway-event-filter>
          <class-name>org.apache.geode.util.SampleEventFilter</class-name>
          <parameter name="param1">
            <string>"value1"</string>
          </parameter>
        </gateway-event-filter>
        <gateway-transport-filter>
          <class-name>org.apache.geode.util.SampleTransportFilter</class-name>
          <parameter name="param1">
            <string>"value1"</string>
          </parameter>
        </gateway-transport-filter>
      </gateway-sender> 
    </cache>
    ```

    ``` pre
    <cache>
      ...
      <gateway-receiver start-port="1530" end-port="1551"> 
        <gateway-transport-filter>
          <class-name>org.apache.geode.util.SampleTransportFilter</class-name>
          <parameter name="param1">
            <string>"value1"</string>
          </parameter>
        </gateway-transport-filter>
      </gateway-receiver>
    </cache>
    ```

-   **gfsh example**

    ``` pre
    gfsh>create gateway-sender --id=remoteA --parallel=true --remote-distributed-id="1" 
    --gateway-event-filter=org.apache.geode.util.SampleEventFilter 
    --gateway-transport-filter=org.apache.geode.util.SampleTransportFilter
    ```

    See [create gateway-sender](../../tools_modules/gfsh/command-pages/create.html#topic_hg2_bjz_ck).

    ``` pre
    gfsh>create gateway-receiver --start-port=1530 --end-port=1551 \
    --gateway-transport-filter=org.apache.geode.util.SampleTransportFilter
    ```

    **Note:**
    You cannot specify parameters and values for the Java class you specify with the `--gateway-transport-filter` option.

    See [create gateway-receiver](../../tools_modules/gfsh/command-pages/create.html#topic_a4x_pb1_dk).

-   **API example**

    ``` pre
    Cache cache = new CacheFactory().create();

    GatewayEventFilter efilter = new SampleEventFilter();
    GatewayTransportFilter tfilter = new SampleTransportFilter();

    GatewaySenderFactory gateway = cache.createGatewaySenderFactory();
    gateway.setParallel(true);
    gateway.addGatewayEventFilter(efilter);
    gateway.addTransportFilter(tfilter);
    GatewaySender sender = gateway.create("remoteA", "1");
    sender.start();
    ```

    ``` pre
    Cache cache = new CacheFactory().create();

    GatewayTransportFilter tfilter = new SampleTransportFilter();

    GatewayReceiverFactory gateway = cache.createGatewayReceiverFactory();
    gateway.setStartPort(1530);
    gateway.setEndPort(1551);
    gateway.addTransportFilter(tfilter);
    GatewayReceiver receiver = gateway.create();
    receiver.start();
    ```