tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject [1/2] incubator-tamaya-site git commit: TAMAYA-318 Updated documentation.
Date Mon, 20 Nov 2017 14:12:30 GMT
Repository: incubator-tamaya-site
Updated Branches:
  refs/heads/master e1ec90317 -> 5cc9fccf2


TAMAYA-318 Updated documentation.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/commit/b8fba796
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/tree/b8fba796
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/diff/b8fba796

Branch: refs/heads/master
Commit: b8fba79669f9db5382488f49e324d4b6e8d5b1a5
Parents: e1ec903
Author: Anatole Tresch <anatole.tresch@trivadis.com>
Authored: Mon Nov 20 15:08:05 2017 +0100
Committer: Anatole Tresch <anatole.tresch@trivadis.com>
Committed: Mon Nov 20 15:08:05 2017 +0100

----------------------------------------------------------------------
 content/documentation/core.adoc                 | 27 +++---
 content/documentation/extensions.adoc           |  6 +-
 .../extensions/mod_microprofile.adoc            | 93 ++++++++++++++++++++
 content/documentation/extensions/mod_osgi.adoc  |  3 +-
 .../extensions/mod_spi-support.adoc             | 67 --------------
 .../documentation/extensions/mod_spring.adoc    | 93 ++++++++++++++------
 content/documentation/spisupport.adoc           | 67 ++++++++++++++
 7 files changed, 247 insertions(+), 109 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/core.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/core.adoc b/content/documentation/core.adoc
index 575ca1e..d4604f2 100644
--- a/content/documentation/core.adoc
+++ b/content/documentation/core.adoc
@@ -10,7 +10,10 @@ and building blocks for supporting SPI implementations.
 
 Tamaya Core contains the following artifacts:
 
-* Implementations of +Configuration, ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi+
+* *tamaya-spisupport* provides implementations and base classes for different API artifacts
such as +Configuration,
+  ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi, BasePropertySource+
and more. It is
+  built as independent core module, which also can be used with other implementations. The
*tamaya-core*
+  implementation leverages these base classes to a build up a full API implementation.
 * A +java.util.ServiceLoader+ based +ServiceContext+ implementation. Hereby it implements
component priorization based
   on the +@Priority+ annotations.
 * A +PropertyConverterManager+ that loads and stores references to all the preconfigured
+PropertyConverter+ instances
@@ -42,8 +45,8 @@ For details about the extension modules available and  their functionality
refer
 [[CorePropertyConverters]]
 === Default PropertyConverters
 
-The _Core_ module provides several +PropertyConverter+ implementations by default. Find below
the
-listing of converters automatically registered with the Core module:
+The _SPI_ base module provides several +PropertyConverter+ implementations, which are automatically
registered by the
+_Core_ module. Find below the listing of converters automatically registered with the Core
module:
 
 [width="100%",frame="1",options="header",grid="all"]
 |=======
@@ -74,8 +77,9 @@ listing of converters automatically registered with the Core module:
 === Registering PropertyConverters
 
 Additional +PropertyConverters+ can be implemented easily. It is recommended to register
them using
-the +java.util.ServiceLoader+, meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+
containing the fully qualified
-class names of the converters to be registered (one line each).
+the +java.util.ServiceLoader+, meaning you add a file under +META-INF/service/org.apache.tamaya.spi.PropertyConverter+
+containing the fully qualified class names of the converters to be registered (one line each)
to enable
+auto-discovery.
 
 Alternatively you can also use a +ConfigurationContextBuilder+ to add additional converters
 programmatically.
@@ -84,8 +88,8 @@ programmatically.
 [[ComponentLoadingAndPriorization]]
 === Component Loading and Priorization
 
-Tamaya _Core_ in general loads all components by default using the +java.util.ServiceLoader+
mechanism. This means that new components
-must be registered by adding a file under +META-INF/service/<myInterfaceName>+ containing
the fully
+Tamaya _Core_ in general loads all components by default using the +java.util.ServiceLoader+
mechanism. This means that
+new components must be registered by adding a file under +META-INF/service/<myInterfaceName>+
containing the fully
 qualified implementation class names of the components to be registered (one line per each).
 The +ServiceLoader+ itself does not provide any functionality for overriding or ordering
