content/documentation/extensions/mod_filter.adoc

:jbake-type: page
:jbake-status: published

= Apache Tamaya - Extension: User Filtering

toc::[]


[[Filter]]
== User Filtering (Extension Module)

Tamaya _Filter_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.


=== What functionality this module provides ?

Tamaya _Filter_ provides a simple singleton accessor that allows to explicitly add +PropertyFilter+ instances
active on the current thread only. This can be very useful in many scenarios, especially within
Java EE web filters or similar. Additionally this module adds
standard filters that hide metadata entries when the full configuration map is accessed. When keys are accessed
explicitily no filtering is applied and everything is visible.

=== Compatibility

The module is based on Java 8.


=== Installation

To benefit from filter support you only must add the corresponding dependency to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-filter</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== The Extensions Provided

Tamaya Filter comes basically with 3 artifacts:

* The +org.apache.tamaya.filter.ThreadBasedConfigurationFilter+ provides several static methods to register +PropertyFilter+
instances on the current thread.
* The +org.apache.tamaya.filter.ThreadFilterContext+ is a +PropertyFilter+ with hides all entries starting with
 an underscore ('_'), when a full property map is accessed.


==== The ConfigurationFilter

The accessor mentioned implements the API for for adding +PropertyFilters+ to the current thread (as thread local):

[source, java]
-----------------------------------------------
public final class ConfigurationFilter implements PropertyFilter{

    ...

    /**
     * Seactivates metadata filtering also on global map access for this thread.
     * @see #clearFilters()
     * @param active true,to enable metadata filtering (default).
     */
    public static void setFilterMetadata(boolean active);

    /**
     * Access the filtering configuration that is used for filtering single property values accessed.
     * @return the filtering config, never null.
     */
    public static FilterContext getSingleFilterContext();

    /**
     * Access the filtering configuration that is used for filtering configuration properties accessed as full
     * map.
     * @return the filtering config, never null.
     */
    public static FilterContext getMapFilters();

    /**
     * Removes all programmable filters active on the current thread.
     */
    public static void clearFilters();

    ...

}
-----------------------------------------------

For using regular expression when filtering configuration keys a corresponding implementation of a +PropertyFilter+
is part of this module, So you can add a customized filter as follows:

[source, java]
-----------------------------------------------
try {
    ThreadBasedConfigurationFilter.getMapFilters().addFilter(new myFilter());

    // do your code with filtering active
}
finally {
    // cleanup
    ThreadBasedConfigurationFilter.clearFilters();
}
-----------------------------------------------

The +ThreadFilterContext+ is a simple structure just providing some handy accessors to the dynamic thread-local
managed filters:

[source, java]
-----------------------------------------------
public final class ThreadFilterContext implements PropertyFilter {

    public void addIncludes(PropertyFilter filter);
    public void addExcludes(int pos, PropertyFilter filter);
    public PropertyFilter removeFilter(int pos);
    public void clearFilters();
    public void setIncludes(PropertyFilter... filters);
    public void setExcludes(Collection<PropertyFilter> filters);
    public List<PropertyFilter> getFilters();

}
-----------------------------------------------