You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tamaya.apache.org by an...@apache.org on 2016/01/08 12:52:34 UTC
[3/3] incubator-tamaya git commit: TAMAYA-133: Added docu for etcd
support.
TAMAYA-133: Added docu for etcd support.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/846842cb
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/846842cb
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/846842cb
Branch: refs/heads/master
Commit: 846842cb24daed70157dd921b2a203205ff0bb80
Parents: 895dfd8
Author: anatole <an...@apache.org>
Authored: Fri Jan 8 12:52:25 2016 +0100
Committer: anatole <an...@apache.org>
Committed: Fri Jan 8 12:52:25 2016 +0100
----------------------------------------------------------------------
src/site/asciidoc/extensions/index.adoc | 1 +
src/site/asciidoc/extensions/mod_etcd.adoc | 221 ++++++++++++++++++++++++
2 files changed, 222 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/846842cb/src/site/asciidoc/extensions/index.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/extensions/index.adoc b/src/site/asciidoc/extensions/index.adoc
index 87d8df7..9607d80 100644
--- a/src/site/asciidoc/extensions/index.adoc
+++ b/src/site/asciidoc/extensions/index.adoc
@@ -84,6 +84,7 @@ from a sledgehammer to a scalpell:
|+org.apache.tamaya.ext:tamaya-camel+ | Integration for Apache Camel. | link:mod_camel.html[Documentation]
|+org.apache.tamaya.ext:tamaya-spring+ | Integration for Spring / Spring Boot. | link:mod_spring.html[Documentation]
|+org.apache.tamaya.ext:tamaya-osgi+ | Integration for OSGI containers. | link:mod_osgi.html[Documentation]
+|+org.apache.tamaya.ext:tamaya-etcd+ | Integration with etcd clusters. | link:mod_etcd.html[Documentation]
|=======
http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/846842cb/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
new file mode 100644
index 0000000..22247fd
--- /dev/null
+++ b/src/site/asciidoc/extensions/mod_etcd.adoc
@@ -0,0 +1,221 @@
+= Apache Tamaya -- Extension: Integration with etcd (Core OS)
+
+:name: Tamaya
+:rootpackage: org.apache.tamaya.integration.etcd
+:title: Apache Tamaya Extension: Integration with etcd service
+:revdate: January 2016
+:authorinitials: ATR
+:author: Anatole Tresch
+:email: <an...@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!:
+<<<
+[[Optional]]
+== Integration with etcd (Extension Module)
+=== Overview
+
+The Tamaya etcd integration module provides different artifacts which allows integration of Apachae Tamaya
+configuration with etcd. Basically the module supports read-only integration.
+
+NOTE: The etcd backend itself also has methods that allow writing to the etcd cluster back. Once Tamaya's writable
+ feature will be ready for broader usage (currently it is in the sandbox).
+
+
+=== 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-etcd</artifactId>
+ <version>{tamayaVersion}</version>
+</dependency>
+-----------------------------------------------
+
+
+=== The Extensions Provided
+
+ETcd integration comes basically with 2 artifacts:
+
+* The +org.apache.tamaya.etcd.EtcdAccessor+ can be configured with a an url targeting an etcd server's REST endpoint root.
+ (+org.apache.tamaya.etcd.EtcdAccessor+). The accessor basically provides a simple Java API for communicating
+ with etcd server. The accessor hereby allows reading of single properties, or whole subtrees. Also the basic non
+ 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.
+
+=== The EtcdAccessor
+
+The accessor mentioned implements the basic read and write API for communicating with an etcd configuration cluster.
+Hereby the accessor also provides etcd specific data such as +createdIndex, modifiedIndex, ttl+ in the +Map+
+returned. Hereby the concept of etcd is used where keys starting with an '_' will be hidden from the overall
+properties map, being only directly/explicitly accessible:
+
+[source, java]
+-----------------------------------------------
+public class EtcdAccessor {
+
+ /**
+ * Creates a new instance with the basic access url.
+ * @param server server url, e.g. {@code http://127.0.0.1:4001}.
+ * @throws MalformedURLException
+ */
+ public EtcdAccessor(String server) throws MalformedURLException;
+
+ /**
+ * Get the etcd server version.
+ * @return the etcd server version, never null.
+ */
+ public String getVersion();
+
+ /**
+ * Ask etcd for s aingle key, value pair. Hereby the response returned from etcd:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.ttl=300 // optional
+ * _key.expiration=... // optional
+ * </pre>
+ * @param key the requested key
+ * @return the mapped result, including meta-entries.
+ */
+ public Map<String,String> get(String key);
+
+ /**
+ * Creates/updates an entry in etcd without any ttl set.
+ * The response is as follows:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * </pre>
+ * @param key the property key, not null
+ * @param value the value to be set
+ * @return the result map as described above.
+ */
+ public Map<String,String> set(String key, String value);
+
+ /**
+ * Creates/updates an entry in etcd. The response is as follows:
+ * <pre>
+ * key=value
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34 // optional
+ * _key.ttl=300 // optional
+ * _key.expiry=... // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * _key.prevNode.ttl=300 // optional
+ * _key.prevNode.expiration=... // optional
+ * </pre>
+ * @param key the property key, not null
+ * @param value the value to be set
+ * @param ttlSeconds the ttl in seconds (optional)
+ * @return the result map as described above.
+ */
+ public Map<String,String> set(String key, String value, Integer ttlSeconds);
+
+
+ /**
+ * Deletes a given key. The response is as follows:
+ * <pre>
+ * _key.source=[etcd]http://127.0.0.1:4001
+ * _key.createdIndex=12
+ * _key.modifiedIndex=34
+ * _key.ttl=300 // optional
+ * _key.expiry=... // optional
+ * _key.prevNode.createdIndex=12 // optional
+ * _key.prevNode.modifiedIndex=34 // optional
+ * _key.prevNode.ttl=300 // optional
+ * _key.prevNode.expiration=... // optional
+ * _key.prevNode.value=... // optional
+ * </pre>
+ * @param key the key to be deleted.
+ * @return the response mpas as described above.
+ */
+ public Map<String,String> delete(String key);
+
+
+ /**
+ * Access regular Tamaya properties map as follows:
+ * <pre>
+ * key1=myvalue
+ * _key1.source=[etcd]http://127.0.0.1:4001
+ * _key1.createdIndex=12
+ * _key1.modifiedIndex=34 // optional
+ * _key1.ttl=300 // optional
+ * _key1.expiration=... // optional
+ *
+ * key2=myvaluexxx
+ * _key2.source=[etcd]http://127.0.0.1:4001
+ * _key2.createdIndex=12
+ *
+ * key3=val3
+ * _key3.source=[etcd]http://127.0.0.1:4001
+ * _key3.createdIndex=12
+ * _key3.modifiedIndex=2
+ * </pre>
+ */
+ public Map<String,String> getProperties(String directory, boolean recursive);
+
+}
+-----------------------------------------------
+
+
+=== The EtcdPropertySource
+
+The +EtcdPropertySource+ is automatically registered and requires the etcd servers to be used to be configured. This
+enables to use e.g. in Docker environments the docker environment configuration mechanisms to configure Tamaya running
+in microservice containers to connect with the according etcd container cluster:
+
+* The property source reads the +tamaya.etcd.server.urls+ system property to evaluate possible etcd servers
+ (comma separated), which can be connected to. On error the API just performs a Round-Robin through the list of
+ configured servers. Without any configuration +http://127.0.0.1:4001+ is used. If no connection to any etcd
+ server can be established a warning will be logged, but deployment will not fail.
+* Additinoally also the
+ accessor allows to configure the socket/connection timeouts by setting +tamaya.etcd.timeout+ in seconds either as
+ system or environment property.
+* The +EtcdPropertySource+ finally also allows the values read from the etcd cluster to be mapped to prefixed
+ context. This can be activated by setting the +-Dtamaya.etcd.prefix=<PREFIX>+ system property. E.g. when the prefix is
+ set to +cluster-config.+ a etcd key of +host:known/all+ is mapped to +cluster-config.host:known/all+.
\ No newline at end of file