tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject [1/3] incubator-tamaya git commit: TAMAYA-135: Added mutability for configuration sources or mechanisms.
Date Sat, 16 Jan 2016 06:40:16 GMT
Repository: incubator-tamaya
Updated Branches:
  refs/heads/master 49d787d8f -> afb2d1a45


http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/ConfigChangeRequest.java
----------------------------------------------------------------------
diff --git a/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/ConfigChangeRequest.java
b/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/ConfigChangeRequest.java
deleted file mode 100644
index 6d393cf..0000000
--- a/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/ConfigChangeRequest.java
+++ /dev/null
@@ -1,136 +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.
- */
-package org.apache.tamaya.mutableconfig;
-
-import org.apache.tamaya.ConfigException;
-import org.apache.tamaya.Configuration;
-
-import java.util.Collection;
-import java.util.Map;
-
-
-/**
- * This interface extends the Configuration interface hereby adding methods to change configuration
entries.
- * Hereby not all configuration entries are necessarily mutable, since some entries may be
read from non
- * mutable areas of configuration. Of course, it is always possible to add a mutable shadow
layer on top of all
- * configuration to enable whatever changes applied. The exact management and storage persistence
algorithm should be
- * transparent.<br/>
- * As a consequence clients should first check, using the corresponding methods, if entries
are to edited or removed
- * actually are eligible for change/creation or removal.
- */
-public interface ConfigChangeRequest{
-
-    /**
-     * Returns the configuration onto which the change should be applied.
-     * @return the corresponding configuration, not null.
-     */
-    Configuration getConfiguration();
-
-    /**
-     * Checks if a configuration key is writable (or it can be added).
-     *
-     * @param keyExpression the key to be cheched for write access (including creation),
not null. Here this could also
-     *                      be a regulat expression, such "as a.b.c.*".
-     */
-    boolean isWritable(String keyExpression);
-
-    /**
-     * Checks if a configuration key is removable. This also implies that it is writable,
but there might be writable
-     * keys that cannot be removed.
-     *
-     * @param keyExpression the keyExpression the key to be cheched for write access (including
creation), not null. Here this could also
-     *                      be a regulat expression, such "as a.b.c.*".
-     */
-    boolean isRemovable(String keyExpression);
-
-    /**
-     * Sets a property.
-     *
-     * @param key the property's key, not null.
-     * @param value the property's value, not null.
-     * @return the former property value, or null.
-     * @throws ConfigException if the key/value cannot be added.
-     */
-    String put(String key, String value);
-
-    /**
-     * Puts all given configuration entries. This method should check that all given properties
are
-     * basically removable, as defined by #isWritable. If any of the passed keys is not writable
during this initial
-     * check, the operation should not perform any configuration changes and throw a {@link
ConfigException}. If errors
-     * occur afterwards, when the properties are effectively written back to the backends,
the errors should be
-     * collected and returned as part of the ConfigException payload. Nevertheless the operation
should in that case
-     * remove all entries as far as possible and abort the writing operation.
-     *
-     * @param properties the properties tobe written, not null.
-     * @throws ConfigException if any of the given properties could not be written.
-     */
-    void putAll(Map<String, String> properties);
-
-    /**
-     * Removes a configuration entry.
-     *
-     * @param key the property's key, not null.
-     * @throws ConfigException if the given cannot be removed.
-     * @return the property's keys.
-     */
-    void remove(String key);
-
-    /**
-     * Removes all given configuration entries. This method should check that all given properties
are
-     * basically removable, as defined by #isRemovable. If any of the passed keys is not
removable during this initial
-     * check, the operation should not perform any configuration changes and throw a {@link
ConfigException}. If errors
-     * occur afterwards, when the properties are effectively written back to the backends,
the errors should be
-     * collected and returned as part of the ConfigException payload. Nevertheless the operation
should in that case
-     * remove all entries as far as possible and abort the writing operation.
-     *
-     * @param keys the property's keys to be removed, not null.
-     * @throws ConfigException if any of the given keys could not be removed.
-     */
-    void removeAll(Collection<String> keys);
-
-    /**
-     * Resets all changes, leaving the request still open for further operations.
-     */
-    void reset();
-
-    /**
-     * Closes the request, sby default any uncommitted changes are committed.
-     */
-    void commit();
-
-    /**
-     * Closes the request,
-     * @param saveChanges flag to control if  any uncommitted changes ahould be written (default:
yes).
-     */
-    void commit(boolean saveChanges);
-
-    /**
-     * Operation to check, if the current request is closed. Closed requests are read-only
and can not be used
-     * for preparing/submitting any configuration changes.
-     * @return true, if this instance is closed.
-     */
-    boolean isCommitted();
-
-    /**
-     * Access the summary of the changes applied
-     * @return
-     */
-    ChangeSummary getChangeSummary();
-
-}

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/spi/ConfigurationChangeProviderSpi.java
----------------------------------------------------------------------
diff --git a/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/spi/ConfigurationChangeProviderSpi.java
b/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/spi/ConfigurationChangeProviderSpi.java
deleted file mode 100644
index e378c0d..0000000
--- a/sandbox/mutable-config/src/main/java/org/apache/tamaya/mutableconfig/spi/ConfigurationChangeProviderSpi.java
+++ /dev/null
@@ -1,37 +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.
- */
-package org.apache.tamaya.mutableconfig.spi;
-
-import org.apache.tamaya.Configuration;
-import org.apache.tamaya.mutableconfig.ConfigChangeRequest;
-
-/**
- * Provider SPI for the {@link org.apache.tamaya.mutableconfig.ConfigChangeProvider}.
- */
-public interface ConfigurationChangeProviderSpi {
-
-   /**
-    * Creates a new change request for the given Configuration.
-    * @param config the configuration.
-    * @return a new ChangeRequest
-    * @throws UnsupportedOperationException if no change providers are registered.
-    */
-    ConfigChangeRequest createChangeRequest(Configuration config);
-
-}

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/sandbox/pom.xml
----------------------------------------------------------------------
diff --git a/sandbox/pom.xml b/sandbox/pom.xml
index 8168c47..249c18a 100644
--- a/sandbox/pom.xml
+++ b/sandbox/pom.xml
@@ -29,7 +29,7 @@ under the License.
     <artifactId>tamaya-sandbox</artifactId>
     <groupId>org.apache.tamaya.ext</groupId>
 
