<commit_before>= Apache Tamaya -- Extension: Resolver

:name: Tamaya
:rootpackage: org.apache.tamaya.ext.resolver
:title: Apache Tamaya Extension: Resolver
:revnumber: 0.1.1
:revremark: Incubator
:revdate: March 2015
:longversion: {revnumber} ({revremark}) {revdate}
:authorinitials: ATR
:author: <NAME>
:email: <<EMAIL>>
:source-highlighter: coderay
:website: http://tamaya.incubator.apache.org/
:toc:
:encoding: UTF-8
:numbered:

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

[[Core]]
== Tamaya Resolver (Extension Module)

=== Overview

Tamaya Resolver is an extension module. Refer to the link:modules.html[extensions documentation] for further details
about modules.

Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (+${...}+ placeholder
expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents
cycles to loop endlessly.

=== Compatibility

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

=== Installation

To benefit from dynamic value resolution you only must add the corresponding dependency to your module:

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

The module automatically registers an according +PropertyFilter+ that is automatically called, whenever a value
is accessed.

=== Available Resolvers

Currently the module defined the following resolvers:

.Available Resolvers
|=======
|_Expression_                                 |_Description_                                |_Example_
|+conf:<configKey>+       |Reads another configKey and replaces the expression with the value found.   | conf-ref=${conf:anotherConf.entryKey}
|+resource:<resourceRef>+       |Reads a resource from the current classpath and replaces the expression with the given text content.   | cp-ref=${resource:Testresource.txt}
|+file:<fileRef>+       |Reads a resource from the current classpath and replaces the expression with the given text content.   | file-ref=${file:c:\myFile.txt}
|+url:<url>+       |Reads an URL and replaces the expression with the given text content.   | url-ref=${url:http://www.google.com}
|=======

=== SPI: Implementing your own Resolvers

The module also provides an easy but powerful SPI for adding your own resolver implementations. Basically the
first and most important thing to do is implementing the +ExpressionResolver+ interface:

.Implementing a Custom Resolver
[source, java]
-----------------------------------------------
public class PwdDecrypter implements ExpressionResolver {

  @Override
  public String getResolverPrefix(){
     return "decrypt:";
  }

  @Override
  public String evaluate(String expression){
    return decrypt(expression);
  }

  private String decrypt(String s){
    ...
  }
}
-----------------------------------------------

Basically that is all you must do, after having registered the class with the +ServiceLoader+ it will be found
and loaded by the implementation. With that all expressions that start with the given prefix are passed to the
resolver, so all the following expressions will be sent to the implementation:

[source,listing]
-----------------------------------------------
blabla ${decrypt:myname}
blabla ${decrypt:myname} foo blabla ${decrypt:myname}
-----------------------------------------------

Hereby evaluation is repeasted until no further change of values could be detetced. In case of a endless loop
the evaluation is broken after a (configurable) number of cycles.<commit_msg>TAMAYA-122 Overhauled the documentation of the resolver documentation. Not finished. There is a layout problem with the formatting of one of the source examples.<commit_after>// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

= Apache Tamaya -- Extension: Resolver

include::temp-properties-files-for-site/attributes.adoc[]

:name: Tamaya
:rootpackage: org.apache.tamaya.ext.resolver
:title: Apache Tamaya Extension: Resolver
:revnumber: 0.1.1
:revremark: Incubator
:revdate: March 2015
:longversion: {revnumber} ({revremark}) {revdate}
:authorinitials: ATR
:author: <NAME>
:email: <<EMAIL>>
:source-highlighter: coderay
:website: http://tamaya.incubator.apache.org/
:encoding: UTF-8
:numbered:


[[Core]]
== Tamaya Resolver (Extension Module)

=== Overview

Tamaya Resolver is an extension module. Refer to the
// @todo Fix the link to the modules documentation
link:modules.html[extensions documentation]
for further details about modules.

Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (+${...}+ placeholder
expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents
cycles to loop endlessly.

=== Compatibility

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

=== Installation

To benefit from dynamic value resolution you only must add the corresponding dependency to your module:

[source, xml, subs="verbatim,attributes"]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya.ext</groupId>
  <artifactId>tamaya-resolver</artifactId>
  <version>{tamaya_version_current}</version>
</dependency>
-----------------------------------------------

The module automatically registers an according +PropertyFilter+ that is automatically called, whenever a value
is accessed.

=== Available Resolvers

Currently the module defined the following resolvers:

.Available Resolvers
[cols="<.1,<.2,<.1"]
|=======
| _Expression_
| _Description_
| _Example_

| +conf:<configKey>+
| Reads another configKey and replaces the expression with the value found.
| conf-ref=${conf:anotherConf.entryKey}

| +resource:<resourceRef>+
| Reads a resource from the current classpath and replaces the expression with the given text content.
| cp-ref=${resource:Testresource.txt}

| +file:<fileRef>+
| Reads a resource from the current classpath and replaces the expression with the given text content.
| file-ref=${file:c:\myFile.txt}

|+url:<url>+
|Reads an URL and replaces the expression with the given text content.
| url-ref=${url:http://www.google.com}

|=======

=== SPI: Implementing your own Resolvers

The module also provides an easy but powerful SPI for adding your own resolver implementations. Basically the
first and most important thing to do is implementing the +ExpressionResolver+ interface:

.Implementing a Custom Resolver
[source, java]
-----------------------------------------------
public class PwdDecrypter implements ExpressionResolver {

  @Override
  public String getResolverPrefix() {
     return "decrypt:";
  }

  @Override
  public String evaluate(String expression) {
    return decrypt(expression);
  }

  private String decrypt(String s) {
    ...
  }
}
-----------------------------------------------

Basically that is all you must do, after having registered the class with the +ServiceLoader+ it will be found
and loaded by the implementation. With that all expressions that start with the given prefix are passed to the
resolver, so all the following expressions will be sent to the implementation:

[source,listing]
-----------------------------------------------
blabla ${decrypt:myname}
blabla ${decrypt:myname} foo blabla ${decrypt:myname}
-----------------------------------------------

Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop
the evaluation is broken after a (configurable) number of cycles.
{'fraction_non_alphanumeric': 0.14296636085626913, 'fraction_numerical': 0.003713411970292704, 'mean_word_length': 3.3031015037593985, 'pattern_counts': {'":': 0, '<': 36, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1077016', 'n_tokens_mistral': 2371, 'n_tokens_neox': 2288, 'n_words': 1008}