.. include:: ../../../router.1.0/srcDoc/vars.rst .. _section-filters: Propagating Content Filters *************************** |RS| can be configured to propagate the content filter information associated with user |DRs| to the user |DWs|. When this functionality is enabled, the user |DWs| receive information about the data sets subscribed to by the user |DRs|. The |DWs| can use that information to do writer-side filtering [#]_ and propagate only the samples belonging to the subscribed data sets. This results in more efficient bandwidth usage as well as in less CPU consumption in the |RS| instances and user |DRs|. :numref:`FigureCommWithoutFilterProp` shows a scenario where communication between |DWs| and |DRs| is relayed through one or more |RSs| that do not propagate content filters. The user |DWs| will send on the wire all the samples they publish, since they cannot make assumptions about what the user |DRs| want. This default behavior incurs unnecessary bandwidth and CPU utilization since the filtering will occur on the DDS |DW| SW\ :sub:`N`\. .. figure:: ../static/RouterFiltersNoProp.svg :figwidth: 90 % :alt: Communication without propagation of content filters :name: FigureCommWithoutFilterProp :align: center Without propagation, user |DWs| send all the samples; filtering occurs on the last route’s |SW| Enabling filter propagation makes it possible to perform writer-side filtering from the user |DWs|, since they receive a composed filter that represents the data set subscribed to by all the user |DRs|, as shown in :numref:`FigureCommWithFilterProp`. .. figure:: ../static/RouterFiltersWithProp.svg :figwidth: 90 % :alt: System Behavior with Filter Propagation :name: FigureCommWithFilterProp :align: center With propagation, user |DWs| receive a composed filter that allows writer-side filtering, thus sending only the samples of interest to the |DRs| .. [#] The ability to perform writer-side filtering is subject to some restrictions. For the sake of this discussion, we will assume that the configuration of |DRs|, |DWs|, and |RSs| is such that writer-side filtering is allowed .. _section-filter-enabling-propagation: Enabling Filter Propagation =========================== Filter propagation is disabled by default in |RS|. You can enable filter propagation with the ```` tag available under the |TR| configuration (see :ref:`section-Config-Route`) and |ATR| configuration (see :ref:`section-Config-AutoRoute`). .. _section-filter-behavior: Filter Propagation Behavior =========================== Without filter propagation, the only way to enforce writer-side filtering in a scenario involving one or more |RSs| between the user |DWs| and user |DRs| is by statically configuring the content filter individually for each DDS |SR|. This method has two main disadvantages: #. It requires knowing beforehand the data set subscribed to by the user |DRs|. #. The filters in the |SRs| are not automatically updated based on changes to the filters in the user |DRs|. This may affect not only bandwidth utilization but also correctness. For example, a user |DR| may not receive a sample because it has been filtered out by one of the |SRs|. Filter propagation can address the above issues by dynamically updating the |SRs| filters. The composed filter associated with a |SR| in a |ROUTE| is built by aggregating the filter information associated with all |DRs| that match the |ROUTE|'s StreamWriter, as shown in :numref:`FigureFilterProp`. .. figure:: ../static/RouterFiltersPropMechanism.svg :figwidth: 90 % :alt: Filter Propagation Through Routing Service :name: FigureFilterProp :align: center Filter Propagation Through Routing Service The composed filter (CF) is the union of the matching |DRs| filters; it allows passing any sample that passes at least one of the |DR| filters. .. math:: CF = {F_1 \cup F_2 ... } \cup F_N For the SQL filter, the union operator is OR: .. math:: CF_{SQL} = {F_{SQL1} \cup F_{SQL2} ...} \cup F_{SQLN} Filter propagation occurs within a |ROUTE| as follows: the |ROUTE| output |SW| gathers the filter information coming from all of its matching |DRs| and provides the resulting composed filter to the |ROUTE| input |SR|, whose |DR| is responsible for sending this information to all of its matching |DWs|. .. _section-filter-events: Filter Propagation Events ========================= The following events will cause a |SR|’s filter to be updated and propagated: - |ROUTE| |SR| *creation*: The initial filter is set to the *stop-band* filter, which is a special kind of filter that does not let any sample pass. This filter is propagated upon |SR| creation and it will remain unchanged until a matching |DR| to the |ROUTE| |SW| is discovered. - *Discovery of a matching* |DR| *in a* |DR|: The filter of the discovered |DR| will be aggregated to the existing |SR|’s filter, which will be propagated after being updated. If the discovered |DR| does not have a filter (subscribes to all the samples) or it has a non-SQL filter, the |SR|’s filter is set to the *all-pass* filter (a special filter that lets all sample pass). The all-pass filter will remain set until there are no matching |DRs| to the |ROUTE| |SW| without a filter or with a non-SQL filter. - *A matching* |DR| *changes its filter, either in the expression or in the parameters*: The |SR|’s filter is updated to incorporate the latest changes and is propagated afterwards. Restrictions ============ Filter propagation cannot be enabled when: - Using |ROUTEs| or |ARs|, since they are meant to work with other adapters different than the builtin DDS one. - A transformation is present in the |TR|'s output. - Using remote administration, if the |TR| was enabled and started with filter propagation initially disabled. - If the |SR|'s *ContentFilter* class is not the builtin SQL filter. Filter propagation is not currently supported with other filter classes.