content/documentation/extensions/mod_functions.adoc

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

= Apache Tamaya - Extension: Functions

toc::[]

[[Functions]]
== Tamaya Functions (Extension Module)

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


=== What functionality this module provides ?

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.

[source,java]
-------------------------------------------------------------------
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:

[source, xml]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-functions</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------


=== The Provided Functions

==== Functions on +ConfigurationFunctions+

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

* *UnaryOperator<Configuration> filter(PropertyMatcher matcher)* creates a +UnaryOperator<Configuration>+ 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_.
* *UnaryOperator<Configuration> map(KeyMapper keyMapper)* creates a +UnaryOperator<Configuration>+ that maps the keys as defined
  by the given _keyMapper_.
* *UnaryOperator<Configuration> section(String section)* creates  a +UnaryOperator<Configuration>+ that creates a +Configuration+ containing only
  entries that are direct or indirect members of the given section.
* *UnaryOperator<Configuration> section(String areaKey, boolean stripKeys)* creates  a +UnaryOperator<Configuration>+ 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 owner
  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 owner of at least one of the given _sectionKeys_.
* *Function<Configuration,Set<String>> sections()* allows to query all the contained fully qualified section names (the ones that
  also have parameters present).
* *Function<Configuration,Set<String>> transitiveSections()* allows to query all the contained fully qualified section names,
  including the transitive closure of sections.
* *Function<Configuration,Set<String>> sections(final Predicate<String> predicate)* allows to query all the contained fully
  qualified section names that are selected by the given _predicate_.
* *Function<Configuration,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.
* *UnaryOperator<Configuration> sectionsRecursive(String... sectionKeys)* provides a +UnaryOperator<Configuration>+ that filters all sections identified
  by the given _sectionKeys_ and its child sections.
* *UnaryOperator<Configuration> sectionRecursive(final boolean stripKeys, final String... sectionKeys)* provides a +UnaryOperator<Configuration>+
  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).
* *Function<Configuration,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 owner of
  one of the given _sectionKey_.
* *boolean isKeyInSections(String key, String... sectionKeys)* Checks if the given _key_ is a direct or indirect owner 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_.