of
 components. Tamaya _Core_ adds such a functionality with the possibility to add +@Priority+
@@ -108,8 +112,8 @@ NOTE: Sorting the property sources based on their ordinal value is only
the defa
 [[RegisteringPropertySources]]
 === Registering Property Sources
 
-+PropertySource+ implementations that provide configuration properties are registered as
components as described in the previous
-section. Hereby the precedence (ordering) of property sources is not hard-coded. Instead
a +Comparator<PropertySource>+
++PropertySource+ implementations that provide configuration properties are registered as
components as described in the
+previous section. Hereby the precedence (ordering) of property sources is not hard-coded.
Instead a +Comparator<PropertySource>+
 can be passed to a +ConfigurationContextBuilder+ to perform automatic ordering of the property
sources
 registered. The default implementation hereby implements the following logic:
 
@@ -145,7 +149,7 @@ applications already easily. Basically configuration is built  up by default
as
 === Overview of Registered Default Property Sources and Providers
 
 The Tamaya Core implementation provides a couple of default +PropertySource+ implementations,
which are automatically
-registered. They are all in the package +org.apache.tamaya.core.propertysource+ and
+registered. They are all in the package +org.apache.tamaya.spisupport.propertysource+ and
 +org.apache.tamaya.core.provider+:
 
 [width="100%",frame="1",options="header",grid="all"]
@@ -158,6 +162,9 @@ registered. They are all in the package +org.apache.tamaya.core.propertysource+
 |System Properties                        |SystemPropertySource           |1000
 |=======
 
+NOTE: Similarly to property converters the property sources shown here are defined within
the "tamaya-spisupport* module
+      and automatically registered with the *tamaya-core* implementation using Tamaya's auto-discovery
mechanisms.
+
 NOTE: +JNDIPropertySource+ is provided by the `tamaya-jndi` extension module.
 
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/extensions.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions.adoc b/content/documentation/extensions.adoc
index ceeac7d..1ca2b59 100644
--- a/content/documentation/extensions.adoc
+++ b/content/documentation/extensions.adoc
@@ -24,12 +24,13 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati
 |+org.apache.tamaya.ext:tamaya-injection-cdi+ | Java EE/standalone compliant CDI integration
using CDI for injection. | link:extensions/mod_cdi.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-jndi+          |Provides a JNDI based PropertySource.    
             |link:extensions/mod_jndi.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-json+          |Provides format support for JSON based configuration.
 |link:extensions/mod_json.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-microprofile+  |Implemenation and Integration with the Microprofile
API. | link:extensions/mod_microprofile.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration
            |link:extensions/mod_mutable_config.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-optional+      |Lets a Tamaya configuration to be used as
an optional project extension only.  |link:extensions/mod_optional.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-osgi+          |Integration with OSGI containers.        
             |link:extensions/mod_osgi.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-resolver+      |Provides placeholder and dynamic resolution
functionality for configuration values.  |link:extensions/mod_resolver.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-resources+     |Provides ant-style resource path resolution
 |link:extensions/mod_resources.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-spi-support+   |Tamaya support module for SPI implementation.
         |link:extensions/mod_spi-support.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-spring+        | Integration for Spring / Spring Boot.   
    | link:extensions/mod_spring.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-spring+        |Integration for Spring / Spring Boot.    
   | link:extensions/mod_spring.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-yaml+          |Support for using yaml as a configuration
format.      |link:extensions/mod_yaml.html[Documentation]
 |=======
 
@@ -57,7 +58,6 @@ NOTE: All extensions currently run on Java 7 as well as on Java 8.
 |+org.apache.tamaya.ext:tamaya-jodatime_beta+    |Provides support for JodaTime.        
               | link:extensions/mod_jodatime.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-management_alpha+  |Provides JMX support for inspecting configuration.
   |link:extensions/mod_management.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-metamodel_alpha+   |Provides an XML API for building configuration.
      |link:extensions/mod_metamodel-staged.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-osgi_alpha+        |Integration with OSGI containers.    
                | link:extensions/mod_osgi.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-remote_alpha+      |Remote configuration support using the
