You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2018/11/18 21:20:49 UTC
[3/8] incubator-tamaya-site git commit: TAMAYA-274 Updated
documentation. TAMAYA-355 Updated documentation. TAMAYA-353 Updated
documentation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_jodatime.adoc
index 67a88a1,67a88a1..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_jodatime.adoc
+++ /dev/null
@@@ -1,80 -1,80 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: JodaTime
--
--toc::[]
--
--[[JodaTime]]
--== Tamaya JodaTime (Extension Module)
--Tamaya _JodaTime_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _JodaTime_ is an extension module to support the usage of http://www.joda.org/joda-time/[Joda-Time]
--in conjunction with Tamaya. Tamaya JodaTime defines some additional property
--converters to use Joda-Time types when accessing configuration.
--
--
--=== Installation
--
--To support Joda-Time types as configuration values, you only have to add the following
--maven dependency to your project:
--
--[source, listing]
-------------------------------------------------
--<dependency>
-- <grooupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-jodatime</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Usage
--
--After adding this module to your project you can retrieve
--Joda-Time based values directly from a given configuration.
--
--[source,java]
-------------------------------------------------
--Config configuration = ConfigProvider.getConfig();
--
--DateTime pit = configuration.get("pointInTime", DateTime.class)
-------------------------------------------------
--
--Currently the following types are supported:
--
--
--[width="80%",options=header]
--|================================================================
--| Joda-Time target type | Supported Input Formats
--.12+^.<| +org.joda.time.DateTime+ +org.joda.time.Instant+ | `yyyy-MM-dd'T'HH:mm:ss.SSSZ`
-- | `yyyy-MM-dd'T'HH:mm:ss.SSSz`
-- | `yyyy-MM-dd'T'HH:mm:ss.SSS z`
-- | `yyyy-MM-dd'T'HH:mm:ssZ`
-- | `yyyy-MM-dd'T'HH:mm:ssz`
-- | `yyyy-MM-dd'T'HH:mm:ss z`
-- | `yyyy-MM-dd'T'HH:mmZ`
-- | `yyyy-MM-dd'T'HH:mmz`
-- | `yyyy-MM-dd'T'HH:mm z`
-- | `yyyy-MM-dd'T'HHZ`
-- | `yyyy-MM-dd'T'HHz`
-- | `yyyy-MM-dd'T'HH z`
--.2+^.<| +org.joda.time.DateTimeZone+ | `[+-]hh:mm` (reg.ex.)
-- | all _timezone ids_ known by Joda-Time.
--.3+^.<| +org.joda.time.Duration+ | `PTa.bS`
-- | `PdDThHmMsS`
-- | `ddThh:mm:ss`
--.2+^.<| +org.joda.time.Period+ | `PyYmMwWdDThHmMsS`
-- | `Pyyyy-mm-ddThh:mm:ss`
--.4+^.<| +org.joda.time.LocalDate+ | `yyyy ['-' MM ['-' dd]]`
-- | `yyyy ['-' DDD]`
-- | `LocalDateConverter`
-- | `yyyy ['-' dd ['-' MM]]`
--.4+^.<| +org.joda.time.LocalTime+ | `['T']` _time-element_
-- | _time-element_ = HH [_minute-element_] _or_ [_fraction_]
-- | _minute-element_ = ':' mm [_second-element_] _or_ [_fraction_]
-- | _second-element_ = ':' ss [_fraction_]
-- | _fraction_ = ('.' _or_ ',') digit+`
--|================================================================
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_json.adoc
index a6e0572,a6e0572..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_json.adoc
+++ /dev/null
@@@ -1,80 -1,80 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Builder
--
--toc::[]
--
--
--[[JSON]]
--== Tamaya JSON (Extension Module)
--Tamaya _JSON_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _JSON_ provides support for reading configuration using JSON
--format:
--
--[source, json]
-------------------------------------------------
--{
-- "a.b"{
-- "key1": "blabla",
-- "key2": true,
-- }
--}
-------------------------------------------------
--
--Hereby the hierarchical structure of the JSON document will be mapped to a
--flat key-value pairs of type `String`, e.g. the bove will be mapped to
--
--[source, properties]
-------------------------------------------------
--a.b.key1=blabla
--a.b.key2=true
-------------------------------------------------
--
--This extension uses SPI defined by the +tamaya.formats+ extension module.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To use the JSON extension module you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-json</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--This extension also transitively requires the +tamaya.formats+ module.
--
--
--=== Reading configuration in JSON
--
--For reading JSON based onfiguration most easily a +JSONFormat+ can be
--used:
--
--[source, java]
-------------------------------------------------
--ConfigurationData dataRead = ConfigurationFormats.readConfig(
-- getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
-------------------------------------------------
--
--Or, if you are fine with the _default_ mapping you can directly create a
--+PropertySource+ using the _formats_ API (this works since this module
--registers the _json_ format automatically using the `ServiceContext`):
--
--[source, java]
-------------------------------------------------
--ConfigSource ps = ConfigurationFormats.createConfigSource(
-- getClassLoader().getResource("myFileConfig.json"));
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_management.adoc
index df45aeb,df45aeb..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_management.adoc
+++ /dev/null
@@@ -1,97 -1,97 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: JMX Management Access
--
--toc::[]
--
--
--[[ExtModel]]
--== Tamaya Management (JMX Support) (Extension Module)
--Tamaya _Management_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--The Tamaya _Management_ module provides support for registering a JMX management bean for
--accessing configuration.
--
--=== Compatibility
--
--The module is based on Java 8, so it will run on Java 8 and beyond.
--
--
--=== Installation
--
--To use the _management_ extension you only must add the corresponding dependency
--to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-management</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== The ManagedConfigMBean bean
--
--The management model defines the MBean of type +ManagedConfigMBean+ as follows:
--
--
--[source,java]
-------------------------------------------------------------------------------
--public interface ManagedConfigMBean {
-- String getJsonConfigurationInfo();
-- String getXmlConfigurationInfo();
-- Map<String, String> getConfiguration();
-- Map<String, String> getSection(String area, boolean recursive);
-- Set<String> getSections();
-- Set<String> getTransitiveSections();
-- boolean isSectionExisting(String area);
-- default boolean isSectionEmpty(String area);
--}
-------------------------------------------------------------------------------
--
--* +getJsonConfigurationInfo,getXmlConfigurationInfo+ return a JSON or XML representation of the
--current configuration.
--* +getConfiguration+ access the current configuration properties.
--* +getSection+ allows to extract all entries below a certain subkey. With _recursive_ the query
-- will not only return direct children, but also recursively walk down all subsection of the
-- given section key.
--* +getSections+ returns all current known section names.
--* +getTransitiveSections+ return all sections, but also adds all transitive subsection as single
-- entries to the set as well.
--* +isSectionExisting+ and +isSectionEmpty+ allow for quering if entries are present under the given
-- section keys.
--
--
--=== Registering the ManagedConfigMBean
--
--For registering the current +ManagedConfigMBean+ instance to the current MBean platform server, the
--following static methods are available:
--
--[source,java]
-------------------------------------------------------------------------------
--public final class ConfigManagementSupport{
--
-- private JMXSupport(){}
--
-- public static ObjectName registerMBean();
-- public static ObjectName registerMBean(String context);
-- public static ObjectName unregisterMBean();
-- public static ObjectName unregisterMBean(String context);
--}
-------------------------------------------------------------------------------
--
--* +registerMBean+ creates a new +ManagedConfigMBean+ instance using the +ServiceContextManager+
-- and registers it. Optionally an additional _context_ parameter can be passed, which allows
-- to register the management bean for different classloaders, e.g. for different
-- ears.
--* +unregisterMBean+ does the oppsite than registering obviously.
--
--NOTE: The instance of +ManagedConfigMBean+ to be created and registered is evaluated by use og the
-- +ServiceContextManager+. So you can replace the bean implementation by registering your
-- overriding implementation using the current +ServiceContext+ (by default using
-- +java.util.ServiceLoader+ and +@Priority+ annotation.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_metamodel.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_metamodel.adoc
index ed03b25,ed03b25..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_metamodel.adoc
+++ /dev/null
@@@ -1,632 -1,632 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Metamodel (Configuration of Tamaya)
--
--toc::[]
--
--
--[[Model]]
--== Tamaya Metamodel (Configuration of Tamaya) (Extension Module)
--
--Tamaya _metamodel_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--The Tamaya _metamodel_ module provides support for configuring the Tamaya system itself. It
--allows, like a logging configuration, to configure how your configuration framework should
--work, where to find configuration and how it is combined using overrides, filters etc.
--
--By default it uses an XML based configuration format as illustrated below:
--
--[source, xml]
--.Extract from `tamaya-config.xml`
-------------------------------------------------
--<configuration>
-- <!-- Context is evaluated first. -->
-- <context>
-- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
-- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
-- <context-entry name="app">${properties:system.APP?default=NONE}</context-entry>
-- <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry>
-- <context-entry name="company">Trivadis</context-entry>
-- <context-entry name="default-formats">yaml,json</context-entry>
-- <context-entry name="default-refresh-period">5 SECOND</context-entry>
-- </context>
--
-- <!-- combinationPolicy type="" / -->
--
-- <!-- Configuration definition. -->
--
-- <sources>
-- <source enabled="${stage=TEST || stage=PTA || stage=PROD}"
-- type="env-properties">
-- <filter type="PropertyMapping">
-- <param name="mapTarget">ENV.</param>
-- </filter>
-- <filter type="AccessMask">
-- <param name="roles">admin,power-user</param>
-- <param name="policy">mask</param>
-- <param name="mask">*****</param>
-- <param name="matchExpression">SEC_</param>
-- </filter>
-- </source>
-- <source type="sys-properties" >
-- <filter type="ImmutablePropertySource" />
-- </source>
-- <source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
-- </source>
-- ...
-- </sources>
--</configuration>
-------------------------------------------------
--
--The module basically provides an XML representation to the +ConfigBuilder+ API.
--It creates and registers the corresponding +Config+
--as the system's _default_ configuration (accessible from `ConfigProvider.getConfig(ClassLoader cl)`.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use _metamodel_ features you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-model</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Creating a Configuration using Meta-Configuration
--
--The basic feature of this module is the capability of creating a +Config+ completely
--based on a meta-configuration file. For this the +MetaConfig+ main singleton
--provides different methods:
--
--[source, java)
-------------------------------------------------
--public final class MetaConfig {
-- public static void configure();
-- public static void configure(URL metaConfig);
-- public static ConfigBuilder createBuilder(URL metaConfig);
-- public static Config createConfiguration(URL metaConfig);
-------------------------------------------------
--
--* If you have supplied your meta-configuration at `META-INF/tamaya-config.xml` you simply
-- call +MetaConfig.configure();+. This will read the meta-configuration and
-- configure Tamaya's _default_ configuration. Alternatively you can choose your own
-- metaconfiguration location by passing an alternate `URL` ro read from.
--* With +MetaConfiguration.createContextBuilder()+ you can stop a step earlier: a new
-- instance of +ConfigBuilder+ is created and configured with all the
-- entries found in your meta-configuration. Also here you can optionally pass your
-- custom location for the meta-configuration resouce.
--* Finally +MetaConfig.createConfig(URL)+ allows you to create an
-- arbitrary +Config+ instance using a meta-configuration file. The `Config`
-- instance is completely independent and not registered as _default_ configuration, so
-- it's lifecycle and usage is completely under your control.
--
--
--=== MetaContext
--
--When thinking what are the various input parameters for determining a correct configuration, there
--might be different things relevant in different scenarios, especially for developers in different
--companies. A good example of such an input parameter is the current `STAGE`. All these kinf od inputs
--can be summarized in some sort of meta-configuration, commonly known as a _context_. So
--the metamodel extension ships with a +MetaContext+ class that allows to define a common meta-context,
--that can be accessed by components as needed to determine the correct settings to be applied:
--
--[source, java)
-------------------------------------------------
--public final class MetaContext {
--
-- ...
--
-- public static MetaContext getInstance(String contextName);
--
-- /**
-- * Access the default context. Contexts are managed as weak references in this class. If no
-- * such context exists, a new instance is created.
-- * @return the context instance, never null.
-- */
-- public static MetaContext getDefaultInstance();
--
-- /**
-- * Access a context by name. Contexts are managed as weak references in this class. If no
-- * such valid context exists, a new instance is created, using the given {@code validSupplier}.
-- * @param contextName the context name, not null.
-- * @return the context instance, never null.
-- */
-- public static MetaContext getInstance(String contextName, Supplier<Boolean> validSupplier);
--
-- /**
-- * Access the thread-based context. If no such context
-- * exists a new one will be created.
-- * @param reinit if true, clear's the thread's context.
-- * @return the corresponding context, never null.
-- */
-- public static MetaContext getThreadInstance(boolean reinit);
--
-- /**
-- * Access the current context, which actually is the current context, combined with the thread based
-- * context (overriding).
-- * @return the corresponding context, never null.
-- */
-- public MetaContext getCurrentInstance();
--
-- /**
-- * Access the current context, which actually is the current context, combined with the thread based
-- * context (overriding).
-- * @param reinit if true, clear's the thread's context.
-- * @return the corresponding context, never null.
-- */
-- public MetaContext getCurrentInstance(boolean reinit);
--
--
-- /**
-- * Method to evaluate if a context is valid. This basically depends on the
-- * {@code validSupplier}, if any is set. If no supplier is present the context is valid.
-- *
-- * @return true, if this context is valid.
-- */
-- public boolean isValid();
--
-- /**
-- * Combine this context with the other contexts given, hereby only contexts are included
-- * which are {@code valid}, see {@link #isValid()}.
-- * @param contexts the context to merge with this context.
-- * @return the newly created Context.
-- */
-- public MetaContext combineWith(MetaContext... contexts);
--
-- /**
-- * Access the given context property.
-- * @param key the key, not null
-- * @return the value, or null.
-- */
-- public String getProperty(String key);
--
-- /**
-- * Access the given context property.
-- * @param key the key, not the default value.
-- * @param defaultValue the default value to be returned, if no value is defined, or the
-- * stored value's TTL has been reached.
-- * @return the value, default value or null.
-- */
-- public String getProperty(String key, String defaultValue);
--
-- /**
-- * Sets the given context property.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- * @return the porevious value, or null.
-- */
-- public String setProperty(String key, String value);
--
-- /**
-- * Sets the given context property.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- * @param ttl the time to live. Zero or less than zero means, no timeout.
-- * @param unit the target time unit.
-- * @return the porevious value, or null.
-- */
-- public String setProperty(String key, String value, int ttl, TimeUnit unit);
--
-- /**
-- * Sets the given property unless there is already a value defined.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- */
-- public void setPropertyIfAbsent(String key, String value);
--
-- /**
-- * Sets the given property unless there is already a value defined.
-- * @param key the key, not null.
-- * @param value the value, not null.
-- * @param ttl the time to live. Zero or less than zero means, no timeout.
-- * @param unit the target time unit.
-- */
-- public void setPropertyIfAbsent(String key, String value, long ttl, TimeUnit unit);
--
-- /**
-- * Adds all properties given, overriding any existing properties.
-- * @param properties the properties, not null.
-- */
-- public void setProperties(Map<String,String> properties);
--
-- /**
-- * Adds all properties given, overriding any existing properties.
-- * @param properties the properties, not null.
-- * @param ttl the time to live. Zero or less than zero means, no timeout.
-- * @param unit the target time unit.
-- */
-- public void setProperties(Map<String,String> properties, long ttl, TimeUnit unit);
--
-- /**
-- * Checks if all the given properties are present.
-- * @param keys the keys to check, not null.
-- * @return true, if all the given keys are existing.
-- */
-- public boolean checkProperties(String... keys);
--
-- /**
-- * Access all the current context properties.
-- * @return the properties, never null.
-- */
-- public Map<String,String> getProperties();
--}
-------------------------------------------------
--
--As you see, a +MetaContext+ has the following aspects:
--
--* there are multiple context's possible, identified by their name.
--* Accessing an instance that does not yet exist, will create a new one.
--* there is one shared _default_ instance.
--* they store ordinary `String,String` key, value pairs.
--* they can be _combined_ into a overriging hierarchy
--* accessing the _default_ MetaContext returns the global instance combined with
-- a threaded override instance. Passing `reinit` will clear the thread instance's
-- data.
--
--
--==== Configuring MetaContexts
--
--`MetaContext` instances can be configured in the _meta-configuration_ in the first
--`meta-context` section as illustrated below:
--
--[source, xml]
-------------------------------------------------
--<!-- Configuring the default context -->
--<context>
-- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
-- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
-- <context-entry name="app">${properties:system.APP?default=NONE}</context-entry>
-- <context-entry name="context">${java:org.apache.tamaya.context.Context#id()}</context-entry>
-- <context-entry name="company">Trivadis</context-entry>
-- <context-entry name="default-formats">yaml,json</context-entry>
-- <context-entry name="default-refresh-period">5 SECOND</context-entry>
--</context>
--<!-- Configuring a context named 'APP' -->
--<context name="APP">
-- <context-entry name="application">someAppName</context-entry>
--</context>
-------------------------------------------------
--
--As shown above multiple contexts can be configured. Keys and values are of type `String`.
--
--
--===== Using Expressions
--
--As shown before, it is possible to add simple expressions, enclosed in `${}`. Hereby the
--contents must be formatted as `evaluator:expression`, which then internally must be interpreted by
--the +org.apache.tamaya.metamodel.internal.SimpleResolver+, which effectively reads and
--applied context entries.
--
--Currently the following placeholders for context entries are provided:
--
--* properties - mapping to system properties (`properties:sys:KEY`) or
-- environment properties (`properties:env:KEY`) or other MetaContext
-- entries initialized already (`properties:ctx[:CTXNAME]:KEY`)
--* java - mapping to a static method or field, returning a `String` value.
--
--
--=== General Extensions
--
--Working with meta-models requires additional aspects to be generalized to separate
--concerns and reuse some of the common functionality. These concepts are shown in the following
--subsections.
--
--=== Enabled
--
--Things can be dynamically enabled or disabled, e.g. based on context. This can be
--modelled by the +Enabled+ interface:
--
--[source, java]
-------------------------------------------------
--public interface Enabled {
--
-- /**
-- * Returns the enabled property.
-- * @return the enabled value.
-- */
-- boolean isEnabled();
--
-- /**
-- * Enables/disables this property source.
-- * @param enabled the enabled value.
-- */
-- void setEnabled(boolean enabled);
--}
-------------------------------------------------
--
--+Enabled+ can be used as a mixin-logic, e.g. for decorating property sources,
--property source providers, filters and converters. The decorator can also, if not
--set explicitly, evaluate the _enabled_ property based on the current runtime
--context.
--
--
--=== Refreshable
--
--Similar to _Enabled_ things can also be refreshable.
--
--[source, java]
-------------------------------------------------
--public interface Refreshable {
--
-- /**
-- * Refreshes the given instance.
-- */
-- void refresh();
--}
-------------------------------------------------
--
--This can be used to define a common API for refreshing artifctas. Similar to
--_Enabled_ this can be applied as a decorator/mix-in interface to property
--sources and property source providers. This property also is supported in the
--XML metaconfiguration, e.g.
--
--[source, xml]
-------------------------------------------------
--<sources>
-- <source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
-- </source>
--</sources>
-------------------------------------------------
--
--
--=== The MetaConfiguration XML Structure
--
--In general the `tamaya-config.xml` file does never apply an XML schema or
--similar. Nevertheless there is a common DSL structure, which can be extended
--as well (see next chapter).
--
--[source, xml]
-------------------------------------------------
--<configuration>
-- <!-- PART ONE: Contexts initialization. -->
-- <context>
-- <context-entry name="stage">${properties:system:STAGE?default=DEV}</context-entry>
-- <context-entry name="configdir">${properties:system:configdir?default=.}</context-entry>
-- ...
-- </context>
-- <context name="APP">
-- <context-entry name="application">someAppName</context-entry>
-- </context>
--
-- <!-- PART TWO: Global settings of ConfigurationContext. -->
-- <!-- combinationPolicy type="" / -->
--
-- <!-- PART THREE: Configuration definition. -->
--
-- <sources>
-- <source enabled="${stage=TEST || stage=PTA || stage=PROD}"
-- type="env-properties">
-- <filter type="PropertyMapping">
-- <param name="mapTarget">ENV.</param>
-- </filter>
-- <filter type="AccessMask">
-- <param name="roles">admin,power-user</param>
-- <param name="policy">mask</param>
-- <param name="mask">*****</param>
-- <param name="matchExpression">SEC_</param>
-- </filter>
-- </source>
-- <source type="sys-properties" >
-- <filter type="ImmutablePropertySource" />
-- </source>
-- <source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
-- </source>
-- <source type="file" refreshable="true">
-- <name>config.xml</name>
-- <param name="location">config.xml</param>
-- <param name="formats">xml-properties</param>
-- </source>
-- <source-provider type="resource">
-- <name>classpath:application-config.yml</name>
-- <param name="location">/META-INF/application-config.yml</param>
-- </source-provider>
-- <source type="ch.mypack.MyClassSource" />
-- <!--<include enabled="${stage==TEST}">TEST-config.xml</include>-->
-- <source-provider type="resource" enabled="${configdir != null}">
-- <name>config-dir</name>
-- <param name="location">/${configdir}/**/*.json</param>
-- </source-provider>
-- <source type="url" refreshable="true">
-- <name>remote</name>
-- <param name="location">https://www.confdrive.com/cfg/customerId=1234</param>
-- <param name="formats">json</param>
-- <filter type="CachedPropertySource">
-- <param name="ttl">30 SECOND</param>
-- </filter>
-- </source>
-- </sources>
-- <filters>
-- <filter type="UsageTrackerFilter"/>
-- <filter type="AccessControl">
-- <param name="roles">admin,power-user</param>
-- <param name="policy">hide</param>
-- <param name="expression">*.secret</param>
-- </filter>
-- <filter type="Cache">
-- <param name="ttl">30000</param>
-- <param name="expression">cached.*</param>
-- </filter>
-- </filters>
-- <converters>
-- <!--<converter type="AllInOneConverter"/>-->
-- <default-converters/>
-- </converters>
--</configuration>
-------------------------------------------------
--
--The different parts in fact are not hardcoded, but implemented
--as independent components, where each of them gets access to the
--XML DOM tree to read the configuration aspects of interest.
--Instances related must implement the ++ interface and register it to
--the `ServiceContext`. Reading order is mapped using `@Priority`
--annotations.
--For further details refer to the SPI section in this document.
--
--
--== Model SPI
--
--=== Extending the XML DSL
--
--The XML DSL can be extended in various ways:
--
--* Basically adding a new feature maps to adding a new section to the
-- meta-config XML. This can be easily done, by implementing +MetaConfigurationReader+
-- and do whatever is appropriate for your use case.
--* For adding new expression capabilities for `MetaContext`entries +SimpleResolver+ must
-- be implemented.
--* For allowing customized parameterization of artifacts, e.g. property sources,
-- property source providers, converters and filters etc. you may implement +ItemFactory+
-- instances.
--
--=== MetaConfigurationReader
--
--XML metaconfiguration is effectively processed by instances of
--type +org.apache.tamaya.metamodel.spi.MetaConfigurationReader+:
--
--[source,java]
-------------------------------------------------------------
--public interface MetaConfigReader {
--
-- /**
-- * Reads meta-configuration from the given document and configures the current
-- * context builder. The priority of readers is determined by the priorization policy
-- * implemented by the {@link org.apache.tamaya.spi.ServiceContext},
-- * @param document the meta-configuration document
-- * @param configBuilder the config builder to use.
-- */
-- void read(Document document, ConfigBuilder configBuilder);
--
-- }
-------------------------------------------------------------
--
--Hereby we also see that an instance of `ConfigBuilder` is passed.
--Remember, we mentioned earlier that meta-configuration basically is a XML
--API to the building a configuration using a +ConfigBuilder+. So
--all you can do with the meta-config XML can also be done programmatically using
--the Java API.
--
--This module provides instances of this class for reading of meta-context,
--property-sources, property source providers, converters, filters and more.
--Look into the +org.apache.tamaya.metamodel.internal+ package for further details.
--
--New instances implementing this interface must be registered into the current
--+ServiceContext+, by default the +ServiceLoader+ is used.
--
--
--=== ItemFactory
--
--Instances of +ItemFactory+ allow to configure artifacts using XML data:
--
--[source, java]
-------------------------------------------------------------
--public interface ItemFactory<T> {
--
-- /**
-- * Get the factory name.
-- * @return the factory name, not null.
-- */
-- String getName();
--
-- /**
-- * Create a new instance.
-- * @param parameters the parameters for configuring the instance.
-- * @return the new instance, not null.
-- */
-- T create(Map<String,String> parameters);
--
-- /**
-- * Get the target type created by this factory. This can be used to
-- * assign the factory to an acording item base type, e.g. a PropertySource,
-- * PropertySourceProvider, PropertyFilter etc.
-- * @return the target type, not null.
-- */
-- Class<? extends T> getArea();
--
--}
-------------------------------------------------------------
--
--The factory's name hereby is used as a short cut, e.g. have a look at the following
--XML snippet defining a `PropertySource` to be added:
--
--[source, xml]
-------------------------------------------------------------
--<source type="file" refreshable="true">
-- <name>config.json</name>
-- <param name="location">config.json</param>
--</source>
-------------------------------------------------------------
--
--In the above snippet _file_ equals to the factory name, which provides the user
--a simple to use short name, instead of adding the fully qualified classname
--(which is always possible).
--
--The _location_ paramter with its value is passed as `Map` to the `create` method.
--
--
--=== ItemFactoryManager
--
--This singleton class manages the _ItemFactory_ instances found, hereby allowing
--accessing and registering instances. This singleton is actually used by the
--component parsers (type `MetaConfigurationReader`).
--
--[source, java]
-------------------------------------------------------------
--public final class ItemFactoryManager {
--
-- ...
--
-- public static ItemFactoryManager getInstance();
--
-- public <T> List<ItemFactory<T>> getFactories(Class<T> type);
-- public <T> ItemFactory<T> getFactory(Class<T> type, String id);
--
-- public <T> void registerItemFactory(ItemFactory<T> factory);
--
--}
-------------------------------------------------------------
--
--
--=== Extended Implementations
--
--The package +org.apache.tamaya.metamodel.ext+ contains a few useful
--implementations that also can be used in your meta-configuration and
--show how mixin-functionality can be added without touching property source
--implementations.
--
--As of now the package contains
--
--* +EnabledPropertySource+: a decorator for a `PropertySource`
-- adding the capability to _enable/disable_ the property source.
--* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider`
-- adding the capability to _enable/disable_ the property source provider.
--* +RefreshablePropertySource+: a decorator for a `PropertySource`
-- adding the capability to _refresh_ the property source.
--* +EnabledPropertySourceProvider+ a decorator for a `PropertySourceProvider`
-- adding the capability to _refresh_ the property source provider.
--
--Not yet implemented but planned are implementations to add the following
--functionality:
--
--* _caching_ of entries for a given time.
--* _immutability_ of entries, so a configuration data (or parts of it) will
-- never change later.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_mutable_config.adoc
index 478acee,478acee..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_mutable_config.adoc
+++ /dev/null
@@@ -1,236 -1,236 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Mutable Configuration
--
--toc::[]
--
--
--[[MutableConfiguration]]
--== Tamaya Mutable Configuration (Extension Module)
--
--Tamaya _Mutable Configuration_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--+Config+ instances by default are read-only, which covers must of the use cases. But there are many legit scenarios
--where configuration should be written back to backend systems or the local file system. This module adds this
--functionality.
--
--
--=== Compatibility
--
--The module is based on Java 8, so it can be used with Java 8 and beyond.
--
--
--=== Installation
--
--To benefit from configuration mutability support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-mutable-config</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Core Architecture
--
--==== Accessing MutableConfig
--
--The core of the module is the +MutableConfigProider+ singleton, which provides access to +MutableConfig+
--instance, which extends +Config+. This interface adds additional methods to add/update or remove property values.
--Hereby each +MutableConfig+ manages a transaction like context, which includes
--a UUID that identifes a change.
--Backends for writing changes applied umst implement +MutableConfigSource+, which extends +ConfigSource+.
--Registrations and ordering policies are exact the same as with ordinary config sources, but
--mutable property sources can be targeted by config write operations.
--
--The example below shows how a +MutableConfig+ can be obtained ,values added, removed and
--finally changes written back to the backend:
--
--[source,java]
--.Accessing and changing configuration
----------------------------------------------
--MutableConfig config = MutableConfigProvider
-- .createMutableConfig();
--config.put("newKey", "newValue")
-- .put("anotherKey", "updatedValue")
-- .remove("valueNotValid")
-- .store();
----------------------------------------------
--
--In the above scenario we use the system's _default_ configuration as the backend to be used.
--We can also pass any +Config+ to render it into a mutable instance, e.g.
--
--[source,java]
--.Explicitly passing the backing configuration
----------------------------------------------
--Config config = ...;
--MutableConfig config = MutableConfigProvider
-- .createMutableConfig(config);
----------------------------------------------
--
--NOTE: If a configuration does not contain any +MutableConfigSource+ instances,
-- a +IllegalArgumentException+ is thrown since it would not be able to accept
-- any changes.
--
--
--Following we show the possible methods you can use to create a +MutableConfig+.
--We will show in the following sections more details on the options provided...
--
--[source, java]
-----------------------------------------------
--public final class MutableConfigProvider {
--
-- private MutableConfigProvider(){}
--
-- public static MutableConfig createMutableConfig();
-- public static MutableConfig createMutableConfig(
-- ChangePropagationPolicy changePropgationPolicy);
-- public static MutableConfig createMutableConfig(Config configuration);
-- public static MutableConfig createMutableConfig(
-- Config configuration,
-- ChangePropagationPolicy changePropgationPolicy);
--
-- [...]
--}
-----------------------------------------------
--
--As we have not yet shown it, +MutableConfiguration+ is defined as follows:
--
--[source, java]
-----------------------------------------------
--public interface MutableConfig extends Config {
--
-- void store();
--
-- ConfigChangeRequest getConfigChangeRequest();
-- ChangePropagationPolicy getChangePropagationPolicy();
--
-- MutableConfig put(String key, String value);
-- MutableConfig putAll(Map<String, String> properties);
-- MutableConfig remove(Collection<String> keys);
-- MutableConfig remove(String... keys);
--
--}
-----------------------------------------------
--
--
--===== Targeting specific MutableConfigSources
--
--A +Config+ may have multiple +MutableConfigSource+ instances present. These are members of Tamaya's ordered list of
--+ConfigSources+ to evaluate the configuration. Nevertheless writing back changes requires additional aspects to
--be considered:
--* Should changes written target all mutable config sources? Or should a change only
-- target the most significant instance (hereby not writing the change to less significant config sources)?
--* Or should a change be applied only to specific mutable config source(s), regardless its position in the
-- processing chain?
--
--Therefore a _default_ +ChangePropagationPolicy+ can be applied on a +MutableConfig+ instance, which allows to
--control this aspect:
--
--[source,java]
--.Explicitly passing the backing configuration
----------------------------------------------
--public interface ChangePropagationPolicy {
-- /**
-- * Method being called when a multiple key/value pairs are added or updated.
-- * @param configSources all config sources, including read-only config sources, of the current configuration,
-- * never null.
-- * @param configChange the configuration change, not null.
-- */
-- void applyChange(ConfigChangeRequest configChange, Collection<ConfigSource> configSources);
--}
----------------------------------------------
--
--By default, changes are applied to all registered +MutableConfigSource+ instances
--similarly.
--
--The +MutableConfigProvider+ singleton also provides the most common
--change propagation policy implementations:
--
--[source, java]
-----------------------------------------------
--public final class MutableConfigProvider {
--
-- [...]
--
-- public static ChangePropagationPolicy getApplyAllChangePolicy();
-- public static ChangePropagationPolicy getApplyMostSignificantOnlyChangePolicy();
-- public static ChangePropagationPolicy getApplySelectiveChangePolicy(String... propertySourceNames);
-- public static ChangePropagationPolicy getApplyNonePolicy();
--}
-----------------------------------------------
--
--
--==== Some Aspects to consider
--
--Due to Tamaya's design the effective effect of your changes to the overall configuration, cannot
--be sometimes a bit tricky to be predicted, since it depends on several aspects:
--
--. is the corresponding configuration resource configured as part of the current system's configuration?
--. what is the +PropertySource's+ priority within the configuration context? Is it overriding or overridden
-- by other sources?
--. is the change directly visible to the configuration system? E.g. injected values are normally not updated,
-- whereas injecting a +DynamicValue<T>+ instance allows to detect and react single value changes. Also the
-- +PropertySources+ implementation must be able to detect any configuration changes and adapt its values returned
-- accordingly. Finally values also can be marked as immutable or being cached.
--. Is configuration cached, or written/collected directly on access?
--. can the changes applied be committed at all?
--
--So it is part of your application configuration design to clearly define, which property sources may be read-only, which
--may be mutable, how overriding should work and to which backends finally any changes should be written back.
--
--
--=== Configuration Changes
--
--This module does not handle detection of changes to the overall system's +Config+. This can be done in
--several ways, e.g. by:
--
--* using the _tamaya-events_ extension, which can be used to observe the system's configuration and
-- publishing events when things have been changed.
--* The SPI implementing the +MutableConfigBackendSpi+ may inform/update any affected +ConfigSource,
-- ConfigSourceProvider+ instances about the changes applied.
--
--
--=== Supported Backends
--
--Multiple backends are supported. E.g. _tamaya-etcd_ also registers
--corresponding SPI implementations/backends. This module comes with
--the following +MutableConfigSource+ implementations:
--
--* +MutablePropertiesConfigSource+ resources, targeting local +.properties+ files, using the +java.util.Properties+
-- format.
--* +MutableXmlPropertiesConfigSource+ resources, targeting local +.xml+ property files, using the +java.util.Properties+
-- XML format.
--
--
--=== SPIs
--
--The module defines +MutableConfigProviderSpi+, that is used as a delegate by the +MutableConfigProvider+
--singleton accessor:
--
--[source,java]
--.SPI: MutableConfigurationProviderSpi
----------------------------------------------------
--public interface MutableConfigProviderSpi {
-- /**
-- * Creates a new {@link MutableConfig} with {@code autoCommit = false} as default.
-- *
-- * @param configuration the configuration, not null.
-- * @param propagationPolicy policy that defines how changes are published to the property
-- * sources.
-- * @return a new mutable configuration instance.
-- */
-- MutableConfig createMutableConfig(Config configuration,
-- ChangePropagationPolicy propagationPolicy);
--}
----------------------------------------------------
--
--Implementations are registered with the current +ServiceContext+ (using by default the
-- +java.util.ServiceLoader+ service).
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_optional.adoc
index 29ed2fc,29ed2fc..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_optional.adoc
+++ /dev/null
@@@ -1,61 -1,61 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Optional Tamaya Configuration
--
--toc::[]
--
--
--[[Optional]]
--== Tamaya Optional (Extension Module)
--
--Tamaya _Optional_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--=== What functionality this module provides ?
--
--Tamaya _Optional_ is for projects that want to benefit from Tamaya configuration optionally only.
--E.g. doing an OSS project you can declare to support configuration with Tamaya as
--an optional extension. This module can be added as a hard dependency to your code, hereby adding only
--three artifacts. The _optional_ module automatically checks the availability of Tamaya on the
--classpath and only if available it tries to access it for configuration evaluation.
--Additionally an +EvaluationPolicy+ lets you define the precedence of configured values
--(yours, or Tamaya ones, if present).
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use Tamaya _optional_ you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-optional</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Reading configuration using the Tamaya Optional Module
--
--Tamaya _Optional_ allows reading configuration with a small subset of functionality only. For more
-- advanced use cases consider using the Apache Tamaya as your main configuration API. When
-- creating your +OptionalConfiguration+ instance you also pass the logic to access a value
-- with your own configuration logic. Tamaya Optional will delegate to your logic as needed
-- (depending on the `EvaluationPolicy`).
--
--[source, java]
-------------------------------------------------
--BigDecimal interestRate =
-- OptionalConfiguration.of(
-- EvaluationPolicy.TAMAYA_OVERRIDES_OTHER,
-- (k) -> MyConfigMechanism.get(k) // String get(String key);
-- )
-- .get("com.mycomp.ratecalculator.rate", BigDecimal.class))
-- .orElse(BigDecimal.of(0.05d));
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_osgi.adoc
index d075ac1,d075ac1..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_osgi.adoc
+++ /dev/null
@@@ -1,814 -1,814 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extensions: OSGI Integration
--
--toc::[]
--
--
--[[OSGI]]
--== Tamaya OSGI Support
--
--Tamaya _OSGI_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _OSGI_ provides support for integration with OSGI. Hereby Tamaya does actively override or extend the OSGI
--+ConfigAdmin+ based configuration with entries stored and managed by Tamaya. Tamaya provides also shell extensions
--to enable/perform configuration loading and restoring actions.
--Optionally Tamaya also provides extension for automatically trigger configuration updates, when configuration has
--been changed and configuration injection using Tamaya's injection API.
--
--
--=== Compatibility
--
--All module described are based on Java 8, so it will run on Java 8 and beyond.
--The modules are built against *OSGI Compendium version 5.0*. Tamaya OSGI support
--is tested against the following OSGI runtimes:
--
--* Apache Karaf, version 4.0.7
--* Apache Felix, version 5.6.1
--* Eclipse Equinox, version x.x.x.
--
--
--=== Installation
--
--To benefit from Tamaya in an OSGI context you must deploy at least the following modules to
--your OSGI runtime environment:
--
--[source, listing]
-------------------------------------------------
--# Runtime with OSGI ConfigAdmin support, e.g.
--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-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}
-------------------------------------------------
--
--
--=== Tamaya Service Loading in OSGI
--
--Important to know is that within OSGI class- and resource loading is not compatible with standard Java SE. Also
--in OSGI, bundles can be loaded or unloaded at any time, so Tamaya's logic must cope with this as well.
--These constraints are handled by Tamaya (implemented in +tamaya-core+ and +tamaya-osgi+) as follows:
--
--* Tamaya registers a +OSGIServiceContext+ which reads all +java.util.ServiceLoader+ configurations and
-- registers them as OSGI services. Hereby integration is two-way: The core module contains an
-- OSGI +Activator+ that replaces Tamaya's default +ServiceContext+ with an OSGI based implementation that
-- will consume all services from the OSGI service API. Consequently you can also register Tamaya extensions
-- as OSGI services using standard OSGI tooling (e.g. your own +PropertySource+ instances). Tamaya hereby
-- also does not store any service references, so the dynamic nature of OSGI is fully honored.
--* Tamaya's +ServiceContext+ SPI does additionally provide functionality for loading of (classpath)
-- resources using the bundle's +getEntry(String)+ method.
--* Tamaya similarly checks the classpath of all bundles for Tamaya SPI services to be registered thus
-- implementing the +ServiceLoader+ logic in OSGI. Hereby Tamaya will only register services with the
-- +org.apache.tamaya+ as root package.
--
--NOTE: Tamaya actually does not replace any existing +ConfigAdmin+ component, Tamaya modifies any existing OSGI
-- configuration on changes detected and stores backups of any OSGI configuration before applying any
-- changes.
--
--=== Configuring Bundles
--==== Mapping of pids and factoryPids
--
--When accessing configuration from the OSGI +ConfigAdmin+ a pid and an optional location can be provided.
--Tamaya requires all configuration for a PID to be located in keys starting [PID]:
--
--[source, listing]
--.OSGI pid mapping
-------------------------------------------------
--# OSGI settings
--pid=myBundle
--key=common.net.port
--
--# Corresponding key in Tamaya configuration
--[myBundle]key=common.net.port
-------------------------------------------------
--
--==== Enabling/Disabling Tamaya
--
--By default, Tamaya doesn't do anything, unless it is told to so so. So having installed the Tamaya OSGI plugin,
--you will see the bundles are loaded, but your OSGI environment still works the same. This is not accidentally, since
--configuration is a crucial part. This means Tamaya, by default, is disabled for all bundles. You have now several
--options to enabled Tamaya:
--
--* you can enable Tamaya for *all* bundles by default by
-- ** setting the +-Dtamaya-enabled=true+ system property.
-- ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the PID +TamayaConfigPlugin+.
--* you can enable Tamaya for a single bundle by
-- ** by setting +tamaya-enabled=true+ in the OSGI Configuration for the given bundle.
-- ** by adding +Tamaya-Enabled: true+ to the bundle's MANIFEST.
--
--Similarly you can also combine these options the other way round:
--
--* You can enable Tamaya by default as shown above.
--* You can disable Tamaya for bundles by
-- ** by setting +tamaya-enabled=false+ in the OSGI Configuration for the given bundle.
-- ** by adding +Tamaya-Enabled: false+ to the bundle's MANIFEST.
--
--
--==== Controlling How Tamaya changes your OSGI Configuration
--
--Tamaya supports different policies that define how Tamaya is changing the OSGI configuration:
--
--* *EXTEND*: Only add properties not existing in the OSGI configuration, but never override
-- or remove existing properties.
--* *OVERRIDE*: Override existing properties and also add new properties.
--* *UPDATE_ONLY*: Only override existing properties but do not add any properties.
--
--By default, Tamaya uses the _OVERRIDE_ policy. Also this policy can be configured in several
--ways and with different scopes:
--
--* You can define the _default_ policy applied, by
-- ** setting the +-Dtamaya-policy=POLICY+ system property.
-- ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the PID +TamayaConfigPlugin+.
--
--Hereby, _POLICY_ must be one of +OVERRIDE, EXTEND, UPDATE_ONLY+.
--
--* You can also configure the policy individually for a bundle by
-- ** by setting +tamaya-policy=POLICY+ in the OSGI Configuration for the given bundle.
-- ** by adding +Tamaya-Policy: POLICY+ to the bundle's MANIFEST.
--
--==== Mapping OSGI PIDs to Tamaya Configuration
--
--Tamaya configuration is a single +Map<String,String> with String keys and String values. Whereas OSGI configuration are
--multiple +Dictionary<String,?>+ (for several PIDs). The Tamaya OSGI extension implements the following mapping:
--
--As an example refer to the followinf Tamaya configuration entries:
--
--[source, listing]
--.Tamaya configuration for PID 'MyPlugin'
-------------------------------------------------
--[MyPlugin]ch.base.pack.Main.customer=Native Inc
--[MyPlugin]ch.base.pack.Main.use=234
--[MyPlugin]ch.base.pack.Main.encoding=UTF-8
-------------------------------------------------
--
--The OSGI Configuration Plugin now provides the following configuration for PID:
--
--[source, listing]
--.OSGI configuration for PID 'MyPlugin'
-------------------------------------------------
--ch.base.pack.Main.use=100 (Integer)
--ch.base.pack.Main.switch=on (Boolean)
--ch.base.pack.Main.customer=NONE (String)
-------------------------------------------------
--
--Now using +Policy.OVERRIDE+ (as desribed in the previous section), Tamaya will change the OSGI configuration
--as follows:
--
--[source, listing]
--.OSGI configuration after Tamaya update for PID 'MyPlugin'
-------------------------------------------------
--ch.base.pack.Main.use=234 (Integer)
--ch.base.pack.Main.switch=on (Boolean)
--ch.base.pack.Main.customer=Native Inc (String)
--[MyPlugin]ch.base.pack.Main.encoding=UTF-8 (String)
-------------------------------------------------
--
--So Tamaya configuration mapping can be summarized as follows:
--
--* The OSGI PID is mapped to a Tamaya prefix +[PID]+.
--* The OSGI keys are the exact same keys as from Tamaya with the _[PID]_ prefix removed.
--* New entries are added (depending on the +Policy+) as +String+ values.
--* Types of existing entries are preserved on update (this requires the Tamaya entries to be convertable into
-- the required target types. Refer to Tamaya's core documentation for supported types and how
-- to add custom converters).
--
--Finally, the mapping of the OSGI _PID_ to the Tamaya _[PID]_ prefix also can be customized by
--
--* adding +tamaya-config-root+ as an OSGI configuration property to the OSGI configuration.
--* adding +Tamaya-Config-Root+ as a MANIFEST entry to the bundle.
--
--The root will replace the default _[PID]_ prefix with the value configured.
--
--==== OSGI Configuration Backup
--
--Before Tamaya changes any OSGI configuration it creates a _Backup_ of the existing OSGI
--configuration dictionary and stores it in serialized form in the plugin's OSGI configuration.
--This allows you to restore the original OSGI configuration in case of problems. Hereby Tamaya
--automatically sets the +tamaya-enabled=false+ property to disable Tamaya for the given
--configuration (bundle).
--
--The history can be accessed from the Tamaya Configuration Plugin Service
--(shown later).
--
--==== OSGI Configuration Change Log
--
--All changes applied by Tamaya are logged as well using
--+ConfigHistory+ entry items. The history can be accessed from the Tamaya Configuration Plugin Service
--(shown later):
--
--[source, Java]
--.OSGI ConfigHistory Entry
-------------------------------------------------
--public final class ConfigHistory implements Serializable{
--
-- [...]
--
-- public enum TaskType{
-- PROPERTY,
-- BEGIN,
-- END,
-- }
--
-- // ***
-- // Entry = attributes
-- // ***
--
-- public TaskType getArea(){...}
--
-- public String getPid() {... }
--
-- public Object getPreviousValue() {... }
--
-- public ConfigHistory setPreviousValue(Object previousValue) {... }
--
-- public Object getValue() {...}
--
-- public ConfigHistory setValue(Object value) {...}
--
-- public String getKey() {...}
--
-- public ConfigHistory setKey(String key) {...}
--
--}
-------------------------------------------------
--
--==== The Tamaya OSGI Configuration Service
--
--As mentioned Tamaya exposes it's OSGI functionality, allowing programmatic access to Tamaya configuration
--logic with the +TamayaConfigService+ OSGI service:
--
--[source, Java]
--.The exposed +TamayaConfigService+
-------------------------------------------------
--public interface TamayaConfigService{
-- /** The system/config property to set Tamaya's {@link Policy}. */
-- String TAMAYA_POLICY_PROP = "tamaya-policy";
-- /** The MANIFEST property to set Tamaya's {@link Policy}. */
-- String TAMAYA_POLICY_MANIFEST = "Tamaya-Policy";
-- /** The system/config property to define a customized Tamaya's configuration root, replacing the {@code [PID]} default
-- * prefix used. */
-- String TAMAYA_CUSTOM_ROOT_PROP = "tamaya-config-root";
-- /** The MANIFEST property to define a customized Tamaya's configuration root, replacing the {@code [PID]} default
-- * prefix used. */
-- String TAMAYA_CUSTOM_ROOT_MANIFEST = "Tamaya-Config-Root";
-- /** The system/config property to enable Tamaya. */
-- String TAMAYA_ENABLED_PROP = "tamaya-enabled";
-- /** The MANIFEST property to enable Tamaya. */
-- String TAMAYA_ENABLED_MANIFEST = "Tamaya-Enabled";
-- /** The system/config property to enable Tamaya automatic updates (requires Tamaya's Updater plugin to be loaded as well). */
-- String TAMAYA_AUTO_UPDATE_ENABLED_PROP = "tamaya-update-enabled";
-- /** The MANIFEST property to enable Tamaya automatic updates (requires Tamaya's Updater plugin to be loaded as well). */
-- String TAMAYA_AUTO_UPDATE_ENABLED_MANIFEST = "Tamaya-Update-Enabled";
--
-- /**
-- * Enables/disables automatic updates (requires Tamaya's Updater plugin to be loaded as well).
-- * @param enabled set to true to enable updates.
-- */
-- void setAutoUpdateEnabled(boolean enabled);
--
-- /**
-- * Enables/disables Tamaya config by default.
-- * @param enabled set to true to enable Tamaya for all bundles by default.
-- */
-- void setTamayaEnabledByDefault(boolean enabled);
--
-- /**
-- * Get the flag, if Tamaya is enabled by default for all bundles.
-- * @return true if Tamaya is enabled.
-- */
-- boolean isTamayaEnabledByDefault();
--
-- /**
-- * Get the default policy Tamaya is using for adapting OSGI configuration.
-- * @return the default policy, never null.
-- */
-- Policy getDefaultPolicy();
--
-- /**
-- * Set the default policy Tamaya is using for adapting OSGI configuration.
-- * @param policy the policy, not null.
-- */
-- void setDefaultPolicy(Policy policy);
--
-- /**
-- * Updates the given OSGI configuration with Tamaya configuration.
-- * @param pid the target PID, not null.
-- * @return the new configuration.
-- */
-- Dictionary<String,Object> updateConfig(String pid);
--
-- /**
-- * Updates the given OSGI configuration with Tamaya configuration.
-- * @param pid the target PID, not null.
-- * @param dryRun if true, the changes will not be applied to the OSGI configuration.
-- * @return the configuration that would be applied, has been applied.
-- */
-- Dictionary<String,Object> updateConfig(String pid, boolean dryRun);
--
-- /**
-- * Updates the given OSGI configuration with Tamaya configuration.
-- * @param pid the target PID, not null.
-- * @param policy the updating policy to be used, by default.
-- * @param forcePolicy if set to true, the given policy will be used, even if an alternate policy is configured
-- * for the given PID.
-- * @param dryRun if true, the changes will not be applied to the OSGI configuration.
-- * @return the configuration that would be applied, has been applied.
-- */
-- Dictionary<String,Object> updateConfig(String pid, Policy policy, boolean forcePolicy, boolean dryRun);
--
-- /**
-- * Checks if a bundle is enabled for Tamaya configuration.
-- * @param bundle the bundle, not null.
-- * @return true, if the bundle is enabled.
-- */
-- boolean isBundleEnabled(Bundle bundle);
--
-- /**
-- * Get the flag if automatic updates for config changes are enabled.
-- * @return true, if automatic updates for config changes are enabled.
-- */
-- boolean isAutoUpdateEnabled();
--
-- /**
-- * Get the backup written for a PID.
-- * @param pid the pid, not null.
-- * @return the backup, or null, if no backup is present.
-- */
-- Dictionary<String,?> getBackup(String pid);
--
-- /**
-- * Get all current known PIDs for which backups are registered.
-- * @return all known PIDs for which backups are registered.
-- */
-- Set<String> getBackupPids();
--
-- /**
-- * Restores a backup, replacing the current OSGI configuration with the backup and
-- * disabling Tamaya for this PID.
-- * @param pid the PID, not null.
-- * @return true, if a backup has been restored successfully.
-- */
-- boolean restoreBackup(String pid);
--
-- /**
-- * Stores the current OSGI configuration as a backup (only if no backup is existing).
-- * @param pid the target PID, not null.
-- * @return true, if a backup has been stored successfully.
-- */
-- boolean createBackup(String pid);
--
-- /**
-- * Deletes a backup, if existing.
-- * @param pid the target PID, not null.
-- * @return true, if a backup has been restored successfully.
-- */
-- boolean deleteBackup(String pid);
--
-- /**
-- * Sets the maximum getHistory size.
-- * @param maxHistory the max getHistory size. {@code 0} disables the getHistory function.
-- */
-- void setMaxHistorySize(int maxHistory);
--
-- /**
-- * Get the max getHistory size.
-- * @return the max getHistory size. {@code 0} means the getHistory function is disabled.
-- */
-- int getMaxHistorySize();
--
-- /**
-- * Access the current (full) change getHistory.
-- * @return the current getHistory, never null.
-- */
-- List<ConfigHistory> getHistory();
--
-- /**
-- * Clears the getHistory.
-- */
-- void clearHistory();
--
-- /**
-- * Clears the getHistory for a PID.
-- * @param pid the target PID, not null.
-- */
-- void clearHistory(String pid);
--
-- /**
-- * Get the getHistory for a PID.
-- * @param pid the target PID, not null.
-- * @return the PID's getHistory, never null.
-- */
-- List<ConfigHistory> getHistory(String pid);
--
-- /**
-- * Access the current OSGI configuration for a PID.
-- * @param pid the target PID, not null.
-- * @param section a subsection to be filter (using startsWith).
-- * @return the (optionally filtered) OSGI configuration.
-- */
-- Dictionary<String,Object> getOSGIConfiguration(String pid, String section);
--
-- /**
-- * Checks if a backup exists.
-- * @param pid the target PID, not null.
-- * @return true, if a backup exists.
-- */
-- boolean containsBackup(String pid);
--}
-------------------------------------------------
--
--
--==== The Tamaya OSGI Configuration Service
--
--Finally Tamaya also provides support for using Tamaya's injection API with your OSGI project. To enable injection
--you must install a few additional bundles:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-osgi-injection</artifactId>
-- <version>${tamaya.version}</version>
--</dependency>
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-injection</artifactId>
-- <version>${tamaya.version}</version>
--</dependency>
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>injection-api</artifactId>
-- <version>${tamaya.version}</version>
--</dependency>
-------------------------------------------------
--
--Given that you can inject configuration entries
--
--* on your services by
-- ** setting +tamaya-config-inject=true+ in your service properties.
-- ** setting +Tamaya-Config-Inject: true+ in your bundle's manifest.
--* or by using the registered +ConfigInjectionService+:
--
--[source, java]
-------------------------------------------------
--public interface ConfigInjectionService {
-- /** The manifest entry to enable Tamaya injection. */
-- String TAMAYA_INJECTION_ENABLED_MANIFEST = "Tamaya-Config-Inject";
-- /** The OSGI config entry to enable Tamaya injection. */
-- String TAMAYA_INJECTION_ENABLED_PROP = "tamaya-config-inject";
--
-- /**
-- * Checks if injection is enabled on the given service.
-- * @param reference the service reference, not null.
-- * @return true, if enjection is enabled.
-- */
-- boolean isInjectionEnabled(ServiceReference reference);
--
-- /**
-- * Checks if injection is enabled on the given service.
-- * @param bundle the bundle, not null.
-- * @return true, if enjection is enabled.
-- */
-- boolean isInjectionEnabled(Bundle bundle);
--
-- /**
-- * Configures the passed instance.
-- * @param instance the instance, not null.
-- * @param <T> the input and return type.
-- * @param pid the target PID, not null.
-- * @param location the optional location
-- * @return the configured instance.
-- */
-- <T> T configure(String pid, String location, T instance);
--
-- /**
-- * Creates a suzpplier, which supplies events as created by the basic supplier, which are
-- * automatically configured, when supplying.
-- * @param supplier the base supplier, not null.
-- * @param pid the target PID, not null.
-- * @param location the optional location
-- * @param <T> the type
-- * @return a configuring supplier.
-- */
-- <T> Supplier<T> getConfiguredSupplier(String pid, String location, java.util.function.Supplier<T> supplier);
--
-- /**
-- * Creates a template implementing the annotated methods based on current configuration data.
-- *
-- * @param <T> the type of the template.
-- * @param templateType the type of the template to be created.
-- * @param pid the target PID, not null.
-- * @param location the optional location
-- * @return the configured template.
-- */
-- <T> T createTemplate(String pid, String location, Class<T> templateType);
--
-- /**
-- * Configures the passed instance.
-- * @param instance the instance, not null.
-- * @param <T> the input and return type.
-- * @param bundle the target bundle, not null.
-- * @return the configured instance.
-- */
-- <T> T configure(Bundle bundle, T instance);
--
-- /**
-- * Creates a suzpplier, which supplies events as created by the basic supplier, which are
-- * automatically configured, when supplying.
-- * @param supplier the base supplier, not null.
-- * @param bundle the target bundle, not null.
-- * @param <T> the type
-- * @return a configuring supplier.
-- */
-- <T> Supplier<T> getConfiguredSupplier(Bundle bundle, java.util.function.Supplier<T> supplier);
--
-- /**
-- * Creates a template implementing the annotated methods based on current configuration data.
-- *
-- * @param <T> the type of the template.
-- * @param templateType the type of the template to be created.
-- * @param bundle the target bundle, not null.
-- * @return the configured template.
-- */
-- <T> T createTemplate(Bundle bundle, Class<T> templateType);
--}
-------------------------------------------------
--
--NOTE: Injection hereby is based on the OSGI ConfigAdmin values only. To use Tamaya configuration you have to additionally
--install the Tamaya common OSGI support as described in the previous sections.
--
--More details on Tamaya's injection API can be found in the corresponding link:mod_injection.html[API documentation].
--
--=== Special OSGI Platform support
--
--==== Apache Karaf Shell
--
--Apache Tamaya provides a Karaf Shell Extension providing commands for performing several actions related
--to Tamaya configuration. To use them, simply add the +org.apache.tamaya.ext:tamaya-osgi-karaf-shell+ bundle
--to your OSGI runtime. The extension will add the following commands to your Karaf conaole (with prefix +tamaya+):
--
--[width="100%",frame="1",options="header",grid="all"]
--|=======
--|_Artifact_ |_Description_ |_Options_
--
--| +tm_apply_config+
--| Show the current Tamaya configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_apply_config [options] pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target OSGI component PID.
--<b>OPTIONS</b>
--<i>operationMode, -m, --opmode</i> Explicitly set (override) the operation mode to use.
--<i>dryRun, -d, --dryrun</i> If set to true no OSGI configuration gets changed.
--</pre>
--+++
--
--| +tm_backup_create+
--| Creates a backup of a current OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_create [options] pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target pid to backup.
--<b>OPTIONS</b>
--<i>--force, -f</i> Forces to (over)write a backup, even if one already exists.
--</pre>
--+++
--
--| +tm_backup_delete+
--| Deletes the OSGI configuration backup of Tamya.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_delete pid
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID. '*' removes all backups.
--</pre>
--+++
--
--| +tm_backup_list+
--| List the backed-up OSGI configuration before Tamya applied changes.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_list [pid]
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID.
--</pre>
--+++
--
--| +tm_backup_restore+
--| Restores the OSGI configuration backup of Tamya and disabled the PID for Tamaya configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_backup_restore pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target PID. '*' restores all backups.
--</pre>
--+++
--
--| +tm_config+
--| Show the current Tamaya configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_config [options]
--<b>OPTIONS</b>
--<i>pi, -p, --pid</i> Apply filtering for the given OSGI component PID.
--<i>section, -s, --section</i> A starting expression selecting the section to be filtered.
--</pre>
--+++
--
--| +tm_enable+
--| Enables or disable Tamaya by default for all bundles/services (default: enabled=false). Disabling still allows to explicitly enable
-- bundles using 'tamaya-enable' manifest or OSGI config entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_enable enabled
--<b>ARGUMENTS</b>
--<i>enabled</i> The boolean value to enabled/disable Tamaya by default.
--</pre>
--+++
--
--| +tm_enabled+
--| Check if Tamaya is currently by default enabled for all bundles/services (default: enabled=false). If disabled still Tamaya allows to
-- explicitly enable bundles using 'tamaya-enable' manifest or OSGI config entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_enabled
--</pre>
--+++
--
--| +tm_history+
--| Gets the getHistory of changes Tamaya applied to the OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history [options] [pid]
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID.
--<i>--type, -t</i> Allows to filter the events types shown.
--</pre>
--+++
--
--| +tm_history_delete+
--| Deletes the getHistory of changes Tamaya applied to the OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_delete pid
--<b>ARGUMENTS</b>
--<i>pid</i> Allows to filter on the given PID.
--</pre>
--+++
--
--| +tm_history_delete_all+
--| Deletes the full getHistory of changes Tamaya applied to the OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_delete_all
--</pre>
--+++
--
--
--| +tm_history_maxsize+
--| Gets the maximal size of stored getHistory entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_maxsize
--</pre>
--+++
--
--| +tm_history_maxsize_set+
--| Sets the maximal size of Tamaya getHistory entries.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_history_maxsize_set size
--<b>ARGUMENTS</b>
--<i>size</i>: The maximum number of entries in the getHistory.
--+++
--
--| +tm_info+
--| Show he current Tamaya status.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_info
--</pre>
--+++
--
--| +tm_osgi_config+
--| Show the current OSGI configuration.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_osgi_config [options] pid
--<b>ARGUMENTS</b>
--<i>pid</i> The target OSGI component PID.
--<b>OPTIONS</b>
--<i>section, -s, --section</i>: A starting expression selecting the keys to be filtered.
--</pre>
--+++
--
--| +tm_policy+
--| Get the current Tamaya overriding policy.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_policy
--</pre>
--+++
--
--| +tm_policy_set+
--| Sets the current Tamaya operation policy.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_policy_set tm_policy_set
--<b>ARGUMENTS</b>
--<i>tm_policy_set</i>: The operation policy how Tamaya intercepts OSGI configuration.
--+++
--
--| +tm_propagate_updates+
--| Flag if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.
--| +++
--<pre>
--<b>SYNTAX</b>
--tm_propagate_updates
--+++
--
--| +tm_propagate_updates_set+
--| Configure if Tamaya is automatically triggering OSGI config updates, when according Tamaya configuration changes.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_propagate_updates_set enabled
--<b>ARGUMENTS</b>
--<i>enabled</i>: Set to true to enable Tamaya's updating trigger.
--</pre>
--+++
--
--| +tm_property+
--| Get a Tamaya property.
--| +++
--<pre><b>SYNTAX</b>
--tamaya:tm_property [options] [key]
--<b>ARGUMENTS</b>
--<i>key</i>: The target property source id.
--<b>OPTIONS</b>
--<i>extended,e</i>: Also print extended property value attributes.
--<i>propertysource, ps</i>: The target property source id.
--</pre>
--+++
--
--| +tm_propertysource+
--| Show the current Tamaya entries of a propertysource.
--| +++
--<pre><b>SYNTAX</b>
--tamaya:tm_propertysource [propertysource]
--<b>ARGUMENTS</b>
--<i>propertysource</i>: The target property source id.
--+++
--
--| +tm_propertysources+
--| Get a list of currently registered propertysources.
--| +++
--<pre>
--<b>SYNTAX</b>
--tamaya:tm_propertysources
--</pre>
--+++
--
--|=======
--
--==== Apache Karaf Ferature
--
--Apache Tamaya provides a Karaf feature with all required dependencies
--as +org.apache.tamaya.ext:tamaya-karaf-features:{tamaya-version}:features:xml+.
--
--
--
--==== Apache Felix Gogo Console
--
--Apache Tamaya also provides the same commands as described for _Karaf_, but executable in
--plaing Gogo console as used by Apache Felix and Equinox as
--+org.apache.tamaya.ext:tamaya-gogo-shell:{tamaya-version}+. Refer to the previous sections for
--a detailed command description.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_remote.adoc
index fb7ffa9,fb7ffa9..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_remote.adoc
+++ /dev/null
@@@ -1,111 -1,111 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Remote Configuration
--
--toc::[]
--
--
--[[Remote]]
--== Tamaya Remote Configuration (Extension Module)
--
--Tamaya _Remote_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Remote_ provides support for reading configuration from remote resources. It provides
--out-of-the-box support for reading scoped configuration from a Tamaya configuration server as
--provided with the Tamaya _server_ module .
--
--
--=== Compatibility
--
--The module is based on Java 8, so it will not run on Java 8 and beyond.
--
--
--=== Installation
--
--To use remote support you only must add the corresponding dependency to your module:
--
--[source, xml]
-------------------------------------------------
--<dependency>
-- <groupId>org.apache.tamaya.ext</groupId>
-- <artifactId>tamaya-remote</artifactId>
-- <version>{tamaya_version}</version>
--</dependency>
-------------------------------------------------
--
--
--=== Reading Remote configuration from a Tamaya Configuration Server
--
--The remote module allows reading JSON formatted configuration as provided by the Tamaya _server_ extension . The JSON
--format used looks as follows:
--
--[source, json]
-------------------------------------------------
--{
-- "java.vendor.url": "http://java.oracle.com/",
-- "java.vendor.url.bug": "http://bugreport.sun.com/bugreport/",
-- "java.vm.info": "mixed mode",
-- "java.vm.name": "Java HotSpot(TM) 64-Bit Server VM",
-- "java.vm.specification.name": "Java Virtual Machine Specification",
-- "java.vm.specification.vendor": "Oracle Corporation",
-- "java.vm.specification.version": "1.8",
-- "java.vm.vendor": "Oracle Corporation",
-- "java.vm.version": "25.45-b02",
-- "sun.arch.data.model": "64",
-- "sun.boot.class.path": "C:\apps\jdk18\jre\lib\resources.jar;C:\apps\jdk18\jre\lib\rt.jar;C:\apps\jdk18\jre\lib\sunrsasign.jar;C:\apps\jdk18\jre\lib\jsse.jar;C:\apps\jdk18\jre\lib\jce.jar;C:\apps\jdk18\jre\lib\charsets.jar;C:\apps\jdk18\jre\lib\jfr.jar;C:\apps\jdk18\jre\classes",
-- "sun.boot.library.path": "C:\apps\jdk18\jre\bin",
-- "sun.cpu.endian": "little",
-- "sun.cpu.isalist": "amd64",
-- "sun.desktop": "windows",
-- "sun.io.unicode.encoding": "UnicodeLittle",
-- "sun.java.command": "com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start",
-- "sun.java.launcher": "SUN_STANDARD",
-- "sun.jnu.encoding": "Cp1252",
-- "sun.management.compiler": "HotSpot 64-Bit Tiered Compilers",
-- "sun.os.patch.level": "",
-- "_class": "org.apache.tamaya.functions.FilteredConfiguration",
-- "_info.filter": "java.v,sun",
-- "_info.format": "application/json",
-- "_info.timestamp": "1441463200571",
-- "_timestamp": "1441463200571",
-- "_type": "Configuration"
--}
-------------------------------------------------
--
--Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with
--+'_'+ to identify meta-data entries, but this is not a required precondition.
--
--Finally such a remote configuration can be easily integrated by inheriting from the provided base
--class. Hereby a default ordinal must be defined and the +protected Collection<URL> getAccessURLs()+
--method must be implemented to define the URL from where the configuration should be accessible. Hereby
--multiple URLs can be provided, which are accesed in order as provided by the collection's iterator. The
--first accessible URL determines the configuration read.
--
--[source, java]
-------------------------------------------------
--public class RemoteConfigSource extends BaseRemoteConfigSource{
--
-- @Override
-- protected Collection<URL> getAccessURLs() {
-- try {
-- String configServerUrl = System.getenv("CONFIG_SERVER");
-- if(configServerUrl==null){
-- configServerUrl = System.getProperty("configServer");
-- }
-- if(configServerUrl==null){
-- configServerUrl = "http://localhost:8888/config?scope=CLIENT&scopeId={clientId}&format=application/json";
-- }
-- System.out.println("Reading config from " + configServerUrl.replace("{clientId}", Client.getClientId()));
-- return Arrays.asList(new URL[]{new URL(configServerUrl.replace("{clientId}", Client.getClientId()))});
-- } catch (MalformedURLException e) {
-- Logger.getLogger(getClass().getName()).log(Level.WARNING, "Failed to configure remote config location,", e);
-- return Collections.emptySet();
-- }
-- }
--
--}
-------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya-site/blob/1c033714/content/documentation-new/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --cc content/documentation-new/extensions/mod_resolver.adoc
index dac7735,dac7735..0000000
deleted file mode 100644,100644
--- a/content/documentation-new/extensions/mod_resolver.adoc
+++ /dev/null
@@@ -1,131 -1,131 +1,0 @@@
--:jbake-type: page
--:jbake-status: published
--
--= Apache Tamaya - Extension: Resolver
--
--[[Resolver]]
--== Tamaya Resolver (Extension Module)
--
--Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation] for further details.
--
--
--=== What functionality this module provides ?
--
--Tamaya _Resolver_ is an extension module. Refer to the link:../extensions.html[extensions documentation]
--for further details about modules.
--
--Tamaya Resolver provides a extendible dynamic resolution mechanism. It 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 8, so it can be used with Java 8 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}</version>
--</dependency>
-------------------------------------------------
--
--The module automatically registers an according +Filter+ that is automatically called, whenever a value
--is accessed.
--
--
--=== Available Resolvers
--
--Currently the module defines 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 a small 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.
--
--
--Under the hood instances of +ExpressionResolver+ are managed by an implementation of the +ExpressionEvaluator+
--interface:
--
--[source, java]
-------------------------------------------------
--public interface ExpressionEvaluator {
-- /**
-- * Evaluates the current expression.
-- * @param key the key, not null.
-- * @param value the value to be filtered/evaluated.
-- * @return the filtered/evaluated value, including null.
-- */
-- String evaluateExpression(String key, String value);
--}
-------------------------------------------------
--
--Implementing and registering this interface gives you full control, but in most cases you should be fine with
--the default implementation in place.