-    <name>Apache Tamaya Sandbox Modules</name>
+    <name>Apache Tamaya Sandbox</name>
     <description>This project contains the several extensions that can be used with
Tamaya, but are not (yet) ready for
         a release.</description>
     <packaging>pom</packaging>

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/sandbox/sysprops/pom.xml
----------------------------------------------------------------------
diff --git a/sandbox/sysprops/pom.xml b/sandbox/sysprops/pom.xml
index 2fe0dd2..96f0cd9 100644
--- a/sandbox/sysprops/pom.xml
+++ b/sandbox/sysprops/pom.xml
@@ -27,7 +27,7 @@ under the License.
         <relativePath>..</relativePath>
     </parent>
     <artifactId>tamaya-sysprops</artifactId>
-    <name>Apache Tamaya - Configured Java SE System Properties</name>
+    <name>Apache Tamaya Modules - Configured Java SE System Properties</name>
     <packaging>bundle</packaging>
 
     <build>

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/sandbox/ui/pom.xml
----------------------------------------------------------------------
diff --git a/sandbox/ui/pom.xml b/sandbox/ui/pom.xml
index bb524f4..b40563e 100644
--- a/sandbox/ui/pom.xml
+++ b/sandbox/ui/pom.xml
@@ -30,6 +30,7 @@ under the License.
     <packaging>pom</packaging>
     <modelVersion>4.0.0</modelVersion>
     <artifactId>tamaya-ui</artifactId>
+    <name>Apache Tamaya Modules - UI</name>
 
     <modules>
         <module>jsf</module>

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/src/site/asciidoc/extensions/index.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/index.adoc b/src/site/asciidoc/extensions/index.adoc
index 9607d80..5f87490 100644
--- a/src/site/asciidoc/extensions/index.adoc
+++ b/src/site/asciidoc/extensions/index.adoc
@@ -47,7 +47,8 @@ Mature extensions have a stable API and SPI, similar to the API and Implementati
 |+org.apache.tamaya.ext:tamaya-functions+     |Provides several functional extension points.
         |link:mod_functions.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-optional+      |Lets a Tamaya configuration to be used as
an optional project extension only.  |link:mod_optional.html[Documentation]
 |+org.apache.tamaya.ext:tamaya-spi-support+   |Tamaya support module for SPI implementation.
         |link:mod_spi-support.html[Documentation]
