You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by po...@apache.org on 2016/12/19 21:38:54 UTC
[2/4] incubator-tamaya git commit: TAMAYA-209: Remove old stuff from
main repo.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_injection.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_injection.adoc b/src/site/asciidoc/extensions/mod_injection.adoc
deleted file mode 100644
index 47f8872..0000000
--- a/src/site/asciidoc/extensions/mod_injection.adoc
+++ /dev/null
@@ -1,447 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Injection
-
-toc::[]
-
-
-[[Core]]
-== Tamaya Injection (Extension Module)
-=== Overview
-
-Tamaya Injection is an extension module. Refer to the link:modules.html[extensions documentation] for further details
-about modules.
-
-Tamaya Injection provides functionality for injecting configured values into beans, or creating configuration
-template instances.
-
-Inversion of Control (aka IoC/the Hollywood Principle) has proven to be very useful and effective in avoiding boilerplate
-code. In Java there are different frameworks available that all provide IoC mechanisms. Unfortunately IoC is not a
-built-in language feature. So for a portable solution that works also in Java SE Tamaya itself has to provide the
-according injection services. This module adds this functionality to Tamaya.
-
-=== Compatibility
-
-The module is based on Java 7, so it can be used with Java 7 and beyond.
-
-=== Installation
-
-Basically Tamaya's injection API is deployed as API artifact:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-injection-api</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-To use injection with Java SE you must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-injection</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-Similarly there are other injection implementations available, targetig platforms such as
-
-* Spring, Spring Boot
-* Java EE/CDI
-* OSGI, Apache Felix/Apache Karaf
-
-
-=== Core Concepts
-
-Basically you annotate fields or methods in your beans with +@Config+ to enable configuration injection. Tamaya
-additionally defines further annotations that allo you to define additional aspects such as default values, custom
-converters etc. The following example illustrates the basic functionality:
-code snippet:
-
-[source,java]
-.Annotated Example Class
---------------------------------------------
-package foo.bar;
-
-public class ConfiguredClass{
-
- // resolved by default, using property name, class and package name: foo.bar.ConfiguredClass.testProperty
- private String testProperty;
-
- // Trying to resolve mutiple keys, with a default value, if none could be resolved
- @Config({"a.b.c.key1","a.b.legacyKey",area1.key2"}, defaultValue="The current \\${JAVA_HOME} env property is ${env:JAVA_HOME}.")
- String value1;
-
- // Typical case
- @Config("a.b.c.key2")
- private int value2;
-
- // resolved by default as foo.bar.ConfiguredClass.accessUrl
- // Using a (default) String -> URL converter
- @Config(defaultValue="http://127.0.0.1:8080/res/api/v1/info.json")
- private URL accessUrl;
-
- // Config injection disabled for this property
- @NoConfig
- private Integer int1;
-
- // Overriding the String -> BigDecimal converter with a custom implementation.
- @Config("BD")
- @WithPropertyConverter(MyBigDecimalRoundingAdapter.class)
- private BigDecimal bigNumber;
-
- ...
-}
---------------------------------------------
-
-
-When configuring data or configuration classes it is also possible to auto-inject the fields identified. For activating
-this feature a class must be annotated with +@ConfigAutoInject+:
-
-[source, java]
-. An autoinjected bean class
---------------------------------------------
-package a.b;
-
-@ConfigAutoInject
-public final class Tenant{
- private int id;
- private String name;
- private String description;
- @NoConfig // prevents auto injection for this field
- private String id2;
-
- public int getId(){
- return id;
- }
- public String getName(){
- return name;
- }
- public String getDescription(){
- return description;
- }
-}
---------------------------------------------
-
-These examples do not show all possibilities provided. Configuring instance of these
-class using Tamaya is very simple: Just pass the instance to Tamaya to let
-Tamaya inject the configuration (or throw a +ConfigException+, if this is not possible):
-
-[source,java]
-.Configuring the +ConfiguredClass+ Instance
---------------------------------------------
-ConfiguredClass classInstance = new ConfiguredClass();
-ConfigurationInjector.configure(configuredClass);
-
-Tenant tenant = new Tenant();
-ConfigurationInjector.configure(tenant);
---------------------------------------------
-
-NOTE: Configuration injection works similarly, when used with other integration modules, e.g. when Tamaya is used
-with CDI, Spring or within an OSGI container. For further details refer also to the corresponding integration module's
-documentation.
-
-
-=== The Annotations in detail
-==== The ConfigurationInjector
-
-The +ConfigurationInjector+ interface provides methods that allow any kind of instances to be configured
-by passing the instances to +T ConfigurationInjector.getInstance().configure(T);+. The classes passed
-hereby must not be annotated with +@Config+ for being configurable. By default Tamaya
-tries to determine configuration for each property of an instance passed, using the following resolution policy:
-
-Given a class +a.b.MyClass+ and a field +myField+ it would try to look up the following keys:
-[source, listing]
---------------------------------------------
-a.b.MyClass.myField
-a.b.MyClass.my-field
-MyClass.myField
-MyClass.my-field
-myField
-my-field
---------------------------------------------
-
-So given the following properties:
-
-[source, properties]
---------------------------------------------
-a.b.Tenant.id=1234
-Tenant.description=Any kind of tenant.
-name=<unnamed>
---------------------------------------------
-
-
-==== Accessing Supplier instances
-
-In many cases you want to create a supplier that simply creates instances that are correctly configured as defined
-by the current context. This can be done using +Suppliers+:
-
-[source, java]
---------------------------------------------
-Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
- new Supplier<Tenant>(){
- public Tenant get(){
- return new Tenant();
- }
-});
---------------------------------------------
-
-With Java 8 it's even more simpler:
-
-[source, java]
---------------------------------------------
-Supplier<Tenant> configuredTenantSupplier = ConfigurationInjector.getInstance().getConfiguredSupplier(
- Tenant::new);
---------------------------------------------
-
-Hereby this annotation can be used in multiple ways and combined with other annotations such as
-+@WithLoadPolicy+, +@WithConfigOperator+, +@WithPropertyConverter+.
-
-==== Minimal Example
-
-To illustrate the mechanism below the most simple variant of a configured class is given:
-
-[source,java]
-.Most simple configured class
---------------------------------------------
-pubic class ConfiguredItem{
- @Config
- private String aValue;
-}
---------------------------------------------
-
-When this class is configured, e.g. by passing it to +ConfigurationInjector.getInstance().configure(Object)+,
-the following is happening:
-
-* The current valid +Configuration+ is evaluated by calling +Configuration cfg = ConfigurationProvider.getConfiguration();+
-* The current property value (String) is evaluated by calling +cfg.get("aValue");+ for each possible key (mutliple
- keys are possible).
-* if not successful, an error is thrown (+ConfigException+)
-* On success, since no type conversion is involved, the value is injected.
-
-==== Using @DefaultValue
-
-In the next example we explicitly define the property value:
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
-
- @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
- private String aValue;
-}
---------------------------------------------
-
-==== Inject a DynamicValue Property
-
-Within this example we evaluate a dynamic value. This mechanism allows you to listen for configuration changes and to
-commit new values exactly, when convenient for you.
-
-[source,java]
---------------------------------------------
-pubic class ConfiguredItem{
-
- @Config(value={"aValue", "a.b.value","a.b.deprecated.value"}, defaultValue="${env:java.version}")
- private DynamicValue aValue;
-}
---------------------------------------------
-
-The +DynamicValue+ provides you the following functionality:
-
-[source,java]
---------------------------------------------
-public interface DynamicValue<T> {
-
- enum UpdatePolicy{
- IMMEDIATE,
- EXPLCIT,
- NEVER,
- LOG_AND_DISCARD
- }
-
- T get();
- T getNewValue();
- T evaluateValue();
- T commitAndGet();
- void commit();
- void discard();
- boolean updateValue();
-
- void setUpdatePolicy(UpdatePolicy updatePolicy);
- UpdatePolicy getUpdatePolicy();
- void addListener(PropertyChangeListener l);
- void removeListener(PropertyChangeListener l);
-
- boolean isPresent();
- T orElse(T other);
- // Enabled with Java 8
- // T orElseGet(ConfiguredItemSupplier<? extends T> other);
- // <X extends Throwable> T orElseThrow(ConfiguredItemSupplier<? extends X> exceptionSupplier) throws X;
-
-}
---------------------------------------------
-
-Summarizing this class looks somehow similar to the new +Optional+ class added with Java 8. It provides
-a wrapper class around a configured instance. Additionally this class provides functionality that gives
-active control, to manage a configured value based on a ++LoadingPolicy+:
-
-* +IMMEDEATE+ means that when the configuration system detects a change on the underlying value, the new value
- is automatically applied without any further notice.
-* +EXPLICIT+ means that a new configuration value is signalled by setting the +newValue+ property. if +getNewValue()+
- returns a non null value, the new value can be applied by calling +commit()+. You can always access the newest value,
- hereby implicitly applying it, by accessing it via +commitAndGet()+. Also it is possible ti ignore a change by calling
- +discard()+.
-* +NEVER+ means the configured value is evaluated once and never updated. All changes are silently discarded.
-* +LOG_AND_DISCARD+ similar to +NEVER+, but changes are logged before they are discarded.
-
-Summarizing a +DynamicValue+ allows you
-
-* to reload actively updates of configured values.
-* update implicitly or explicitly all changes on the value.
-* add listeners that observe changes of a certain value.
-
-Dynamic values also allow on-the-fly reevaluation of the value by calling +evaluateValue()+. Hereby the value of the
-instance is not changed.
-
-
-==== Ommitting Injection using @NoConfig
-
-Adding the @NoConfig annotation prevents a field or method to be auto-injected from
-configuration. This is especially useful, if a type is annotated as @ConfigAutoInject with auto-confiuration
-turned on as follows:
-
-[source,java]
---------------------------------------------
-@ConfigAutoInject
-pubic class ConfiguredItem{
-
- @NoConfig
- private transient int sum;
-
- private String a;
- private String b;
- Private String c;
-}
---------------------------------------------
-
-In this case the fields +a,b,c+ are configured, whereas the field +sum+ is ignored regarding
-configuration.
-
-==== Adding custom operators using @WithConfigOperator
-
-The @WithConfigOperator annotation allows you define a class of type +ConfigOperator+, to being applied
-to the final +Configuration+, BEFORE the value is injected. This can be used for various use cases, e.g.
-filtering or validating the visible properties for a certain use case.
-
-[source,java]
---------------------------------------------
-
-@WithConfigOperator(MyConfigView.class)
-pubic class ConfiguredItem{
-
- @Config
- private String a;
-
-}
---------------------------------------------
-
-
-==== Adding custom property converters using @WithPropertyConverter
-
-The @WithPropertyConverter annotation allows you to define a class of type +PropertyConverter+, to be applied
-on a property configured to convert the String value to the expected injected type. This can be used for
-various use cases, e.g. adding custom formats, config models, decryption.
-
-[source,java]
---------------------------------------------
-
-pubic class ConfiguredItem{
-
- @WithPropertyConverter(MyPropertyConverter.class)
- @Config
- private String a;
-
-}
---------------------------------------------
-
-
-==== Defining the loading policy to be applied to configured values using @WithLoadPolicy
-
-The @WithLoadPolicy annotation allows to define the loading behaviour to be applied. The +LoadPolicy+
-enum hereby defines the various loading modes.
-
-[source,java]
---------------------------------------------
-
-@WithLoadPolicy(LoadPolicy.NEVER)
-pubic class BootTimeStableConfig{
-
- @WithPropertyConverter(MyPropertyConverter.class)
- @Config
- private String a;
-
-}
---------------------------------------------
-
-
-=== Configuration Events
-
-Similar to CDI Tamaya publishes Configuration events, when instances were configured. It depends on the effective
-event backend in use, if and how events are published:
-
-* when you have the CDI extension active events are published using the default CDI event mechanism.
-* in all other scenarios events are delegated to the +tamaya-events+ module, if available,
-* if no event delegation is available no events are published.
-
-The event published is very simple:
-
-[source,java]
---------------------------------------------
-public interface ConfiguredType {
- Class getType();
- String getName();
- public Collection<ConfiguredField> getConfiguredFields();
- Collection<ConfiguredMethod> getConfiguredMethods();
- void configure(Object instance, Configuration config);
-}
-
-
-public interface ConfiguredField {
- Class<?> getType();
- Collection<String> getConfiguredKeys();
- String getName();
- String getSignature();
- Field getAnnotatedField();
- void configure(Object instance, Configuration config);
-}
-
-public interface ConfiguredMethod {
- Collection<String> getConfiguredKeys();
- Class<?>[] getParameterTypes();
- Method getAnnotatedMethod();
- String getName();
- String getSignature();
- void configure(Object instance, Configuration config);
-}
-----------------------------------------
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_jodatime.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_jodatime.adoc b/src/site/asciidoc/extensions/mod_jodatime.adoc
deleted file mode 100644
index 6dd05b6..0000000
--- a/src/site/asciidoc/extensions/mod_jodatime.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: JodaTime
-
-toc::[]
-
-[[Core]]
-== Tamaya JodaTime (Extension Module)
-
-=== Overview
-
-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 retrieve Joda-Time types from a given configuration.
-
-Refer to the link:modules.html[extensions documentation] for further details
-about modules.
-
-tools to locate resources in your classpath or file system based on descriptive
-ant-styled resource patterns. To use this module add the following dependency:
-
-[source, listing]
------------------------------------------------
-<dependency>
- <grooupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-jodatime</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-After adding this dependency to your project you can retrieve
-Joda-Time based values directly from a given configuration.
-
-[source,java]
------------------------------------------------
-Configuration configuration = ConfigurationProvider.getConfiguration();
-
-DateTime pit = configuration.get("pointInTime", DateTime.class)
------------------------------------------------
-
-=== Specifying date and time values
-
-To be written.
-
-=== Specifing periods and durations
-
-To be written.
-
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_json.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_json.adoc b/src/site/asciidoc/extensions/mod_json.adoc
deleted file mode 100644
index 691b27b..0000000
--- a/src/site/asciidoc/extensions/mod_json.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Builder
-
-toc::[]
-
-
-[[BuilderCore]]
-== Tamaya JSON (Extension Module)
-=== Overview
-
-The Tamaya json module provides support for reading configuration using the JSON format:
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-json</artifactId>
- <version>{tamayaVersion}</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 provided:
-
-[source, java]
------------------------------------------------
-ConfigurationData dataRead = ConfigurationFormats.readConfig(
- getClassLoader().getResource("myFileConfig.json"), new JSONFormat()));
------------------------------------------------
-
-=== Examples
-
-The JSON module adds instances of +ConfigurationFormat+ so JSON configuration can be read and mapped to the
-according property maps. E.g. the following file is a simple and correct JSON configuration:
-
-[source,listing]
-----------------------------------------------------------------
-{
- "a" : "A",
- "b" : "B",
- "c" : "C",
- "d" : {
- "o" : "O",
- "p" : "P"
- }
-}
-----------------------------------------------------------------
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_management.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_management.adoc b/src/site/asciidoc/extensions/mod_management.adoc
deleted file mode 100644
index b9f8de0..0000000
--- a/src/site/asciidoc/extensions/mod_management.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: JMX Management Access
-
-toc::[]
-
-
-[[ExtModel]]
-== Tamaya Management (JMX Support) (Extension Module)
-=== Overview
-
-The Tamaya management module provides support for registering a JMX management bean for accessing configuration.
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-management</artifactId>
- <version>{tamayaVersion}</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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_mutable_config.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_mutable_config.adoc b/src/site/asciidoc/extensions/mod_mutable_config.adoc
deleted file mode 100644
index d38626e..0000000
--- a/src/site/asciidoc/extensions/mod_mutable_config.adoc
+++ /dev/null
@@ -1,283 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Mutable Configuration
-
-toc::[]
-
-
-[[Core]]
-== Tamaya Mutable Configuration (Extension Module)
-=== Overview
-
-Tamaya Configuration by default is read-only, which covers must of the use cases. But there are many legit scenarios
-where configuration should be written back to some backend systems or the local file system. This module adds this
-functionality.
-
-=== Compatibility
-
-The module is based on Java 7, so it can be used with Java 7 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>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-=== Core Architecture
-
-==== Accessing MutableConfiguration
-
-The core of the module is the +MutableConfigurationProvider+ singleton, which provides access to +MutableConfiguration+
-instance, which extends +Configuration+. This interface adds additional methods to add/update or remove property values.
-Hereby changes applied are managed in a transaction like context, called +ConfigChangeContext+. Each context defines
-a UUID that identifes a change.
-Backends for writing changes applied are of type +MutablePropertySource+, similarly extending the +PropertySource+
-SPI with methods for writing changes back. Registrations and ordering policies are like with ordinary property sources,
-with one important difference. Mutable property source can be targeted by write operations.
-
-The example below shows how a +MutableConfiguration+ can be obtained the simplest way:
-
-[source,java]
-.Accessing and changing configuration
---------------------------------------------
-MutableConfiguration config = MutableConfigurationProvider
- .createMutableConfiguration();
-config.put("newKey", "newValue")
- .put("anotherKey", "updatedValue")
- .remove("valueNotValid")
- .store();
---------------------------------------------
-
-In the above scenario we use the overall system's configuration as the backend to be used.
-We can also pass any +Configuration+ to render it into a mutable instance, e.g.
-
-[source,java]
-.Explicitly passing the backing configuration
---------------------------------------------
-Configuration config = ...;
-MutableConfiguration config = MutableConfigurationProvider
- .createMutableConfiguration(config);
---------------------------------------------
-
-NOTE: If a configuration does not contain any +MutablePropertySource+ instances,
- a +MutableConfiguration+ built from it will not be able to accept any changes.
-
-
-Following you see the options how to create a +MutableConfiguration+ using the
-+MutableConfigurationProvider+ singleton:
-
-[source, java]
----------------------------------------------
-public final class MutableConfigurationProvider {
-
- private MutableConfigurationProvider(){}
-
- public static MutableConfiguration createMutableConfiguration();
- public static MutableConfiguration createMutableConfiguration(
- ChangePropagationPolicy changePropgationPolicy);
- public static MutableConfiguration createMutableConfiguration(Configuration configuration);
- public static MutableConfiguration createMutableConfiguration(
- Configuration configuration,
- ChangePropagationPolicy changePropgationPolicy);
-
- [...]
-}
----------------------------------------------
-
-Hereby +MutableConfiguration+ is defined as follows:
-
-[source, java]
----------------------------------------------
-public interface MutableConfiguration extends Configuration {
-
- void store();
-
- ConfigChangeRequest getConfigChangeRequest();
- ChangePropagationPolicy getChangePropagationPolicy();
-
- MutableConfiguration put(String key, String value);
- MutableConfiguration putAll(Map<String, String> properties);
- MutableConfiguration remove(Collection<String> keys);
- MutableConfiguration remove(String... keys);
-
-}
----------------------------------------------
-
-
-==== Targeting the right MutablePropertySources
-
-A +Configuration+ may have multiple +MutablePropertySource+ instances present. These are members of Tamaya's oredered list of
-+PropertySources+ to evaluate the configuration. Nevertheless writing back changes requires additional aspects to
-be considered:
-* Should changes being written back to all mutable property sources? Or should a key that could be added or removed
- on a more significant instance not be written/removed on less significant property source instances?
-* Should a change be applied only to a specific mutable property source, regardless its position in the
- processing chain?
-
-Therefore a +ChangePropagationPolicy+ can be set on a +MutableConfiguration+ 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 propertySources the property sources, including readable property sources of the current configuration,
- * never null.
- * @param configChange the configuration change, not null.
- */
- void applyChange(ConfigChangeRequest configChange, Collection<PropertySource> propertySources);
-}
---------------------------------------------
-
-By default, changes are applied to all registered +MutablePropertySources+ similarly.
-
-
-Also the +MutableConfigurationProvider+ provides access to the most commonly used change propagation policies:
-
-[source, java]
----------------------------------------------
-public final class MutableConfigurationProvider {
-
- [...]
-
- 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. Nevertheless
-changing or adding value is very easy:
-
-[source,java]
-.Changing a configuration
---------------------------------------------
-MutableConfiguration config = MutableConfigurationProvider.createMutableConfiguration();
-config.put("newKey", "newValue");
-config.remove("mycluster.myapp.myKey");
-config.store();
---------------------------------------------
-
-
-=== Configuration Changes
-
-This module does not handle detection of changes to the overall system's +Configuration+. 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 +MutableConfigurationBackendSpi+ may inform/update any affected +PropertySource,
- PropertySourceProvider+ instances about the changes applied.
-
-
-=== Supported Backends
-
-Multiple backends are supported. E.g. the _etcd_ integration module of Tamaya also registers
-corresponding SPI implementations/backends. By default this module comes with
-the following +MutablePropertySource+ implementations:
-
-* +MutablePropertySource+ resources, targeting local +.properties+ files, using the +java.util.Properties+
- format.
-* +MutableXmlPropertySource+ resources, targeting local +.xml+ property files, using the +java.util.Properties+
- XML format.
-
-==== Refreshable Property Sources
-
-Somehow similar to configuration changes applied explicitly is the case, where values of underlying
-configuration backends change and must be reflected in the new configuration tree. Examples are:
-
-* Configuration files being edited, added or removed.
-* Changes on remote servers like etcd, consul
-* etc.
-
-For having a common API for refreshable items a +Refreshable+ interface is defined:
-
-[source,java]
-.Refreshable interface
---------------------------------------------
-/**
- * Interface to be implemented by items that can be refreshed. By default
- * these are property sources, but more types may be supported at a later
- * point in time.
- */
-public interface Refreshable {
-
- /**
- * Refreshes the item by reloading its internal state.
- */
- void refresh();
-
-}
---------------------------------------------
-
-
-==== Refreshable Property Sources
-
-=== SPIs
-
-The module defines +MutableConfigurationProviderSpi+, that is used as a delegate by the +MutableConfigurationProvider+
-singleton accessor:
-
-[source,java]
-.SPI: MutableConfigurationProviderSpi
---------------------------------------------------
-public interface MutableConfigurationProviderSpi {
- /**
- * Creates a new {@link MutableConfiguration} 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.
- */
- MutableConfiguration createMutableConfiguration(Configuration 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/blob/63124d1f/src/site/asciidoc/extensions/mod_optional.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_optional.adoc b/src/site/asciidoc/extensions/mod_optional.adoc
deleted file mode 100644
index 369df68..0000000
--- a/src/site/asciidoc/extensions/mod_optional.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Optional Tamaya Configuration
-
-toc::[]
-
-
-[[Optional]]
-== Tamaya Optional Configuration (Extension Module)
-=== Overview
-
-The Tamaya optional module provides contains three types only. It 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 artofacts.
-It automatically checks the availability of Tamaya on the classpath and only if available 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 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration builder support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-optional</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-
-=== Reading configuration using the Tamaya Optional Module
-
-The optional module allows reading configuration with a small subset of functionality only. For extended of full
-featured config please consider using the Apache Tamaya as a full configuration backend.
-
-[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/blob/63124d1f/src/site/asciidoc/extensions/mod_osgi.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_osgi.adoc b/src/site/asciidoc/extensions/mod_osgi.adoc
deleted file mode 100644
index 52518a7..0000000
--- a/src/site/asciidoc/extensions/mod_osgi.adoc
+++ /dev/null
@@ -1,130 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extensions: OSGI Integrations
-
-toc::[]
-
-
-[[Optional]]
-== Tamaya OSGI Support
-=== Overview
-
-Tamaya provides also support for integration with OSGI. Hereby several options are available how Tamaya can be used in
-an OSGI context:
-
-. All Tamaya modules, its API and core library are actually valid OSGI bundles. So adding them into your OSGI modules
- and using Tamaya is basically directly supported. Nevertheless OSGI works rather differently from a class- and
- resource loading perspective. As long as you rely on Tamaya's mechanisms for resource loading things should work
- out of the box. In the back Tamaya's core module actually comes with implicit OSGI support, which is automatically
- activated, if Tamaya is running in an OSGI context. This support actually
- ** Listens on deployed bundles and actively reads all resources configured as +java.util.ServiceLoader+ services and
- registers them as OSGI services. Hereby integration is complete meaning you can also register Tamaya services
- as normal OSGI services, e.g. your own +PropertySource+ instances.
- ** Uses the OSGI bundle to resolve for resources, because accessing them from the classloader directly
- typically fails in an OSGI context.
-. Adding Tamaya's OSGI integration module replaces the existing OSGI +ConfigAdmin+ service with an istance based on
- Tamaya. Hereby several aspects can be configured using system properties:
- ** +org.tamaya.integration.osgi.cm.ranking+ (int) allows to configure the OSGI service ranking used by the Tamaya
- BundleActivator to register Tamaya's +ConfigAdmin+ service. In OSGI higher ranking precede lower rankings. By default
- Tamaya's OSGI extending service registration mechanism is reusing any annotated +@Priority+ priority values as
- corresponsing rankings.
- ** +org.tamaya.integration.osgi.cm.override+ (boolean) allows to configure if Tamaya is overriding any existing
- values from the default +ConfigAdmin+ instance, or only extending them. In other words this setting allows you to
- define, which configuration subsystem has precedence for evaluating the final values, either Tamaya based
- configuration (default) or the configuration mechanisms provided by default from your OSGI container (when this flag
- is set to +false+).
- ** +org.tamaya.integration.osgi.cm.inject+ allows you to deactivate injection of configuration values into your
- OSGI services (by default injection is enabled). In all cases accessing the OSGI +ConfigAdmin+ service to
- read your configuration is working as usual. But Tamaya adds additional injection functionality, which allows
- to inject typed configuration as described by the Tamaya injection api.
-
-It is also possible to combine things, e.g. when you only define a low ranking for Tamaya's configuration service and
-the same time allow injection to be active, you will have Tamaya's injection support based on your default
-OSGI configuration.
-
-
-=== Compatibility
-
-All module described are based on Java 7, so it will run on Java 7 and beyond.
-The modules are built against OSGI Compendium version 5.0.
-
-
-=== Installation
-
-To benefit from Tamaya in an OSGI context you must deploy at least the following modules to your OSGI runtime
-environment:
-
-[source, listing]
------------------------------------------------
-# API and core
-org.apache.tamaya:tamaya-api:{tamayaVersion}
-org.apache.tamaya:tamaya-core:{tamayaVersion}
-org.apache.geronimo.specs:geronimo-annotation_1.2_spec:1.0-alpha-1
-# injection API. SE injection module and dependencies
-org.apache.tamaya.ext:tamaya-injection-api:{tamayaVersion}
-org.apache.tamaya.ext:tamaya-injection:{tamayaVersion}
-org.apache.geronimo.specs:geronimo-atinject_1.0_spec:1.0
-org.apache.geronimo.specs:geronimo-el_2.2_spec:1.0.4
-org.apache.geronimo.specs:geronimo-interceptor_1.1_spec:1.0
-org.apache.geronimo.specs:geronimo-jcdi_1.1_spec:1.0
-# OSGI integration and dependencies
-org.apache.tamaya.ext:tamaya-osgi:{tamayaVersion}
-org.apache.tamaya.ext:tamaya-functions:{tamayaVersion}
------------------------------------------------
-
-
-=== Usage
-
-As an example, what is possible you can implement an OSGI service as a normal POJO and publish it as an OSGI service.
-Given that configuration can be injected very easily:
-
-[source, java]
------------------------------------------------
-public class HelloServiceImpl implements HelloService{
-
- @Config("example.message")
- @ConfigDefault("A Tamaya default.")
- private String message;
-
- @Override
- public String sayHello() {
- System.err.println("HELLO: " + message);
- return message;
- }
-}
------------------------------------------------
-
-
-=== SPI
-
-By defauklt the OSGI pid or factory pid is mapped to a corresponding root section in Tamaya's configuration. We are
-well aware that this might not always be the desired approach. Therefore there as an SPI service provided that allows
-to determine this mapping:
-
-[source, java]
-.OSGIConfigRootMapper
------------------------------------------------
-public interface OSGIConfigRootMapper {
-
- String getTamayaConfigRoot(String pid, String factoryPid);
-}
------------------------------------------------
-
-Registering your own implementation as an OSGI service allows you to redefine the key mapping.
-By default a configuration mapping for +pid/factoryPid==myBundle+ is mapped to +[bundle:myBundle]+.
-This mapping is used as a prefix when collecting the corresponding entries for the OSGI configuration.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_remote.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_remote.adoc b/src/site/asciidoc/extensions/mod_remote.adoc
deleted file mode 100644
index d82b7ba..0000000
--- a/src/site/asciidoc/extensions/mod_remote.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Remote Configuration
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Remote Configuration (Extension Module)
-=== Overview
-
-The Tamaya remote module provides support for reading configuration from remote resources. It provides
-especially out-of-the-box support for reading scoped configuration from a configuration server as
-provided with the _Tamaya server module_ .
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration builder 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>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-
-=== Reading Remote configuration from a Tamaya Configuration Server
-
-The remote module allows reading JSON formatted onfiguration 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": "",
- "{meta}class": "org.apache.tamaya.functions.FilteredConfiguration",
- "{meta}info.filter": "java.v,sun",
- "{meta}info.format": "application/json",
- "{meta}info.timestamp": "1441463200571",
- "{meta}timestamp": "1441463200571",
- "{meta}type": "Configuration"
-}
------------------------------------------------
-
-Basically there are no constraints about they keys provided. By default Tamaya uses keys prefixed with
-+{xxx}+ 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 URL that is successfully accessed determines the configuration read and imported into the
-+PropertySource+.
-
-[source, java]
------------------------------------------------
-public class RemotePropertySource extends BaseRemotePropertySource{
- /** Current remote property source default ordinal. */
- private static final int REMOTE_ORDINAL = 15000;
-
- @Override
- public int getDefaultOrdinal(){
- return REMOTE_ORDINAL;
- }
-
- @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();
- }
- }
-
-}
------------------------------------------------
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_resolver.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_resolver.adoc b/src/site/asciidoc/extensions/mod_resolver.adoc
deleted file mode 100644
index c502272..0000000
--- a/src/site/asciidoc/extensions/mod_resolver.adoc
+++ /dev/null
@@ -1,143 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Resolver
-
-include::temp-properties-files-for-site/attributes.adoc[]
-
-
-[[Core]]
-== Tamaya Resolver (Extension Module)
-
-=== Overview
-
-Tamaya Resolver is an extension module. Refer to the
-// @todo Fix the link to the modules documentation
-link:modules.html[extensions documentation]
-for further details about modules.
-
-Tamaya Resolver provides a dynamic resolution mechanism, which allows to use UNIX-styled (+${...}+ placeholder
-expressions in your configuration values. The resolver hereby supports transitive resolution and also prevents
-cycles to loop endlessly.
-
-=== Compatibility
-
-The module is based on Java 7, so it can be used with Java 7 and beyond.
-
-=== Installation
-
-To benefit from dynamic value resolution you only must add the corresponding dependency to your module:
-
-[source, xml, subs="verbatim,attributes"]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-resolver</artifactId>
- <version>{tamaya_version_development}</version>
-</dependency>
------------------------------------------------
-
-The module automatically registers an according +PropertyFilter+ that is automatically called, whenever a value
-is accessed.
-
-=== Available Resolvers
-
-Currently the module defined the following resolvers:
-
-.Available Resolvers
-[cols="<.1,<.2,<.1"]
-|=======
-| _Expression_
-| _Description_
-| _Example_
-
-| +conf:<configKey>+
-| Reads another configKey and replaces the expression with the value found.
-| conf-ref=${conf:anotherConf.entryKey}
-
-| +resource:<resourceRef>+
-| Reads a resource from the current classpath and replaces the expression with the given text content.
-| cp-ref=${resource:Testresource.txt}
-
-| +file:<fileRef>+
-| Reads a resource from the current classpath and replaces the expression with the given text content.
-| file-ref=${file:c:\myFile.txt}
-
-|+url:<url>+
-|Reads an URL and replaces the expression with the given text content.
-| url-ref=${url:http://www.google.com}
-
-|=======
-
-=== SPI: Implementing your own Resolvers
-
-The module also provides an easy but powerful SPI for adding your own resolver implementations. Basically the
-first and most important thing to do is implementing the +ExpressionResolver+ interface:
-
-.Implementing a Custom Resolver
-[source, java]
------------------------------------------------
-public class PwdDecrypter implements ExpressionResolver {
-
- @Override
- public String getResolverPrefix() {
- return "decrypt:";
- }
-
- @Override
- public String evaluate(String expression) {
- return decrypt(expression);
- }
-
- private String decrypt(String s) {
- ...
- }
-}
------------------------------------------------
-
-Basically that is all you must do, after having registered the class with the +ServiceLoader+ it will be found
-and loaded by the implementation. With that all expressions that start with the given prefix are passed to the
-resolver, so all the following expressions will be sent to the implementation:
-
-[source,listing]
------------------------------------------------
-blabla ${decrypt:myname}
-blabla ${decrypt:myname} foo blabla ${decrypt:myname}
------------------------------------------------
-
-Hereby evaluation is repeated until no further change of values could be detetced. In case of a endless loop
-the evaluation is broken after a (configurable) number of cycles.
-
-
-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 yhou should be fine with
-the default implementation in place.
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_resources.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_resources.adoc b/src/site/asciidoc/extensions/mod_resources.adoc
deleted file mode 100644
index 7506859..0000000
--- a/src/site/asciidoc/extensions/mod_resources.adoc
+++ /dev/null
@@ -1,172 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Resources
-
-include::temp-properties-files-for-site/attributes.adoc[]
-
-[[Core]]
-== Tamaya Resources (Extension Module)
-=== Overview
-
-Tamaya Resources is an extension module. Refer to the
-// @todo Fix the link to the modules page
-link:modules.html[extensions documentation] for further details
-about modules.
-
-Tamaya Resources defines some additional tools to locate resources in your classpath or file system based on descriptive
-ant-styled resource patterns. To use this module add the following dependency:
-
-[source, listing, subs="verbatim,attributes"]
------------------------------------------------
-<dependency>
- <grooupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-resources</artifactId>
- <version>{tamaya_version_development}</version>
-</dependency>
------------------------------------------------
-
-
-The module's main entry point is the singleton class +org.apache.tamaya.resource.ConfigResources+. This class
-provides access to a +ResourceResolver+ instance:
-
-[source,java]
------------------------------------------------
-ResourceResolver resolver = ConfigResources.getResourceResolver();
------------------------------------------------
-
-[source,java]
------------------------------------------------
-public interface ResourceResolver {
- Collection<URL> getResources(Collection<String> expressions) {...}
- Collection<URL> getResources(String... expressions) {...}
- Collection<URL> getResources(ClassLoader classLoader, String... expressions){...}
- Collection<URL> getResources(ClassLoader classLoader, Collection<String> expressions);
-}
------------------------------------------------
-
-Hereby the methods allow to resolve expressions to a collection of URLs. In case the expression is also targeting the
-current classpath the target +ClassLoader+ to be used can be passed additionally.
-
-The default implementation provides resource resolution mechanism similar to the functionality offered by Spring.
-So by default resources can be looked up
-
-* from files
-* from the classpath
-* optionally ant-styled expressions can be used.
-
-=== Valid Expression Examples
-
-There are numerous ways how a resource pattern can be defined. Following the most important variants
-are listed:
-
-[source,listing]
------------------------------------------------
-// explicitly searching the file system
-file:myroot/aa?a/*.file
-file:myroot/b*/b?/*.file
-file:myroot/**/*.file
-
-// explicitly searching the classpath
-classpath:myroot/**/*.file
-classpath:javax/annotation/*.class
-classpath:javax/**/sql/*.class
-classpath:javax/annotation/**/R*.class
-classpath:javax/annotation/R?so*.class
-classpath:META-INF/maven/org.apache.geronimo.specs/**/*
-
-// search both classpath and files
-javax/annotation/*.class
-javax/**/sql/*.class
-javax/annotation/**/R*.class
-javax/annotation/R?so*.class
-META-INF/maven/org.apache.geronimo.specs/**/*
-myroot/**/*.file
-myroot/aa?a/*.file
-myroot/b*/b?/*.file
------------------------------------------------
-
-Summarizing the resources module provides useful functionality that helps to locate resources on the file system and
-in the classpath. This can be used to implement +PropertySourceProvider+ implementations that are based on
-corresponding resource path patterns instead of concrete files.
-
-
-=== Overall Usage Example
-
-Given the functionality we can easily implement a +PropertySourceProvider+ that reads all files from a classpath
-location, hereby traversing down all folders:
-
-
-[source, java]
--------------------------------------------------------------
-public class PathBasedPropertySourceProvider implements PropertySourceProvider {
-
- @Override
- public Collection<PropertySource> getPropertySources() {
- List<PropertySource> propertySources = new ArrayList<>();
- Collection<URL> resources = Resources.getResourceResolver().getResources("META-INF/cfg/**/*.properties");
- for(URL url:resources){
- Properties props = new Properties();
- try(InputStream is = url.openStream()){
- props.load(is);
- propertySources.add(new PropertiesBasedPropertySource(url.toString(), props));
- }
- catch(Exception e){
- e.printStackTrace();
- }
- }
-
- return propertySources;
- }
-
- private final static class PropertiesBasedPropertySource implements PropertySource {
- private String name;
- private Map<String,String> properties = new HashMap<>();
-
- public PropertiesBasedPropertySource(String name, Properties props) {
- this.name = name;
- props.forEach((k,v) -> this.properties.put(k.toString(), v.toString()));
- }
-
- @Override
- public String getName() {
- return name;
- }
-
- @Override
- public String get(String key) {
- return properties.get(key);
- }
-
- @Override
- public Map<String, String> getProperties() {
- return properties;
- }
- }
-}
--------------------------------------------------------------
-
-
-=== SPI
-
-The +ResourceResolver+ that is returned by the +ConfigResources+ singleton is determined by the
-current +ServiceContext+, by default you can replace the default implementation by registering an
-alternate implementation with an overriding +@Priority+ annotation added using the +ServiceLoader+.
-
-Additionally a +BaseResourceResolver+ class can be used to reduce the amount of code to be written
-on your own.
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_server.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_server.adoc b/src/site/asciidoc/extensions/mod_server.adoc
deleted file mode 100644
index 44398d7..0000000
--- a/src/site/asciidoc/extensions/mod_server.adoc
+++ /dev/null
@@ -1,382 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Configuration Server
-
-toc::[]
-
-
-[[Remote]]
-== Tamaya Configuration Server (Extension Module)
-=== Overview
-
-The Tamaya server module provides support for providing scoped configuration using a http server serving JSON formatted
-configuration properties.
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from configuration server support you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-server</artifactId>
- <version>{tamayaVersion}</version>
-</dependency>
------------------------------------------------
-
-
-=== Providing configuration using the Tamaya Built-in Configuration Server
-
-THe most simple way for providing onfiguration ist to start the internal server:
-
-[source, java]
------------------------------------------------
-Server server = org.apache.tamaya.server.ConfigServer.createServer();
-server.start(port);
------------------------------------------------
-
-This will start a simple server instance that serves the following URL patterns:
-
-* +GET /config+ provides access to the full configuration tree.
-* +GET /config/filtered/${path}+ let you filter the configuration returned using regular expression (comma separated).
- E.g. +/config/filtered/java,sun+ will return all configuration entries starting with _java_ and _sun_.
-
-Additionally the server module has the following options implemented, which can be passed as additional, optional
-parameters:
-
-* +format+ allows to define the target format. By default the +ACCEPT+ header of the http request is checked, but this
- setting can be explicitly controlled by passing tis parameter explicitly. The value is the expected MIME type to be
- returned. By default the service supports the following types (refer to the SPI section later in this document for
- options to adapt this):
- ** text/html
- ** text/plain
- ** application/xml
- ** text/json
-
-* +scope,scopeId+ allows to use a server-side preconfigured filter/combination policy to be applied for
- evaluating the entries to be returned. Hereby the +scopeId+ paramter allows to address a certain scope.
- As an example think of a scope +?scope=CLIENT&scopeId=client1+ to be passed as request parameters. This
- tells the server module to lookup a configured scope named 'CLIENT' and access a +ConfigOperator+ for the
- given scopeId 'client1'. The returned operator then can filter and combine any kind of entries to the
- required client configuration (for client1). Refer to the scopes section for more details.
-
-
-=== Using the Configuration Servlets
-
-Additionally to the fully built-in solution, it is also possible to integrate the Tamaya server module with a standard
-Java EE servlet container. Tamaya provides 2 servlet implementations:
-
-* the servlet +org.apache.tamaya.server.FilteredConfigServlet+ can be used to register access to configurations
- that also support filtering of the keys. The URL looks like
-
-----------------------------------------------------------
-http(s)://HOST/SERVLET_CONTEXT/PATHS?params
-
-where
- HOST = host name incl port, e.g. 127.0.0.2:234
- SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
- PATHS = A comma separated number of key paths to be filtered for being returned, e.g.
- java,sun,client
- params = the optional parameters (scope, scopeId and format)
-----------------------------------------------------------
-
-* the servlet +org.apache.tamaya.server.FullConfigServlet+ can be used to register access to configurations
- that alwyas returns all items known. The URL looks like
-
-----------------------------------------------------------
-http(s)://HOST/SERVLET_CONTEXT?params
-
-where
- HOST = host name incl port, e.g. 127.0.0.2:234
- SERVLET_CONTEXT = the base context and servlet context, e.g. /client/config/filtered
- params = the optional parameters (scope, scopeId and format)
-----------------------------------------------------------
-
-==== Formatting used by Default
-
-The server module formats the configuration returned by default in thw following variants:
-
-.Formatting for +text/json+
-
-[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": "",
- "{meta}class": "org.apache.tamaya.functions.FilteredConfiguration",
- "{meta}info.filter": "java.v,sun",
- "{meta}info.format": "application/json",
- "{meta}info.timestamp": "1441463200571",
- "{meta}timestamp": "1441463200571",
- "{meta}type": "Configuration"
-}
------------------------------------------------
-
-
-.Formatting for +application/xml+
-
-[source, xml]
------------------------------------------------
-<configuration>
- <entry key="java.vendor.url">http://java.oracle.com/</entry>
- <entry key="java.vendor.url.bug">http://bugreport.sun.com/bugreport/</entry>
- <entry key="java.vm.info">mixed mode</entry>
- <entry key="java.vm.name">Java HotSpot(TM) 64-Bit Server VM</entry>
- <entry key="java.vm.specification.name">Java Virtual Machine Specification</entry>
- <entry key="java.vm.specification.vendor">Oracle Corporation</entry>
- <entry key="java.vm.specification.version">1.8</entry>
- <entry key="java.vm.vendor">Oracle Corporation</entry>
- <entry key="java.vm.version">25.45-b02</entry>
- <entry key="sun.arch.data.model">64</entry>
- <entry key="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</entry>
- <entry key="sun.boot.library.path">C:\apps\jdk18\jre\bin</entry>
- <entry key="sun.cpu.endian">little</entry>
- <entry key="sun.cpu.isalist">amd64</entry>
- <entry key="sun.desktop">windows</entry>
- <entry key="sun.io.unicode.encoding">UnicodeLittle</entry>
- <entry key="sun.java.command">com.intellij.rt.execution.application.AppMain org.apache.tamaya.examples.remote.server.Start</entry>
- <entry key="sun.java.launcher">SUN_STANDARD</entry>
- <entry key="sun.jnu.encoding">Cp1252</entry>
- <entry key="sun.management.compiler">HotSpot 64-Bit Tiered Compilers</entry>
- <entry key="sun.os.patch.level"></entry>
- <entry key="{meta}class">org.apache.tamaya.functions.FilteredConfiguration</entry>
- <entry key="{meta}info.filter">java.v,sun</entry>
- <entry key="{meta}info.format">application/xml</entry>
- <entry key="{meta}info.timestamp">1441463383687</entry>
- <entry key="{meta}timestamp">1441463383687</entry>
- <entry key="{meta}type">Configuration</entry>
-</configuration>
------------------------------------------------
-
-
-.Formatting for +text/plain+
-
-[source, text]
------------------------------------------------
-
-Configuration:
- 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: ,
- {meta}class: org.apache.tamaya.functions.FilteredConfiguration,
- {meta}info.filter: java.v,sun,
- {meta}info.format: text/plain,
- {meta}info.timestamp: 1441463082020,
- {meta}timestamp: 1441463082021,
- {meta}type: Configuration
------------------------------------------------
-
-
-.Formatting for +application/html+
-
-[source, html]
------------------------------------------------
-<html>
-<head><title>System Configuration</title></head>
-<body>
-<h1>Sysem Configuration</h1>
-<p>This view shows the system configuration of devbox-win at Sat Sep 05 16:30:59 CEST 2015.</p><pre>
-Configuration:
- 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: ,
- {meta}class: org.apache.tamaya.functions.FilteredConfiguration,
- {meta}info.filter: java.v,sun,
- {meta}info.format: text/html,
- {meta}info.timestamp: 1441463459653,
- {meta}timestamp: 1441463459654,
- {meta}type: Configuration
-
-</pre>
-</body>
-</html>
------------------------------------------------
-
-=== SPI
-
-==== Scopes
-
-As mentioned earlier in this document scopes can be used to define the exact configuration tree to be returned, e.g.
-as a result of combining multiple sub trees. Following an example of the code to be written to return a configuration
-that combines common client default entries with client specific entries:
-
-[source, java]
------------------------------------------------
-public class ClientScopeProvider implements ScopeProvider{
-
- /**
- * Access the unique scope name.
- * @return the unique scope name.
- */
- public String getScopeType(){
- return "CLIENT";
- }
-
- @Override
- public ConfigOperator getScope(String scopeId) {
- return c ->
- ConfigurationFunctions.combine("Scoped Config CLIENT="+scopeId,
- c.with(ConfigurationFunctions.sectionRecursive(true, "client.default")),
- c.with(ConfigurationFunctions.sectionRecursive(true, "client." + scopeId))
- );
- }
-}
------------------------------------------------
-
-This class can be registered using the +ServiceContext+ in place. By default the +ServiceLoader+ is used, so you will
-have to add the following to +META-INF/services/org.apache.tamaya.server.spi.ScopeProvider+:
-
-[source, listing]
------------------------------------------------
-my.full.packagename.ClientScopeProvider
------------------------------------------------
-
-==== Adapting the Way Configuration is Derived
-
-Finally the effective readong and configuration handling logic can also be replaced or improved. This can be
-done by registering your own implementation of the interface +ConfigProviderService+:
-
-[source, java]
-------------------------------------------------
-public interface ConfigProviderService {
- String getConfigurationWithPath(String path, String format, String scope, String scopeId, HttpServletRequest request);
- String getConfiguration(String format, String scope, String scopeId, HttpServletRequest request);
- void updateConfiguration(String payload, HttpServletRequest request);
- void deleteConfiguration(String paths, HttpServletRequest request);
-}
-------------------------------------------------
-
-By default the +ServiceContextManager+ uses the +java.util.ServiceLoader+ for component loading, so to replace the
-default server code you must register a higher +@Priority+ implementation.
-
-
-==== Replacing the Built-In Server
-
-We have seen earlier that starting a configuration server is pretty easy:
-
-[source, java]
------------------------------------------------
-Server server = org.apache.tamaya.server.ConfigServer.createServer();
-server.start(port);
------------------------------------------------
-
-Nevertheless one may want to replace the used implementation of +Server+. This can be done easily by simply
-registering an overriding implementation if the corresponding interface:
-
-[source, java]
------------------------------------------------
-public interface Server {
- void start(int port);
- boolean isStarted();
- void stop();
- void destroy();
-}
------------------------------------------------
-
-==== The ScopeManager Singleton
-
-Finally whe implementing your own server, you might also benefit from the +ScopeManager+ singleton. Basically this
-class loads all registered +ScopeProvider+ and manages the configured scope instances:
-
-[source, java]
------------------------------------------------
-public final class ScopeManager {
- ...
-
- private ScopeManager(){}
-
- /**
- * Get the scope given its name.
- * @param scopeId the scope name
- * @return the scope matching
- * @throws ConfigException, if nos such scope is defined.
- */
- public static ConfigOperator getScope(String scopeId, String target);
-
- /**
- * Get the defined scope names.
- * @return the defined scope names, never null.
- */
- public static Set<String> getScopes();
-
-}
------------------------------------------------
-
-
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/63124d1f/src/site/asciidoc/extensions/mod_spi-support.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_spi-support.adoc b/src/site/asciidoc/extensions/mod_spi-support.adoc
deleted file mode 100644
index c507c1a..0000000
--- a/src/site/asciidoc/extensions/mod_spi-support.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-= Apache Tamaya -- Extension: Classloader Isolation Support
-
-toc::[]
-
-
-[[SPISupport]]
-== Tamaya SPI Support (Extension Module)
-=== Overview
-
-The Tamaya SPI support module 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.
-
-
-
-=== Compatibility
-
-The module is based on Java 7, so it will not run on Java 7 and beyond.
-
-
-=== Installation
-
-To benefit from Tamaya CDI integration you only must add the corresponding dependency to your module:
-
-[source, xml]
------------------------------------------------
-<dependency>
- <groupId>org.apache.tamaya.ext</groupId>
- <artifactId>tamaya-spisupport</artifactId>
- <version>{tamayaVersion}</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.
-