server API.    |link:extensions/mod_remote.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-server_alpha+      |Publishes configuration as a REST service.
           |link:extensions/mod_server.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-ui_alpha+          |Provides a web UI for a VM running Tamaya.
           |link:extensions/mod_ui.html[Documentation]

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/extensions/mod_microprofile.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_microprofile.adoc b/content/documentation/extensions/mod_microprofile.adoc
new file mode 100644
index 0000000..9d5951d
--- /dev/null
+++ b/content/documentation/extensions/mod_microprofile.adoc
@@ -0,0 +1,93 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya - Extension: Microprofile Implementation
+
+toc::[]
+
+
+[[Spring]]
+== Tamaya Microprofile Implementation (Extension Module)
+
+Tamaya _Microprofile_ is an extension module. Refer to the link:../extensions.html[extensions
documentation] for further details.
+
+
+=== What functionality this module provides ?
+
+Tamaya _Microprofile_ currently provides full integration for the Microprofile Configuration
API:
+
+* A Microprofile +ConfigSource+ implementation can be used with Tamaya.
+* A Tamaya +PropertySource+ can be used with any Microprofile implementation.
+* The same is also true for +Converter,PropertyConverter+.
+* Nevertheless Tamaya also fully implements the Microprofile API and also successfully is
compatible with the
+  Microprofile TCK.
+
+
+=== Compatibility
+
+Both modules are based on Java 8, so they will run on Java 8 and beyond. The implemented
Microprofile API is currently
+version 1.1.
+
+
+=== Installation
+
+To benefit from Tamaya Microprofile you only must one of the following dependencies to your
module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+  <groupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-microprofile</artifactId>
+  <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== Using Microprofile API
+
+Refer to http://microprofile.io/project/eclipse/microprofile-config for details on how the
API works and should be used. In general, you will see
+many similarities with Tamaya, since Tamaya heavily influenced the design of microprofile.io
regarding configuration.
+Nevertheless Tamaya's API is much more complete and provides far more feature as of now.
Further changes in this area
+may be good to be expected, since as of now also a corresponding specification (JSR) has
been started and will
+be supported by Tamaya as well.
+
+[source, java]
+--------------------------------------------------------
+// SE API
+
+Config config = ConfigProvider.getConfig();
+String serverUrl = config.getValue("acme.myprj.some.url", String.class);
+callToServer(serverUrl);
+
+// =====================================================================
+
+// CDI Injection API
+
+@ApplicationScoped
+public class InjectedConfigUsageSample {
+
+    @Inject
+    private Config config;
+
+    //The property myprj.some.url must exist in one of the configsources, otherwise a
+    //DeploymentException will be thrown.
+    @Inject
+    @ConfigProperty(name="myprj.some.url")
+    private String someUrl;
+    //The following code injects an Optional value of myprj.some.port property.
+    //Contrary to natively injecting the configured value this will not lead to a
+    //DeploymentException if the configured value is missing.
+    @Inject
+    @ConfigProperty(name="myprj.some.port")
+    private Optional<Integer> somePort;
+    //Injects a Provider for the value of myprj.some.dynamic.timeout property to
+    //resolve the property dynamically. Each invocation to Provider#get() will
+    //resolve the latest value from underlying Config.
+    //The existence of configured values will get checked during startup.
+    //Instances of Provider<T> are guaranteed to be Serializable.
+    @Inject
+    @ConfigProperty(name="myprj.some.dynamic.timeout", defaultValue="100")
+    private javax.inject.Provider<Long> timeout;
+}
+--------------------------------------------------------
+

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_osgi.adoc b/content/documentation/extensions/mod_osgi.adoc
index a00c1be..241f795 100644
--- a/content/documentation/extensions/mod_osgi.adoc
+++ b/content/documentation/extensions/mod_osgi.adoc
@@ -44,8 +44,9 @@ org.apache.felix:org.apache.felix.configadmin:{felix_version}
 # API and core
 org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0
 org.apache.tamaya:tamaya-api:{tamaya_version}