-|+org.apache.tamaya.ext:tamaya-json+          |Provides format support for JSON based configuration.
 |link:modjson.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-json+          |Provides format support for JSON based configuration.
 |link:mod_json.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-mutable-config+|Provides API/SPI for writing configuration
            |link:mod_mutable_config.html[Documentation]
 |=======
 
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/src/site/asciidoc/extensions/mod_etcd.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/mod_etcd.adoc b/src/site/asciidoc/extensions/mod_etcd.adoc
index 22247fd..a477887 100644
--- a/src/site/asciidoc/extensions/mod_etcd.adoc
+++ b/src/site/asciidoc/extensions/mod_etcd.adoc
@@ -78,6 +78,8 @@ ETcd integration comes basically with 2 artifacts:
   atomic write methods are implemented.
 * The +org.apache.tamaya.etcd.EtcdPropertySource+ is a +PropertySource+ with a default ordinal
of 100 and the name 'etcd', which is
   automatically registered.
+* If the +tamaya-mutable-config+ module is loaded it is possible to write property values
back into the etcd cluster,
+  by accessing a +ConfigChangeRequest+ using the URI +config:etcd+.
 
 === The EtcdAccessor
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/c2f1b151/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
new file mode 100644
index 0000000..e09497b
--- /dev/null
+++ b/src/site/asciidoc/extensions/mod_mutable_config.adoc
@@ -0,0 +1,143 @@
+= Apache Tamaya -- Extension: Events
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.mutableconfig
+:title: Apache Tamaya Extension: Mutable Configuration
+:revnumber: 0.1
+:revremark: Incubator
+:revdate: March 2016
+:longversion: {revnumber} ({revremark}) {revdate}
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <anatole@apache.org>
+:source-highlighter: coderay
+:website: http://tamaya.incubator.apache.org/
+:toc:
+:toc-placement: manual
+:encoding: UTF-8
+:numbered:
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+'''
+
+<<<
+
+toc::[]
+
+<<<
+:numbered!:
+<<<
+[[Core]]
+== Tamaya Mutable Configuration (Extension Module)
+=== Overview
+
+Tamaya Configuration by default is read-only, which covers must of the use cases. Make it
writable through out
+creates also a bunch of new issues, especially with distributed configuration services and
eventual consistency.
+Therefore mutability of configuration is modelled in Tamaya as a separate concern. This module
defines the API
+to be used, whereas multiple mutable backends can register their mechanism to write configuration
properties.
+
+=== 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
+
+The core of the module is the +ConfigChangeManager+ singleton, which creates a +ConfigChangeReuqest+
class for
+a +configurationTarget+ passed. The supported target +URIs+ hereby are determined (and must
be documented) by
+the registered backend spis. If not sure you can call +getSupportedURIInfo()+ to see, which
kind of URI's
+supported.
+As an example writing configuration entries to an +etcd+ server can be done as follows:
+
+[source,java]
+.Writing configuration to etcd
+--------------------------------------------
+ConfigChangeRequest request = ConfigChangeManager.createChangeRequest(new URI("etc:http://127.0.0.1:4441"));
+ChangeSummary summary = request
+                .set("newKey", "newValue").set("anotherKey", "updatedValue")
+                .remove("valueNotValid")
+                .commit();
+--------------------------------------------
+
+The effective effect of your changes to the overall configuration changes cannot be easily
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+ ordinal? Is it overriding or overriden 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.
+. 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 confoguration
may be read-only, which
+may be mutable, how overridings should work and to which backends finally any changes should
be written back. To
+support such fine granular scenarios the +ConfigChangeRequest+ interface also has methods
to determine if a key
+is writable at all for a given configuration target:
+
+[source,java]
+.Checking for mutability
+--------------------------------------------
+ConfigChangeRequest request = ConfigChangeManager.createChangeRequest(new URI("file://$USER_HOME/.myapp/mapp.properties"));
+if(request,isWritable("mycluster.shared.appKey")){
+    request.set("newKey", "newValue")
+    .remove("valueNotValid")
+     .commit();
+}else{
+    request.cancel();
+}
+--------------------------------------------
+
+=== 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 +ConfigChangeManagerSpi+ may inform/update any affected +PropertySource,
+  PropertySourceProvider+ instances about the changes applied.
+
+
+=== SPIs
+
+The module defines only one single SPI, that must be implemented to implement the fabric
method
++createChangeRequest(URI)+ of the +ConfigChangeManager+ singleton:
+
+[source,java]
+.SPI: ConfigEventSpi
+--------------------------------------------------
+public interface ConfigChangeManagerSpi {
+    ConfigChangeRequest createChangeRequest(URI backendURI);
+}
+--------------------------------------------------
+
+Implementations are registered with the current +ServiceContext+, be default as with
+ +java.util.ServiceLoader+.


Mime
View raw message