content/documentation/spisupport.adoc

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

= Apache Tamaya: SPI Support Module

toc::[]


[[SPISupport]]
== Tamaya SPI Support

Tamaya _SPI Support_ is a module only depending on the API. It implements lots of API and SPI related
artifacts in a portable way. Tamaya's core module completes this functionality to implement the
full Tamaya API. This module can be reused also with alternate implementations of the Tamaya API.


=== What functionality this module provide?

Tamaya _SPI Support_ provides several base classes that can be used to implement the Tamaya Configuration API:

* +BasePropertySource+ provides an abstract *base class* for implementation of your own `PropertySource`.
* +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 an implementation of the +ConfigurationContext+ API.
* +MapPropertySource+ implements a 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,
  loadable from any +URL+.
+ +PropertyConverterManager+ is a useful service class, when implementing instances of +ConfigurationContext+.
  It manages registered instances of +PropertyConverter+ and provides easy to use type conversion logic based on
  the registered converters.
+ +PropertyFiltering+ provides a similar class, which manages +PropertyFilter+ instances and provides an
  easy to use high level filtering API.
+ +PropertySourceComparator+ provides an implementation that compares +PropertySources+ based on their +getOrdinal()+
  values and their class names. It is used to establish the default loading (significance) of property sources.
+ 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 also read the link:../core.html[documentation] of Tamaya's
      core implementation, since this describes the abstractions in use in more
      detail.

=== Compatibility

The module is based on Java 8, so it will run on Java 8 and beyond.


=== Installation

To use Tamaya's _spisupport_ you only have to add the corresponding dependency to your module:

[source, xml, subs=attributes+]
-----------------------------------------------
<dependency>
  <groupId>org.apache.tamaya</groupId>
  <artifactId>tamaya-spisupport</artifactId>
  <version>{tamaya_version}</version>
</dependency>
-----------------------------------------------

The component will not register any components but only provides 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 as well.