-org.apache.tamaya:tamaya-core:{tamaya_version}
 org.apache.tamaya:tamaya-spisupport:{tamaya_version}
+org.apache.tamaya:tamaya-core:{tamaya_version}
+# Required extensions
 org.apache.tamaya.ext:tamaya-functions:{tamaya_version}
 org.apache.tamaya.ext:tamaya-osgi:{tamaya_version}
 -----------------------------------------------

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_spi-support.adoc b/content/documentation/extensions/mod_spi-support.adoc
deleted file mode 100644
index afc1f49..0000000
--- a/content/documentation/extensions/mod_spi-support.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-:jbake-type: page
-:jbake-status: published
-
-= Apache Tamaya - Extension: Classloader Isolation Support
-
-toc::[]
-
-
-[[SPISupport]]
-== Tamaya SPI Support (Extension Module)
-
-Tamaya _SPI Support_ is an extension module. Refer to the link:../extensions.html[extensions
documentation] for further details.
-
-
-=== What functionality this module provides ?
-
-Tamaya _SPI Support_ provides a few helpful base classes that can be used to implement some
of the often
-used SPI parts in Tamaya:
-
-* +BasePropertySource+ provides an abstract base class for implementation of your own PropertySources.
-* +DefaultConfiguration+ provides you with a simple implementation of the +Configuration+
interface based on a
-  +ConfigurationContext+ provided. This is also very useful for mocking configuration during
test execution, but
-  not only constraint to that use case.
-* +DefaultConfigurationContext+ provides you with a working implementation of the +ConfigurationContext+.
-* +EnumConverter+ is a converter implementation that can automatically select the currect
enumeration values based
-  on a configured entry.
-* +MapPropertySource+ implements a static property source based on +java.util.Map+.
-* +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations
(also handling the
-  case, where no such annotation is present).
-* +PropertiesResourcePropertySource+ is an implementation of a +PropertySource+ based on
a +Properties+ instance,
-  lodable from any +URL+.
-+ +PropertyConverterManager+ is a service class very useful, when implementing instances
of +ConfigurationContext+.
-  It manages registered instances of +PropertyConverter+ and provides easy to use type conversion
logic.
-+ +PropertyFiltering+ provides another helpful class that manages +PropertyFilter+ instances
and provides an
-  easy to use high level API.
-+ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based
on their +getOrdinal()+
-  values and their class names.
-+ The default configuration implementation also allows to replace the raw value evaluation
-  logic using a +ConfigValueEvaluator+, similar to Tamaya's core implementation.
-
-NOTE: It is highly recommended that you read also the link:../core.html[documentation] of
Tamaya's
-      implementation core, since this describes the abstrations in use in more
-      detail. This module allows to reuse Tamaya's implementation artifacts but
-      still allow alternate implementations of the core API to be used.
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will run on Java 7 and beyond.
-
-
-=== Installation
-
-To use Tamaya's _spisupport_ you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
-  <groupId>org.apache.tamaya.ext</groupId>
-  <artifactId>tamaya-spisupport</artifactId>
-  <version>{tamaya_version}</version>
-</dependency>
------------------------------------------------
-
-The component will not register any components but only providing portable base classes for
some common SPI
-implementation tasks. It only depends on the API, so it should be safely reusable also with
other implementations
-of the Tamaya API similarly.

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/extensions/mod_spring.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/extensions/mod_spring.adoc b/content/documentation/extensions/mod_spring.adoc
index 9f7fb43..d335b25 100644
--- a/content/documentation/extensions/mod_spring.adoc
+++ b/content/documentation/extensions/mod_spring.adoc
@@ -14,7 +14,7 @@ Tamaya _Spring_ is an extension module. Refer to the link:../extensions.html[ext
 
 === What functionality this module provides ?
 
-Tamaya _Spring_ currently provides two implementations also full integration for Spring:
+Tamaya _Spring_ currently provides full integration for Spring and Spring Boot:
 
 * A Spring +@Configuration+ implementation that also provides a Tamaya based version of
   +org.springframework.context.support.PropertySourcesPlaceholderConfigurer+.
@@ -27,7 +27,7 @@ Tamaya _Spring_ currently provides two implementations also full integration
for
 
 === Compatibility
 
-Both modules are based on Java 7, so they will run on Java 7 and beyond. The extension shown
here works similarly
+Both modules are based on Java 8, so they will run on Java 8 and beyond. The extension shown
here works similarly
 with Spring Framework as well as Spring Boot.
 
 
@@ -48,7 +48,22 @@ To benefit from Tamaya Spring integration you only must one of the following
dep
 === Registering Tamaya Spring Configuration
 
 Basically to activate the Tamaya Spring support the most simple thing is to a enable the
Tamaya package for being
-scanned for Spring components, e.g.
+scanned for Spring components, e.g. using annotations:
+
+[source, java]
+--------------------------------------------------------
+@SpringBootApplication
+@ComponentScan({"org.apache.tamaya.integration.spring"})
+public class SampleWebFreeMarkerApplication {
+
+	public static void main(String[] args) throws Exception {
+		SpringApplication.run(SampleWebFreeMarkerApplication.class, args);
+	}
+
+}
+--------------------------------------------------------
+
+Of course, you can still use Spring's XML configuration variant similarly:
 
 [source, xml]
 --------------------------------------------------------
@@ -65,11 +80,9 @@ scanned for Spring components, e.g.
 </beans>
 --------------------------------------------------------
 
-NOTE: Of course you can also use the newer +@ComponentScan+ annotation as described by the
Spring documentation.
-
 
-Similarly if you dont want to use component scanning you can configure things using plain
old XML. Simply add the
-following lines somewhere into one of your application context configuration files.
+Though not recommended you can explicitly register the Tamaya related beans manually as well
in your context configuration
+files:
 
 [source, xml]
 --------------------------------------------------------
@@ -90,6 +103,7 @@ is resolved from the current Tamaya configuration.
 </bean>
 --------------------------------------------------------
 
+Similarly
 
 === Configuring your Beans
 
@@ -100,42 +114,65 @@ Similarly you can inject any kind of configuration as supported by Tamaya
into y
 **
  * Created by Anatole on 25.09.2015.
  */
-@ConfigDefaultSections
+@ConfigDefaultSections("app.root") // optional <1>
+@Component
 public class ConfiguredSpringBean {
 
+    @Value("${application.message:Hello World}")  <2>
     private String message;
 
     @Autowired
     private Environment env;
 
+    @Config(value = "alternateMessage", required = false) <3>
+    private String anotherMessage = "N/A";
+
     @Config("java.version")
     private String javaVersion;
 
-    @Config
-    @ConfigDefault("23")
+    @Config(value={"number", "testNum", "[notavailable]"}, defaultValue="23") <4><5>
     private int testNumber;
 
-    public String getJavaVersion(){
-        return javaVersion;
-    }
+    ...
+}
+--------------------------------------------------------
 
-    public int getTestNumber(){
-        return testNumber;
-    }
+<1> You can configure default section prefixes. This is an optional feature.
+<2> Tamaya does not require you to change your code. You can still work with
+    Spring injection for your configuration, but Tamaya will override Spring
+    configuration by default.
+<3> You can also define entries as not required, which allows you to perform
+    default inialization using Java idoms.
+<4> Tamaya allows you to define an ordered list of key candidates, which are
+    combined with the section prefix, if present, to the full keys. Keys added
+    in brackets ([]) are interpreted as absolute keys, so the example above
+    the key candidate list evaluates to +app.root.number", "app.root.testNum",
+    "notavailable"+.
+<5> You can configure default values used, if no other value could be evaluated
+    for the given keyset.
 
-    public Environment getEnv(){
-        return env;
-    }
+Summarizing you get all the nice features of Tamaya out of the box running
+with your Spring code.
 
-    public void setMessage(String message){
-        this.message = message;
-    }
+This also includes for example support for _dynamic values_:
 
-    public String getMessage() {
-        return message;
-    }
-}
+[source, java]
+--------------------------------------------------------
+@Config(value = "foreground.color", required = false, defaultValue = "#DDDDDD")
+private DynamicValue<Color> foregroundColor;
 --------------------------------------------------------
 
