Return-Path: X-Original-To: apmail-tamaya-commits-archive@minotaur.apache.org Delivered-To: apmail-tamaya-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id E4BF018D8D for ; Sat, 16 Jan 2016 06:40:22 +0000 (UTC) Received: (qmail 73712 invoked by uid 500); 16 Jan 2016 06:40:22 -0000 Delivered-To: apmail-tamaya-commits-archive@tamaya.apache.org Received: (qmail 73682 invoked by uid 500); 16 Jan 2016 06:40:22 -0000 Mailing-List: contact commits-help@tamaya.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tamaya.incubator.apache.org Delivered-To: mailing list commits@tamaya.incubator.apache.org Received: (qmail 73673 invoked by uid 99); 16 Jan 2016 06:40:22 -0000 Received: from Unknown (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 16 Jan 2016 06:40:22 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 67D111801AA for ; Sat, 16 Jan 2016 06:40:22 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 3.227 X-Spam-Level: *** X-Spam-Status: No, score=3.227 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_BADIPHTTP=2, KAM_LAZY_DOMAIN_SECURITY=1, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.554, WEIRD_PORT=0.001] autolearn=disabled Received: from mx1-eu-west.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id RiztT6yZQGEo for ; Sat, 16 Jan 2016 06:40:18 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-eu-west.apache.org (ASF Mail Server at mx1-eu-west.apache.org) with SMTP id 7138531AC4 for ; Sat, 16 Jan 2016 06:40:17 +0000 (UTC) Received: (qmail 73611 invoked by uid 99); 16 Jan 2016 06:40:16 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 16 Jan 2016 06:40:16 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 4478ADFBEE; Sat, 16 Jan 2016 06:40:16 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: anatole@apache.org To: commits@tamaya.incubator.apache.org Date: Sat, 16 Jan 2016 06:40:16 -0000 Message-Id: <71191f79e74d4e3c90f577f3e95622ed@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [1/3] incubator-tamaya git commit: TAMAYA-135: Added mutability for configuration sources or mechanisms. 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.
- * 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 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 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. tamaya-sandbox org.apache.tamaya.ext - Apache Tamaya Sandbox Modules + Apache Tamaya Sandbox This project contains the several extensions that can be used with Tamaya, but are not (yet) ready for a release. pom 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. .. tamaya-sysprops - Apache Tamaya - Configured Java SE System Properties + Apache Tamaya Modules - Configured Java SE System Properties bundle 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. pom 4.0.0 tamaya-ui + Apache Tamaya Modules - UI jsf 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: +: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] +----------------------------------------------- + + org.apache.tamaya.ext + tamaya-mutable-config + {tamayaVersion} + +----------------------------------------------- + +=== 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+ 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+.