# Apache Tamaya — Extension: Functions

## Tamaya Functions (Extension Module)

### Overview

Tamaya Functions is an extension module. Refer to the extensions documentation for further details.

Tamaya Functions provides several functional extensions using the ConfigOperator,ConfigQuery extension points. Most functional extension are accessible from the ConfigurationFunction singleton. When importing its methods statically one can use the methods to achieve some interesting effects, e.g.

    import static org.apache.tamaya.functions.ConfigurationFunctions.*;

    Set<String> sections = ConfigurationProvider.getConfiguration().with(areas("a", false).with(transitiveAreas());

The expression above returns all fully qualified section names that are child sections of the root section 'a'. So given the entries a.b.entry1, a.b.entry2, a.a.entry3, a.b.c.entry4 the reult would be a, a.a, a.b, a.b.c.

### Compatibility

The module is based on Java 7, so it can be used with Java 7 and beyond.

### Installation

For using the functionality shown in this document you only must add the corresponding dependency to your module:

    <dependency>
      <groupId>org.apache.tamaya.ext</groupId>
      <artifactId>tamaya-functions</artifactId>
      <version>{tamayaVersion}</version>
    </dependency>

### The Provided Functions

#### Functions on ConfigurationFunctions

The following sections explain the provided functions defined by ConfigurationFunctions singleton.

- ConfigOperator filter(PropertyMatcher matcher) creates a ConfigOperator that creates a Configuration containing only keys that are selected by the given matcher predicate. The PropertyMatcher hereby allows to evaluate not only the key, but also the value.

- ConfigOperator map(KeyMapper keyMapper) creates a ConfigOperator that maps the keys as defined by the given keyMapper.

- ConfigOperator section(String section) creates a ConfigOperator that creates a Configuration containing only entries that are direct or indirect members of the given section.

- ConfigOperator section(String areaKey, boolean stripKeys) creates a ConfigOperator that creates a Configuration containing only entries that are direct or indirect members of the given section. Hereby stripKeys allows to determine if the returned entries should be relative to the search criteria {{stripKeys=true}} or absolute keys.

- isKeyInSection(String section, String sectionKey) allows to easily determine if a given key is a direct or indirect member of a given section.

- boolean isKeyInSections(String key, String…​ sectionKeys) allows to easily determine if one key of given key is a direct or indirect member of at least one of the given sectionKeys.

- ConfigQuery<Set<String>> sections() allows to query all the contained fully qualified section names (the ones that also have parameters present).

- ConfigQuery<Set<String>> transitiveSections() allows to query all the contained fully qualified section names, including the transitive closure of sections.

- ConfigQuery<Set<String>> sections(final Predicate<String> predicate) allows to query all the contained fully qualified section names that are selected by the given predicate.

- ConfigQuery<Set<String>> sections(final Predicate<String> predicate) allows to query all the contained fully qualified section names that are selected by the given predicate, including the transitive closure of sections identified.

- ConfigOperator sectionsRecursive(String…​ sectionKeys) provides a ConfigOperator that filters all sections identified by the given sectionKeys and its child sections.

- ConfigOperator sectionRecursive(final boolean stripKeys, final String…​ sectionKeys) provides a ConfigOperator that filters all sections identified by the given sectionKeys and its child sections. stripKeys allows to determine if the resulting configuration should be relative to the selected areas ({{stripKeys=true}}) or absolute (filtering only).

- ConfigQuery<String> jsonInfo() returns a query that converts a Configuration into a JSON formatted String representation.

#### Functions on PropertySourceFunctions

The following sections explain the provided functions defined by PropertySourceFunctions singleton.

- PropertySource addMetaData(PropertySource propertySource, Map<String,String> metaData) Creates a new PropertySource with the given metadata added.

- boolean isKeyInSection(String key, String sectionKey) Checks if the given key is a direct or indirect member of one of the given sectionKey.

- boolean isKeyInSections(String key, String…​ sectionKeys) Checks if the given key is a direct or indirect member of one of one of the given sectionKeys.

- Set<String> sections(Map<String, String> properties) Extracts the sections from the given properties.

- Set<String> transitiveSections(Map<String, String> properties) Extracts the transitive sections from the given properties.

- Set<String> sections(Map<String, String> properties, final Predicate<String> predicate) Extracts the sections from the given properties, also filtering with the given predicate.

- Set<String> transitiveSections(Map<String, String> properties, Predicate<String> predicate) Extracts the transitive sections from the given properties, also filtering with the given predicate.

- Map<String,String> sectionsRecursive(Map<String, String> properties, String…​ sectionKeys) Creates w PropertySource only containing the sections that a direct or indirect children of the given sectionKeys.

- Map<String,String> sectionRecursive(Map<String, String> properties, boolean stripKeys, String…​ sectionKeys) Creates w PropertySource only containing the sections that a direct or indirect children of the given sectionKeys. With stripKeys one can select of the returned values should be relative to its selection of be fully qualified.

- String stripSectionKeys(String key, String…​ sectionKeys) This function strips away the matching section key as given in sectionKeys from a given key.