-Summarizing you get all the nice features of Tamaya out of the box running
-with your Spring code.
+Dynamic values are a very flexible mechanism for managing configuration changes.
+You can even use an update policy to define how you want to handle configuration
+changes four your value:
+
+[source, java]
+--------------------------------------------------------
+foregroundColor.setUpdatePolicy(UpdatePolicy.IMMEDEATE);
+foregroundColor.addPropertyChangeListener(() -> {
+   System.out.println("New forground color: " + foregroundColor.get();
+});
+--------------------------------------------------------
+
+IMPORTANT: For a full description of Tamaya's injection API please
+           refer to the link:extensions/mod_injection.html[corresponding documentation].

http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/b8fba796/content/documentation/spisupport.adoc
----------------------------------------------------------------------
diff --git a/content/documentation/spisupport.adoc b/content/documentation/spisupport.adoc
new file mode 100644
index 0000000..b5c7e17
--- /dev/null
+++ b/content/documentation/spisupport.adoc
@@ -0,0 +1,67 @@
+:jbake-type: page
+:jbake-status: published
+
+= Apache Tamaya: SPI Support Module
+
+toc::[]
+
+
+[[SPISupport]]
+== Tamaya SPI Support (Extension Module)
+
+Tamaya _SPI Support_ is an extension module. Refer to the link:../extensions.html[extensions
documentation] for further details.
+
+
+=== What functionality this module provides ?
+
+Tamaya _SPI Support_ provides a few helpful base classes that can be used to implement some
of the often
+used SPI parts in Tamaya:
+
+* +BasePropertySource+ provides an abstract base class for implementation of your own PropertySources.
+* +DefaultConfiguration+ provides you with a simple implementation of the +Configuration+
interface based on a
+  +ConfigurationContext+ provided. This is also very useful for mocking configuration during
test execution, but
+  not only constraint to that use case.
+* +DefaultConfigurationContext+ provides you with a working implementation of the +ConfigurationContext+.
+* +EnumConverter+ is a converter implementation that can automatically select the currect
enumeration values based
+  on a configured entry.
+* +MapPropertySource+ implements a static property source based on +java.util.Map+.
+* +PriorityServiceComparator+ compares arbitrary services based on their +@Priority+ annotations
(also handling the
+  case, where no such annotation is present).
+* +PropertiesResourcePropertySource+ is an implementation of a +PropertySource+ based on
a +Properties+ instance,
+  lodable from any +URL+.
++ +PropertyConverterManager+ is a service class very useful, when implementing instances
of +ConfigurationContext+.
+  It manages registered instances of +PropertyConverter+ and provides easy to use type conversion
logic.
++ +PropertyFiltering+ provides another helpful class that manages +PropertyFilter+ instances
and provides an
+  easy to use high level API.
++ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based
on their +getOrdinal()+
+  values and their class names.
++ The default configuration implementation also allows to replace the raw value evaluation
+  logic using a +ConfigValueEvaluator+, similar to Tamaya's core implementation.
+
+NOTE: It is highly recommended that you read also the link:../core.html[documentation] of
Tamaya's
+      implementation core, since this describes the abstrations in use in more
+      detail. This module allows to reuse Tamaya's implementation artifacts but
+      still allow alternate implementations of the core API to be used.
+
+
+=== Compatibility
+
+The module is based on Java 7, so it will run on Java 7 and beyond.
+
+
+=== Installation
+
+To use Tamaya's _spisupport_ you only must add the corresponding dependency to your module:
+
+[source, xml]
+-----------------------------------------------
+<dependency>
+  <groupId>org.apache.tamaya.ext</groupId>
+  <artifactId>tamaya-spisupport</artifactId>
+  <version>{tamaya_version}</version>
+</dependency>
+-----------------------------------------------
+
+The component will not register any components but only providing portable base classes for
some common SPI
+implementation tasks. It only depends on the API, so it should be safely reusable also with
other implementations
+of the Tamaya API similarly.


Mime
View raw message