2017-11-25

User Filtering (Extension Module)

Tamaya Filter is an extension module. Refer to the 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 7, so it will not run on Java 7 and beyond.

Installation

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

<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.ConfigurationFilter provides several static methods to register PropertyFilter instances on the current thread.

  • The org.apache.tamaya.filter.DefaultMetdataFilter 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):

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:

try {
    ConfigurationFilter.getMapFilters().addFilter(new myFilter());

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

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

public final class FilterContext 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();

}