Reorganized doc module for easier documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/8b2ba1f6 Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/8b2ba1f6 Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/8b2ba1f6 Branch: refs/heads/master Commit: 8b2ba1f697ea9771198f9cd80d15545ee0d73837 Parents: 3d780be Author: anatole <anat...@apache.org> Authored: Mon Jan 12 23:31:28 2015 +0100 Committer: anatole <anat...@apache.org> Committed: Mon Jan 12 23:31:28 2015 +0100 ---------------------------------------------------------------------- docs/examples/examples.adoc | 76 ++++ docs/images/Thumbs.db | Bin 0 -> 308224 bytes docs/images/highlighter.png | Bin 0 -> 128142 bytes docs/images/icons/README | 5 + docs/images/icons/callouts/1.png | Bin 0 -> 329 bytes docs/images/icons/callouts/10.png | Bin 0 -> 361 bytes docs/images/icons/callouts/11.png | Bin 0 -> 565 bytes docs/images/icons/callouts/12.png | Bin 0 -> 617 bytes docs/images/icons/callouts/13.png | Bin 0 -> 623 bytes docs/images/icons/callouts/14.png | Bin 0 -> 411 bytes docs/images/icons/callouts/15.png | Bin 0 -> 640 bytes docs/images/icons/callouts/2.png | Bin 0 -> 353 bytes docs/images/icons/callouts/3.png | Bin 0 -> 350 bytes docs/images/icons/callouts/4.png | Bin 0 -> 345 bytes docs/images/icons/callouts/5.png | Bin 0 -> 348 bytes docs/images/icons/callouts/6.png | Bin 0 -> 355 bytes docs/images/icons/callouts/7.png | Bin 0 -> 344 bytes docs/images/icons/callouts/8.png | Bin 0 -> 357 bytes docs/images/icons/callouts/9.png | Bin 0 -> 357 bytes docs/images/icons/caution.png | Bin 0 -> 2734 bytes docs/images/icons/example.png | Bin 0 -> 2599 bytes docs/images/icons/home.png | Bin 0 -> 1340 bytes docs/images/icons/important.png | Bin 0 -> 2980 bytes docs/images/icons/next.png | Bin 0 -> 1302 bytes docs/images/icons/note.png | Bin 0 -> 2494 bytes docs/images/icons/prev.png | Bin 0 -> 1348 bytes docs/images/icons/tip.png | Bin 0 -> 2718 bytes docs/images/icons/up.png | Bin 0 -> 1320 bytes docs/images/icons/warning.png | Bin 0 -> 3214 bytes docs/images/smallnew.png | Bin 0 -> 292 bytes docs/images/test.png | Bin 0 -> 2494 bytes docs/misc/4_ImplementationCore.adoc | 47 +++ docs/misc/PossibleContributions.adoc | 388 +++++++++++++++++++ docs/src/images/Thumbs.db | Bin 308224 -> 0 bytes docs/src/images/highlighter.png | Bin 128142 -> 0 bytes docs/src/images/icons/README | 5 - docs/src/images/icons/callouts/1.png | Bin 329 -> 0 bytes docs/src/images/icons/callouts/10.png | Bin 361 -> 0 bytes docs/src/images/icons/callouts/11.png | Bin 565 -> 0 bytes docs/src/images/icons/callouts/12.png | Bin 617 -> 0 bytes docs/src/images/icons/callouts/13.png | Bin 623 -> 0 bytes docs/src/images/icons/callouts/14.png | Bin 411 -> 0 bytes docs/src/images/icons/callouts/15.png | Bin 640 -> 0 bytes docs/src/images/icons/callouts/2.png | Bin 353 -> 0 bytes docs/src/images/icons/callouts/3.png | Bin 350 -> 0 bytes docs/src/images/icons/callouts/4.png | Bin 345 -> 0 bytes docs/src/images/icons/callouts/5.png | Bin 348 -> 0 bytes docs/src/images/icons/callouts/6.png | Bin 355 -> 0 bytes docs/src/images/icons/callouts/7.png | Bin 344 -> 0 bytes docs/src/images/icons/callouts/8.png | Bin 357 -> 0 bytes docs/src/images/icons/callouts/9.png | Bin 357 -> 0 bytes docs/src/images/icons/caution.png | Bin 2734 -> 0 bytes docs/src/images/icons/example.png | Bin 2599 -> 0 bytes docs/src/images/icons/home.png | Bin 1340 -> 0 bytes docs/src/images/icons/important.png | Bin 2980 -> 0 bytes docs/src/images/icons/next.png | Bin 1302 -> 0 bytes docs/src/images/icons/note.png | Bin 2494 -> 0 bytes docs/src/images/icons/prev.png | Bin 1348 -> 0 bytes docs/src/images/icons/tip.png | Bin 2718 -> 0 bytes docs/src/images/icons/up.png | Bin 1320 -> 0 bytes docs/src/images/icons/warning.png | Bin 3214 -> 0 bytes docs/src/images/smallnew.png | Bin 292 -> 0 bytes docs/src/images/test.png | Bin 2494 -> 0 bytes .../main/asciidoc/PossibleContributions.adoc | 388 ------------------- .../asciidoc/design/4_ImplementationCore.adoc | 47 --- docs/src/main/asciidoc/example/example.adoc | 76 ---- 66 files changed, 516 insertions(+), 516 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/examples/examples.adoc ---------------------------------------------------------------------- diff --git a/docs/examples/examples.adoc b/docs/examples/examples.adoc new file mode 100644 index 0000000..55ed049 --- /dev/null +++ b/docs/examples/examples.adoc @@ -0,0 +1,76 @@ += Tamayas Asciidoctor Example Document +Oliver B. Fischer + +:encoding: UTF-8 +:source-highlighter: coderay + +This document is used to see if the current setup +of Asciidoctor within the Tamaya project is working +correctly. Therefore it contains some sections +with different examples of Asciidoctors capabilities. + +== Asciidoctor Environment + +Some facts on the current Asciidoctor environment. + +Asciidoctor version:: {asciidoctor-version} + + +== Plant UML + +This chapter contains a +http://plantuml.sourceforge.net/[Plant UML] diagram. + + +[plantuml, diagram-classes, png] +.... +class BlockProcessor +class DiagramBlock +class DitaaBlock +class PlantUmlBlock + +BlockProcessor <|-- DiagramBlock +DiagramBlock <|-- DitaaBlock +DiagramBlock <|-- PlantUmlBlock +.... + + +== Ditaa + +This section contains a diagram from +http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram website] +generated with http://ditaa.sourceforge.net/[ditaa]. + +[ditaa, "asciidoctor-diagram-process"] +.... + +-------------+ + | Asciidoctor |-------+ + | diagram | | + +-------------+ | PNG out + ^ | + | ditaa in | + | v + +--------+ +--------+----+ /---------------\ + | |---+ Asciidoctor +--->| | + | Text | +-------------+ | Beautiful | + |Document| | !magic! | | Output | + | {d}| | | | | + +---+----+ +-------------+ \---------------/ + : ^ + | Lots of work | + +-----------------------------------+ +.... + + + +== GraphViz + +This section contains a diagram +[graphviz] +.... +graph { + a -- b; b -- c; c -- d; d -- e; e -- f; a -- f; a -- c[color=red]; + a -- d; a -- e; b -- d; b -- e; b -- f; c -- e; c -- f; + d -- f; +} +.... http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/Thumbs.db ---------------------------------------------------------------------- diff --git a/docs/images/Thumbs.db b/docs/images/Thumbs.db new file mode 100644 index 0000000..ce5e659 Binary files /dev/null and b/docs/images/Thumbs.db differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/highlighter.png ---------------------------------------------------------------------- diff --git a/docs/images/highlighter.png b/docs/images/highlighter.png new file mode 100644 index 0000000..b311459 Binary files /dev/null and b/docs/images/highlighter.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/README ---------------------------------------------------------------------- diff --git a/docs/images/icons/README b/docs/images/icons/README new file mode 100644 index 0000000..f12b2a7 --- /dev/null +++ b/docs/images/icons/README @@ -0,0 +1,5 @@ +Replaced the plain DocBook XSL admonition icons with Jimmac's DocBook +icons (http://jimmac.musichall.cz/ikony.php3). I dropped transparency +from the Jimmac icons to get round MS IE and FOP PNG incompatibilies. + +Stuart Rackham http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/1.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/1.png b/docs/images/icons/callouts/1.png new file mode 100644 index 0000000..7d47343 Binary files /dev/null and b/docs/images/icons/callouts/1.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/10.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/10.png b/docs/images/icons/callouts/10.png new file mode 100644 index 0000000..997bbc8 Binary files /dev/null and b/docs/images/icons/callouts/10.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/11.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/11.png b/docs/images/icons/callouts/11.png new file mode 100644 index 0000000..ce47dac Binary files /dev/null and b/docs/images/icons/callouts/11.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/12.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/12.png b/docs/images/icons/callouts/12.png new file mode 100644 index 0000000..31daf4e Binary files /dev/null and b/docs/images/icons/callouts/12.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/13.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/13.png b/docs/images/icons/callouts/13.png new file mode 100644 index 0000000..14021a8 Binary files /dev/null and b/docs/images/icons/callouts/13.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/14.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/14.png b/docs/images/icons/callouts/14.png new file mode 100644 index 0000000..64014b7 Binary files /dev/null and b/docs/images/icons/callouts/14.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/15.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/15.png b/docs/images/icons/callouts/15.png new file mode 100644 index 0000000..0d65765 Binary files /dev/null and b/docs/images/icons/callouts/15.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/2.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/2.png b/docs/images/icons/callouts/2.png new file mode 100644 index 0000000..5d09341 Binary files /dev/null and b/docs/images/icons/callouts/2.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/3.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/3.png b/docs/images/icons/callouts/3.png new file mode 100644 index 0000000..ef7b700 Binary files /dev/null and b/docs/images/icons/callouts/3.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/4.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/4.png b/docs/images/icons/callouts/4.png new file mode 100644 index 0000000..adb8364 Binary files /dev/null and b/docs/images/icons/callouts/4.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/5.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/5.png b/docs/images/icons/callouts/5.png new file mode 100644 index 0000000..4d7eb46 Binary files /dev/null and b/docs/images/icons/callouts/5.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/6.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/6.png b/docs/images/icons/callouts/6.png new file mode 100644 index 0000000..0ba694a Binary files /dev/null and b/docs/images/icons/callouts/6.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/7.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/7.png b/docs/images/icons/callouts/7.png new file mode 100644 index 0000000..472e96f Binary files /dev/null and b/docs/images/icons/callouts/7.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/8.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/8.png b/docs/images/icons/callouts/8.png new file mode 100644 index 0000000..5e60973 Binary files /dev/null and b/docs/images/icons/callouts/8.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/callouts/9.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/callouts/9.png b/docs/images/icons/callouts/9.png new file mode 100644 index 0000000..a0676d2 Binary files /dev/null and b/docs/images/icons/callouts/9.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/caution.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/caution.png b/docs/images/icons/caution.png new file mode 100644 index 0000000..9a8c515 Binary files /dev/null and b/docs/images/icons/caution.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/example.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/example.png b/docs/images/icons/example.png new file mode 100644 index 0000000..1199e86 Binary files /dev/null and b/docs/images/icons/example.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/home.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/home.png b/docs/images/icons/home.png new file mode 100644 index 0000000..37a5231 Binary files /dev/null and b/docs/images/icons/home.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/important.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/important.png b/docs/images/icons/important.png new file mode 100644 index 0000000..be685cc Binary files /dev/null and b/docs/images/icons/important.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/next.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/next.png b/docs/images/icons/next.png new file mode 100644 index 0000000..64e126b Binary files /dev/null and b/docs/images/icons/next.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/note.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/note.png b/docs/images/icons/note.png new file mode 100644 index 0000000..7c1f3e2 Binary files /dev/null and b/docs/images/icons/note.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/prev.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/prev.png b/docs/images/icons/prev.png new file mode 100644 index 0000000..3e8f12f Binary files /dev/null and b/docs/images/icons/prev.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/tip.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/tip.png b/docs/images/icons/tip.png new file mode 100644 index 0000000..f087c73 Binary files /dev/null and b/docs/images/icons/tip.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/up.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/up.png b/docs/images/icons/up.png new file mode 100644 index 0000000..2db1ce6 Binary files /dev/null and b/docs/images/icons/up.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/icons/warning.png ---------------------------------------------------------------------- diff --git a/docs/images/icons/warning.png b/docs/images/icons/warning.png new file mode 100644 index 0000000..d41edb9 Binary files /dev/null and b/docs/images/icons/warning.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/smallnew.png ---------------------------------------------------------------------- diff --git a/docs/images/smallnew.png b/docs/images/smallnew.png new file mode 100644 index 0000000..411c2e1 Binary files /dev/null and b/docs/images/smallnew.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/images/test.png ---------------------------------------------------------------------- diff --git a/docs/images/test.png b/docs/images/test.png new file mode 100644 index 0000000..7c1f3e2 Binary files /dev/null and b/docs/images/test.png differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/misc/4_ImplementationCore.adoc ---------------------------------------------------------------------- diff --git a/docs/misc/4_ImplementationCore.adoc b/docs/misc/4_ImplementationCore.adoc new file mode 100644 index 0000000..2233002 --- /dev/null +++ b/docs/misc/4_ImplementationCore.adoc @@ -0,0 +1,47 @@ +// 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. +<<< +[[CoreConcepts]] +== {name} Core Implementation Concepts +Tamaya comes with an implementation module that implements the Tamaya API. The API itself does only provide the API for configuration usage. +Especially it does not define how the current runtime +Environment+ is mapped to a +Configuration+. This the gaop that should be solved +by the core library. + +The high level packages give you a good overview of the functionality provided: + +* +org.apache.tamaya.core+ is the root package of the Tamaya core implementation. +* +org.apache.tamaya.core.config+ provides + + + +The SPI contains the following core concepts/artifacts: + +* _Bootstrap_ is the delegate singleton that is used by the framework to resolve components. The effective component + loading can be accessed by implementing and registering an instance of +ServiceProvider+ using +java.util.ServiceLoader+. +* All the singleton used explicitly (+PropertyAdapters,PropertyProviders+ are backed up corresponding API interfaces. + To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded + by the current +Bootstrap+ setup (by default ServiceLoader based). +* Also the singleton used implicitly by +Configuration, Environment, Stage+ are backed up corresponding SPI interfaces. + To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded + by the current +Bootstrap+ setup (by default ServiceLoader based). + +This is also reflected in the main parts of the API, which is quite small: + +* +org.apache.tamaya+ contains the main abstractions +Configuration, ConfigOperator, ConfigQuery, PropertyAdapter, Stage, + Environment, PropertyProvider, MetaInfo+ +* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +Bootstrap+ mechanism. ++ +org.apache.tamaya.annot+ contains the annotations defined. http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/misc/PossibleContributions.adoc ---------------------------------------------------------------------- diff --git a/docs/misc/PossibleContributions.adoc b/docs/misc/PossibleContributions.adoc new file mode 100644 index 0000000..a0040d6 --- /dev/null +++ b/docs/misc/PossibleContributions.adoc @@ -0,0 +1,388 @@ +Apache Tamaya - Possible Tasks +============================== +:name: Tamaya +:rootpackage: org.apache.tamaya +:title: Apache Tamaya +:revnumber: 0.1-SNAPSHOT +:revremark: Draft +:revdate: October 2014 +:longversion: {revnumber} ({revremark}) {revdate} +:authorinitials: ATR +:author: Anatole Tresch +:email: <atsti...@gmail.com> +:source-highlighter: coderay +:website: http://tamaya.apache.org/ +:iconsdir: {imagesdir}/icons +:toc: +:toc-placement: manual +:icons: +:encoding: UTF-8 +:numbered: + +''' + +<<< + +-> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[] + +toc::[] + +<<< +: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. +----------------------------------------------------------- + +:numbered: + +<<< + +== Introduction + +== What is Tamaya + +{name} is the Apache standard for flexible and powerful configuration. Objective is to provide flavors for +Java SE, ME as well as to ship with powerful features for Java EE and Cloud Solutions. All functions provided +is build on top of a small but very powerful, flexible and extendible API. This API is implemented by a core implementation, +which then can be extended or adapted for use in different runtime scenarios, such as SE, ME, EE, Spring, OSGI +and more. Similarly additional modules may be provided that help also existing solution to be plugged into +{name}, so you can start right away using {name} without having to rebuild/change your existing application. + +== Main Features of {name} + +The main features of {name} currently are + +* *A simple key/value store*, named +PropertyProvider+ (simply called "provider"). +* Simple *built-in meta-data model*, that allows to easily attach metadata to a provider or single property keys. +* Support for *different configuration formats*. +* Support for *different configuration locations*, including remote locations. +* Powerful and flexible *options to combine providers to new composite providers* using different combination policies. +* The *Configuration model* adds additional features: +** *Type Adapters* allow to convert configuration into any required target type. +** *Built-in support* for all basic Java types. +* *Contextual, hierarchical and multi-layered environment model*. The model is rather simple, but nevertheless + powerful enough to map complex layered runtime environments such as Java EE or multi-tenant SaaS solutions. +* *Configurable System Properties* allow to tweak system properties to behave contextually. +* *Templates* provide a type safe configuration mechanism where an annotated interface is implemented by the + configuration system, providing data from an underlying configuration. +* *Configuration Injection* allows configured values to be directly injected into the bean's configured. +* *Loading Policies* allow to control how configuration changes are reflected on the configured beans. +* *Configuration Operators and Queries* can be used to easily implement advanced features such as *Views, + Security Constraints and Filters*. +* Provider and configuration changes can be observed by registering *PropertyChangeListeners*. +* Configurations are *versioned*, so remote pull scenarios can be implemented very efficiently. +* The system supports *multiple configurations* identified by name. +* The configuration system provides a powerful management console for reading and updating of configuration. +* The system also supports distributed configuration scenarios by leveraging existing solutions, such as Memcached, + Hazelcast or Zookeper. +* The system is built on "Java 8 features*. +* A *Java 7 Backport* is provided. + +=== Purpose of this Document + +The document should help to organize people and ideas around the Apache Tamaya Library. It list possible features, +ideas and tasks that need to be done. Everybody can have a look at and see, where hos contribution and capabilities +would fit best. + +== Basics + +=== Styles, Logo + +The project requires + +* a good Apache styled logo and +* CSS styles as needed, +* an initial web page, +* a twitter account +* ... + +=== Infrastructure + +We should setup all needed infrastructure +* code repos +* project modules (including module sites) +* coding and documentation guidelines +* automatic builds (CI), included automatic coverage and sonar quality checks. +* a docker image or appliance, with everything setup, so contributors can easily + start contributing... +* ... + +== Main Features + +=== Metadata Model + +Currently +MetaInfo+ models metadata as a separate constuct. It has been shown that this leads to more complex +handling when creating composites and makes the API overall more complex. The idea is to model metadata as simple +key/value pairs, that are part of the provider/configuration data as well, but handled separately. Metadata hereby +is identified by a starting '_' character in its key. For example refer to the following configuration properties: + +[source,listing] +.Basic Properties +---------------------------------------------------------------- +a.b.Foo=foo +a.b.Bar=bar +a.AnyOther=whatelse +Something=none +---------------------------------------------------------------- + +Now we can model meta-data as follows: + +[source,listing] +.Metadata Properties +---------------------------------------------------------------- +[a.b].info=An area info +[a.b.Foo].auth=role1,role2 +[a.b.Foo].encrypt=PGP +[a.b.Foo].sensitive=true +[].info=This is a test configuration example. +---------------------------------------------------------------- + +The above would model the following: + +* The area +a.b+ has the meta property +info+. +* The entry +a.b.Foo+ has three meta properties +auth,encrypt+ and +sensitive+. These could be interpreted by a security + view and used to encrypt the values returned by the configuration instance, if not the current user has one of the + specified roles. +* The last meta data defines an attribute +info+ for the whole provider/configuration (the root area). + +Given that the overall entries would be as follows: + +[source,listing] +.Full Properties with Meta Properties +---------------------------------------------------------------- +[a.b].info=An area info +a.b.Foo=foo +[a.b.Foo].auth=role1,role2 +[a.b.Foo].encrypt=PGP +[a.b.Foo].sensitive=true +a.b.Bar=bar +[].info=This is a test configuration example. +a.AnyOther=whatelse +Something=none +---------------------------------------------------------------- + +The current +MetaInfo+ class could be adapted, so it is reading data from the underlying configuration/provider, +instead of its own datastructure. This would make a later mapping of configuration and its metadata into DB table, JSON +etc, much more easier. +The providers on the other side may suppress any metadata from ordinary output, such +as +toString()+, Similarly accessing metadata using the official config API (+get, getOrDefault, getAreas+ etc) +should be disabled. The +MetaInfoBuilder+ must probably as well adapted or redesigned. + +=== Collection Support + +Add a key/value based model for mapping collections such as sets, maps, list. Implement according adapters. +In combination with the metadata model above this could be something like: + +[source,listing] +.Collection Support +---------------------------------------------------------------- +mySet=[a,b,c,d,e\,e,f] +[mySet].type=set +#optional define the implementation class +[mySet].class=java.util.TreeSet + +myList=[a,b,c,d,e\,e,f] +[myList].type=list +#optional define the implementation class +[myList].class=java.util.ArrayList + +myMap=[a:aa,b:bb,c:cc,d:dd,e:e\,e,f:ff] +[myMap].type=map +#optional define the implementation class +[myMap].class=java.util.TreeMap + +#Finally we could also add support for non String based types +myTypedSet=[1,2,3,4.5,6,7.10.123] +[myTypedSet].contentClass=java.lang.Double +myTypedList=[CHF 10.20, EUR 12.20, BTC 0.002] +[myTypedList].contentType=org.javamoney.moneta.FastMoney +myTypedMap=[CHF:CHF 10.20, EUR:EUR 12.20, BTC:BTC 0.002] +[myTypedMap].contentTypes=javax.money.CurrencyUnit,javax.money.MonetaryAmount +---------------------------------------------------------------- + + +=== Management Service + +A JMX/Restful API should be designed and built that exposes configuration information. Access should be secured, e.g. +using OAuth or other security mechasnisms. + +=== Management Client + +A nice web-based client to manage configuration data would be nice as well. This also includes a UI for creating new +configurations. + +=== Mapping Configuration to a Database + +A flexible mechanism should be implemented that allows the use of databases (SQL/JPA as well as non-SQL) for +storing/retreiving/managing configuration: + +* JPA, Hibernate +* MongoDB +* ... + +=== Integration with OSGI + +Examples are to be created and tested, where OSGI is used as the basic runtime platform, e.g. Apache Felix, but as well +others. + +=== Integration with Jigsaw + +Once Jigsaw is mature and in a usable (still early) stage, examples are to be created and tested, where OSGI is used as +the basic runtime platform, e.g. Apache Felix, but as well others. + +== Distributed/Remote Configuration Support + +=== Configuration Server + +A configuration server should be implemented that provides access to configurations and triggers updates to registered +clients (push). Similarly a poull model should be supported, where clients can asl for the current version id of a certain +configuration and reload it if necessary. + +=== Configuration Distribution Policies + +Different configuration distribution policies should be defined any implemented, e.g. distributed cache, restful services, +web services, EJB/RMI calls, asynchronous queues, publish/subsribe models, ... + +=== Dynamic Service Lookup + +Configuration Servers and Clients should bea ble to locate each other in different ways: + +* with fixed configured IPs, or IP ranges +* using a dynamic service location protocol like +** SLP +** Distributed Maps/Datagrids +** Apache Zookeeper + +=== Configuration Client + +A subset of the API would be created that exposes only a well defined subset, of exactly one configuration targeted +to a certain instance, VM or whatever. The client should be connectable to a server in different ways (see configuration +distributiont policies). + +=== Preferences Support + +Write a +PreferencesFactory+ for +java.util.preferences+. + +== Third Party Integration + +=== Integration with Deltaspike Config + +Integration with Deltaspike Config should be implemented and discussed with Deltaspike guys. + +=== Integration with Spring + +A {name} module should be created that allows Spring to be used either as client or configuration provider. + +=== Integration with Jetty + +A {name} module should be created that allows a Jetty instance to be deployed and started that is (completely) +configured based on configuration server. + +=== Integration with Tomcat + +A {name} module should be created that allows a Tomcat instance to be deployed and started that is (completely) +configured based on configuration server. + +=== Configuration of Java EE + +In the Java EE area there would be several options: + +=== Configuration of Application Servers (administrative resources) + +It should be possible to start a application server instance remotely and configure all administrative resources and the +deployments based on the configuration service, server to be considered maybe + +* Wildfly +* IBM +* Weblogic +* Glassfish +* Apache Geronimo + +==== Configuration of CDI + +Implement a CDI extension that controls CDI based on configuration: +* Add beans +* Remove (veto) beans +* Add/remove interceptors +* Add/remove decorators +* Activate alternatives +* ... + +==== Configuration of Bean Validation + +* Add configurable validators. +* Configure bean validation based on configuration +* ... + +=== JNDI Support + +Write a +JCA+ adapter to provide configuration data through JNDI. + +==== Configure JSF + +Use the JSF +XML Document+ event to completely configure JSF. + +==== Configure Web Services + +Provide a WebServiceProviderFactory that may be configured. + +==== Configure JPA + +Provide an implementation that allows configuration of persistence units. Talk with JPA EG people to see if we can +get an SPI to hook in a stadardized way. + +==== Configure EJBs + +Provide an implementation that allows configuration of EJBs and MDBs: + +* Register beans +* Unregister/disable beans +* Intercept beans +* Support Configuration Injection (in the worst case using a standard Interceptor, provide supporting artifacts to + help developers to achive this easily). +* Talk with EE8 Umbrella EG (Bill Shanon, Linda DeMichels) on a feasible SPI for EE8, if possible join the EG. + +==== Configure ... + +Just think of any Java EE aspects that might be worth to be configured. If it can be done, e.g. by managing CDI managed +resources, it might be easy. For others it is a good idea to discuss things with our matter of experts... + +== Special Goodies + +=== Maintenance Mode Servlet Filter + +Provide a servlet filter that is capable of switching to maintenance mode, based on configuration. Similarly also a forwarding +servlet could be useful, wehere only request based on configuration are forwarded, other might be rejected or dropped +as configured. + +=== Dynamic Camel Routes + +Provides dynamic (configurable) Camel routes, e.g. usable within ServiceMix or standalone. + +=== Dynamic CXF + +Provides dynamic (configurable) CXF adapters, e.g. usable within ServiceMix or standalone. + +=== Configurable Apache MQ + +Provides an implementation for configuring Apache MQ. + +=== Dynamic ... + +Interested to see what other ideas are around. Let us know! + http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/Thumbs.db ---------------------------------------------------------------------- diff --git a/docs/src/images/Thumbs.db b/docs/src/images/Thumbs.db deleted file mode 100644 index ce5e659..0000000 Binary files a/docs/src/images/Thumbs.db and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/highlighter.png ---------------------------------------------------------------------- diff --git a/docs/src/images/highlighter.png b/docs/src/images/highlighter.png deleted file mode 100644 index b311459..0000000 Binary files a/docs/src/images/highlighter.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/README ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/README b/docs/src/images/icons/README deleted file mode 100644 index f12b2a7..0000000 --- a/docs/src/images/icons/README +++ /dev/null @@ -1,5 +0,0 @@ -Replaced the plain DocBook XSL admonition icons with Jimmac's DocBook -icons (http://jimmac.musichall.cz/ikony.php3). I dropped transparency -from the Jimmac icons to get round MS IE and FOP PNG incompatibilies. - -Stuart Rackham http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/1.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/1.png b/docs/src/images/icons/callouts/1.png deleted file mode 100644 index 7d47343..0000000 Binary files a/docs/src/images/icons/callouts/1.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/10.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/10.png b/docs/src/images/icons/callouts/10.png deleted file mode 100644 index 997bbc8..0000000 Binary files a/docs/src/images/icons/callouts/10.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/11.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/11.png b/docs/src/images/icons/callouts/11.png deleted file mode 100644 index ce47dac..0000000 Binary files a/docs/src/images/icons/callouts/11.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/12.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/12.png b/docs/src/images/icons/callouts/12.png deleted file mode 100644 index 31daf4e..0000000 Binary files a/docs/src/images/icons/callouts/12.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/13.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/13.png b/docs/src/images/icons/callouts/13.png deleted file mode 100644 index 14021a8..0000000 Binary files a/docs/src/images/icons/callouts/13.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/14.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/14.png b/docs/src/images/icons/callouts/14.png deleted file mode 100644 index 64014b7..0000000 Binary files a/docs/src/images/icons/callouts/14.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/15.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/15.png b/docs/src/images/icons/callouts/15.png deleted file mode 100644 index 0d65765..0000000 Binary files a/docs/src/images/icons/callouts/15.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/2.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/2.png b/docs/src/images/icons/callouts/2.png deleted file mode 100644 index 5d09341..0000000 Binary files a/docs/src/images/icons/callouts/2.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/3.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/3.png b/docs/src/images/icons/callouts/3.png deleted file mode 100644 index ef7b700..0000000 Binary files a/docs/src/images/icons/callouts/3.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/4.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/4.png b/docs/src/images/icons/callouts/4.png deleted file mode 100644 index adb8364..0000000 Binary files a/docs/src/images/icons/callouts/4.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/5.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/5.png b/docs/src/images/icons/callouts/5.png deleted file mode 100644 index 4d7eb46..0000000 Binary files a/docs/src/images/icons/callouts/5.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/6.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/6.png b/docs/src/images/icons/callouts/6.png deleted file mode 100644 index 0ba694a..0000000 Binary files a/docs/src/images/icons/callouts/6.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/7.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/7.png b/docs/src/images/icons/callouts/7.png deleted file mode 100644 index 472e96f..0000000 Binary files a/docs/src/images/icons/callouts/7.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/8.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/8.png b/docs/src/images/icons/callouts/8.png deleted file mode 100644 index 5e60973..0000000 Binary files a/docs/src/images/icons/callouts/8.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/callouts/9.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/callouts/9.png b/docs/src/images/icons/callouts/9.png deleted file mode 100644 index a0676d2..0000000 Binary files a/docs/src/images/icons/callouts/9.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/caution.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/caution.png b/docs/src/images/icons/caution.png deleted file mode 100644 index 9a8c515..0000000 Binary files a/docs/src/images/icons/caution.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/example.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/example.png b/docs/src/images/icons/example.png deleted file mode 100644 index 1199e86..0000000 Binary files a/docs/src/images/icons/example.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/home.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/home.png b/docs/src/images/icons/home.png deleted file mode 100644 index 37a5231..0000000 Binary files a/docs/src/images/icons/home.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/important.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/important.png b/docs/src/images/icons/important.png deleted file mode 100644 index be685cc..0000000 Binary files a/docs/src/images/icons/important.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/next.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/next.png b/docs/src/images/icons/next.png deleted file mode 100644 index 64e126b..0000000 Binary files a/docs/src/images/icons/next.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/note.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/note.png b/docs/src/images/icons/note.png deleted file mode 100644 index 7c1f3e2..0000000 Binary files a/docs/src/images/icons/note.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/prev.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/prev.png b/docs/src/images/icons/prev.png deleted file mode 100644 index 3e8f12f..0000000 Binary files a/docs/src/images/icons/prev.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/tip.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/tip.png b/docs/src/images/icons/tip.png deleted file mode 100644 index f087c73..0000000 Binary files a/docs/src/images/icons/tip.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/up.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/up.png b/docs/src/images/icons/up.png deleted file mode 100644 index 2db1ce6..0000000 Binary files a/docs/src/images/icons/up.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/icons/warning.png ---------------------------------------------------------------------- diff --git a/docs/src/images/icons/warning.png b/docs/src/images/icons/warning.png deleted file mode 100644 index d41edb9..0000000 Binary files a/docs/src/images/icons/warning.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/smallnew.png ---------------------------------------------------------------------- diff --git a/docs/src/images/smallnew.png b/docs/src/images/smallnew.png deleted file mode 100644 index 411c2e1..0000000 Binary files a/docs/src/images/smallnew.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/images/test.png ---------------------------------------------------------------------- diff --git a/docs/src/images/test.png b/docs/src/images/test.png deleted file mode 100644 index 7c1f3e2..0000000 Binary files a/docs/src/images/test.png and /dev/null differ http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/main/asciidoc/PossibleContributions.adoc ---------------------------------------------------------------------- diff --git a/docs/src/main/asciidoc/PossibleContributions.adoc b/docs/src/main/asciidoc/PossibleContributions.adoc deleted file mode 100644 index a0040d6..0000000 --- a/docs/src/main/asciidoc/PossibleContributions.adoc +++ /dev/null @@ -1,388 +0,0 @@ -Apache Tamaya - Possible Tasks -============================== -:name: Tamaya -:rootpackage: org.apache.tamaya -:title: Apache Tamaya -:revnumber: 0.1-SNAPSHOT -:revremark: Draft -:revdate: October 2014 -:longversion: {revnumber} ({revremark}) {revdate} -:authorinitials: ATR -:author: Anatole Tresch -:email: <atsti...@gmail.com> -:source-highlighter: coderay -:website: http://tamaya.apache.org/ -:iconsdir: {imagesdir}/icons -:toc: -:toc-placement: manual -:icons: -:encoding: UTF-8 -:numbered: - -''' - -<<< - --> add image : : https://raw.githubusercontent.com/JavaConfig/config-api/master/src/main/asciidoc/images/javaconfig.jpg[] - -toc::[] - -<<< -: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. ------------------------------------------------------------ - -:numbered: - -<<< - -== Introduction - -== What is Tamaya - -{name} is the Apache standard for flexible and powerful configuration. Objective is to provide flavors for -Java SE, ME as well as to ship with powerful features for Java EE and Cloud Solutions. All functions provided -is build on top of a small but very powerful, flexible and extendible API. This API is implemented by a core implementation, -which then can be extended or adapted for use in different runtime scenarios, such as SE, ME, EE, Spring, OSGI -and more. Similarly additional modules may be provided that help also existing solution to be plugged into -{name}, so you can start right away using {name} without having to rebuild/change your existing application. - -== Main Features of {name} - -The main features of {name} currently are - -* *A simple key/value store*, named +PropertyProvider+ (simply called "provider"). -* Simple *built-in meta-data model*, that allows to easily attach metadata to a provider or single property keys. -* Support for *different configuration formats*. -* Support for *different configuration locations*, including remote locations. -* Powerful and flexible *options to combine providers to new composite providers* using different combination policies. -* The *Configuration model* adds additional features: -** *Type Adapters* allow to convert configuration into any required target type. -** *Built-in support* for all basic Java types. -* *Contextual, hierarchical and multi-layered environment model*. The model is rather simple, but nevertheless - powerful enough to map complex layered runtime environments such as Java EE or multi-tenant SaaS solutions. -* *Configurable System Properties* allow to tweak system properties to behave contextually. -* *Templates* provide a type safe configuration mechanism where an annotated interface is implemented by the - configuration system, providing data from an underlying configuration. -* *Configuration Injection* allows configured values to be directly injected into the bean's configured. -* *Loading Policies* allow to control how configuration changes are reflected on the configured beans. -* *Configuration Operators and Queries* can be used to easily implement advanced features such as *Views, - Security Constraints and Filters*. -* Provider and configuration changes can be observed by registering *PropertyChangeListeners*. -* Configurations are *versioned*, so remote pull scenarios can be implemented very efficiently. -* The system supports *multiple configurations* identified by name. -* The configuration system provides a powerful management console for reading and updating of configuration. -* The system also supports distributed configuration scenarios by leveraging existing solutions, such as Memcached, - Hazelcast or Zookeper. -* The system is built on "Java 8 features*. -* A *Java 7 Backport* is provided. - -=== Purpose of this Document - -The document should help to organize people and ideas around the Apache Tamaya Library. It list possible features, -ideas and tasks that need to be done. Everybody can have a look at and see, where hos contribution and capabilities -would fit best. - -== Basics - -=== Styles, Logo - -The project requires - -* a good Apache styled logo and -* CSS styles as needed, -* an initial web page, -* a twitter account -* ... - -=== Infrastructure - -We should setup all needed infrastructure -* code repos -* project modules (including module sites) -* coding and documentation guidelines -* automatic builds (CI), included automatic coverage and sonar quality checks. -* a docker image or appliance, with everything setup, so contributors can easily - start contributing... -* ... - -== Main Features - -=== Metadata Model - -Currently +MetaInfo+ models metadata as a separate constuct. It has been shown that this leads to more complex -handling when creating composites and makes the API overall more complex. The idea is to model metadata as simple -key/value pairs, that are part of the provider/configuration data as well, but handled separately. Metadata hereby -is identified by a starting '_' character in its key. For example refer to the following configuration properties: - -[source,listing] -.Basic Properties ----------------------------------------------------------------- -a.b.Foo=foo -a.b.Bar=bar -a.AnyOther=whatelse -Something=none ----------------------------------------------------------------- - -Now we can model meta-data as follows: - -[source,listing] -.Metadata Properties ----------------------------------------------------------------- -[a.b].info=An area info -[a.b.Foo].auth=role1,role2 -[a.b.Foo].encrypt=PGP -[a.b.Foo].sensitive=true -[].info=This is a test configuration example. ----------------------------------------------------------------- - -The above would model the following: - -* The area +a.b+ has the meta property +info+. -* The entry +a.b.Foo+ has three meta properties +auth,encrypt+ and +sensitive+. These could be interpreted by a security - view and used to encrypt the values returned by the configuration instance, if not the current user has one of the - specified roles. -* The last meta data defines an attribute +info+ for the whole provider/configuration (the root area). - -Given that the overall entries would be as follows: - -[source,listing] -.Full Properties with Meta Properties ----------------------------------------------------------------- -[a.b].info=An area info -a.b.Foo=foo -[a.b.Foo].auth=role1,role2 -[a.b.Foo].encrypt=PGP -[a.b.Foo].sensitive=true -a.b.Bar=bar -[].info=This is a test configuration example. -a.AnyOther=whatelse -Something=none ----------------------------------------------------------------- - -The current +MetaInfo+ class could be adapted, so it is reading data from the underlying configuration/provider, -instead of its own datastructure. This would make a later mapping of configuration and its metadata into DB table, JSON -etc, much more easier. -The providers on the other side may suppress any metadata from ordinary output, such -as +toString()+, Similarly accessing metadata using the official config API (+get, getOrDefault, getAreas+ etc) -should be disabled. The +MetaInfoBuilder+ must probably as well adapted or redesigned. - -=== Collection Support - -Add a key/value based model for mapping collections such as sets, maps, list. Implement according adapters. -In combination with the metadata model above this could be something like: - -[source,listing] -.Collection Support ----------------------------------------------------------------- -mySet=[a,b,c,d,e\,e,f] -[mySet].type=set -#optional define the implementation class -[mySet].class=java.util.TreeSet - -myList=[a,b,c,d,e\,e,f] -[myList].type=list -#optional define the implementation class -[myList].class=java.util.ArrayList - -myMap=[a:aa,b:bb,c:cc,d:dd,e:e\,e,f:ff] -[myMap].type=map -#optional define the implementation class -[myMap].class=java.util.TreeMap - -#Finally we could also add support for non String based types -myTypedSet=[1,2,3,4.5,6,7.10.123] -[myTypedSet].contentClass=java.lang.Double -myTypedList=[CHF 10.20, EUR 12.20, BTC 0.002] -[myTypedList].contentType=org.javamoney.moneta.FastMoney -myTypedMap=[CHF:CHF 10.20, EUR:EUR 12.20, BTC:BTC 0.002] -[myTypedMap].contentTypes=javax.money.CurrencyUnit,javax.money.MonetaryAmount ----------------------------------------------------------------- - - -=== Management Service - -A JMX/Restful API should be designed and built that exposes configuration information. Access should be secured, e.g. -using OAuth or other security mechasnisms. - -=== Management Client - -A nice web-based client to manage configuration data would be nice as well. This also includes a UI for creating new -configurations. - -=== Mapping Configuration to a Database - -A flexible mechanism should be implemented that allows the use of databases (SQL/JPA as well as non-SQL) for -storing/retreiving/managing configuration: - -* JPA, Hibernate -* MongoDB -* ... - -=== Integration with OSGI - -Examples are to be created and tested, where OSGI is used as the basic runtime platform, e.g. Apache Felix, but as well -others. - -=== Integration with Jigsaw - -Once Jigsaw is mature and in a usable (still early) stage, examples are to be created and tested, where OSGI is used as -the basic runtime platform, e.g. Apache Felix, but as well others. - -== Distributed/Remote Configuration Support - -=== Configuration Server - -A configuration server should be implemented that provides access to configurations and triggers updates to registered -clients (push). Similarly a poull model should be supported, where clients can asl for the current version id of a certain -configuration and reload it if necessary. - -=== Configuration Distribution Policies - -Different configuration distribution policies should be defined any implemented, e.g. distributed cache, restful services, -web services, EJB/RMI calls, asynchronous queues, publish/subsribe models, ... - -=== Dynamic Service Lookup - -Configuration Servers and Clients should bea ble to locate each other in different ways: - -* with fixed configured IPs, or IP ranges -* using a dynamic service location protocol like -** SLP -** Distributed Maps/Datagrids -** Apache Zookeeper - -=== Configuration Client - -A subset of the API would be created that exposes only a well defined subset, of exactly one configuration targeted -to a certain instance, VM or whatever. The client should be connectable to a server in different ways (see configuration -distributiont policies). - -=== Preferences Support - -Write a +PreferencesFactory+ for +java.util.preferences+. - -== Third Party Integration - -=== Integration with Deltaspike Config - -Integration with Deltaspike Config should be implemented and discussed with Deltaspike guys. - -=== Integration with Spring - -A {name} module should be created that allows Spring to be used either as client or configuration provider. - -=== Integration with Jetty - -A {name} module should be created that allows a Jetty instance to be deployed and started that is (completely) -configured based on configuration server. - -=== Integration with Tomcat - -A {name} module should be created that allows a Tomcat instance to be deployed and started that is (completely) -configured based on configuration server. - -=== Configuration of Java EE - -In the Java EE area there would be several options: - -=== Configuration of Application Servers (administrative resources) - -It should be possible to start a application server instance remotely and configure all administrative resources and the -deployments based on the configuration service, server to be considered maybe - -* Wildfly -* IBM -* Weblogic -* Glassfish -* Apache Geronimo - -==== Configuration of CDI - -Implement a CDI extension that controls CDI based on configuration: -* Add beans -* Remove (veto) beans -* Add/remove interceptors -* Add/remove decorators -* Activate alternatives -* ... - -==== Configuration of Bean Validation - -* Add configurable validators. -* Configure bean validation based on configuration -* ... - -=== JNDI Support - -Write a +JCA+ adapter to provide configuration data through JNDI. - -==== Configure JSF - -Use the JSF +XML Document+ event to completely configure JSF. - -==== Configure Web Services - -Provide a WebServiceProviderFactory that may be configured. - -==== Configure JPA - -Provide an implementation that allows configuration of persistence units. Talk with JPA EG people to see if we can -get an SPI to hook in a stadardized way. - -==== Configure EJBs - -Provide an implementation that allows configuration of EJBs and MDBs: - -* Register beans -* Unregister/disable beans -* Intercept beans -* Support Configuration Injection (in the worst case using a standard Interceptor, provide supporting artifacts to - help developers to achive this easily). -* Talk with EE8 Umbrella EG (Bill Shanon, Linda DeMichels) on a feasible SPI for EE8, if possible join the EG. - -==== Configure ... - -Just think of any Java EE aspects that might be worth to be configured. If it can be done, e.g. by managing CDI managed -resources, it might be easy. For others it is a good idea to discuss things with our matter of experts... - -== Special Goodies - -=== Maintenance Mode Servlet Filter - -Provide a servlet filter that is capable of switching to maintenance mode, based on configuration. Similarly also a forwarding -servlet could be useful, wehere only request based on configuration are forwarded, other might be rejected or dropped -as configured. - -=== Dynamic Camel Routes - -Provides dynamic (configurable) Camel routes, e.g. usable within ServiceMix or standalone. - -=== Dynamic CXF - -Provides dynamic (configurable) CXF adapters, e.g. usable within ServiceMix or standalone. - -=== Configurable Apache MQ - -Provides an implementation for configuring Apache MQ. - -=== Dynamic ... - -Interested to see what other ideas are around. Let us know! - http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/main/asciidoc/design/4_ImplementationCore.adoc ---------------------------------------------------------------------- diff --git a/docs/src/main/asciidoc/design/4_ImplementationCore.adoc b/docs/src/main/asciidoc/design/4_ImplementationCore.adoc deleted file mode 100644 index 2233002..0000000 --- a/docs/src/main/asciidoc/design/4_ImplementationCore.adoc +++ /dev/null @@ -1,47 +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. -<<< -[[CoreConcepts]] -== {name} Core Implementation Concepts -Tamaya comes with an implementation module that implements the Tamaya API. The API itself does only provide the API for configuration usage. -Especially it does not define how the current runtime +Environment+ is mapped to a +Configuration+. This the gaop that should be solved -by the core library. - -The high level packages give you a good overview of the functionality provided: - -* +org.apache.tamaya.core+ is the root package of the Tamaya core implementation. -* +org.apache.tamaya.core.config+ provides - - - -The SPI contains the following core concepts/artifacts: - -* _Bootstrap_ is the delegate singleton that is used by the framework to resolve components. The effective component - loading can be accessed by implementing and registering an instance of +ServiceProvider+ using +java.util.ServiceLoader+. -* All the singleton used explicitly (+PropertyAdapters,PropertyProviders+ are backed up corresponding API interfaces. - To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded - by the current +Bootstrap+ setup (by default ServiceLoader based). -* Also the singleton used implicitly by +Configuration, Environment, Stage+ are backed up corresponding SPI interfaces. - To override a singleton's behaviour the corresponding SPI has to be implemented and registered, so it can be loaded - by the current +Bootstrap+ setup (by default ServiceLoader based). - -This is also reflected in the main parts of the API, which is quite small: - -* +org.apache.tamaya+ contains the main abstractions +Configuration, ConfigOperator, ConfigQuery, PropertyAdapter, Stage, - Environment, PropertyProvider, MetaInfo+ -* +org.apache.tamaya.spi+ contains the SPI interfaces to be implemented by implementations and the +Bootstrap+ mechanism. -+ +org.apache.tamaya.annot+ contains the annotations defined. http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/8b2ba1f6/docs/src/main/asciidoc/example/example.adoc ---------------------------------------------------------------------- diff --git a/docs/src/main/asciidoc/example/example.adoc b/docs/src/main/asciidoc/example/example.adoc deleted file mode 100644 index 55ed049..0000000 --- a/docs/src/main/asciidoc/example/example.adoc +++ /dev/null @@ -1,76 +0,0 @@ -= Tamayas Asciidoctor Example Document -Oliver B. Fischer - -:encoding: UTF-8 -:source-highlighter: coderay - -This document is used to see if the current setup -of Asciidoctor within the Tamaya project is working -correctly. Therefore it contains some sections -with different examples of Asciidoctors capabilities. - -== Asciidoctor Environment - -Some facts on the current Asciidoctor environment. - -Asciidoctor version:: {asciidoctor-version} - - -== Plant UML - -This chapter contains a -http://plantuml.sourceforge.net/[Plant UML] diagram. - - -[plantuml, diagram-classes, png] -.... -class BlockProcessor -class DiagramBlock -class DitaaBlock -class PlantUmlBlock - -BlockProcessor <|-- DiagramBlock -DiagramBlock <|-- DitaaBlock -DiagramBlock <|-- PlantUmlBlock -.... - - -== Ditaa - -This section contains a diagram from -http://asciidoctor.org/docs/asciidoctor-diagram/[Asciidoctor Diagram website] -generated with http://ditaa.sourceforge.net/[ditaa]. - -[ditaa, "asciidoctor-diagram-process"] -.... - +-------------+ - | Asciidoctor |-------+ - | diagram | | - +-------------+ | PNG out - ^ | - | ditaa in | - | v - +--------+ +--------+----+ /---------------\ - | |---+ Asciidoctor +--->| | - | Text | +-------------+ | Beautiful | - |Document| | !magic! | | Output | - | {d}| | | | | - +---+----+ +-------------+ \---------------/ - : ^ - | Lots of work | - +-----------------------------------+ -.... - - - -== GraphViz - -This section contains a diagram -[graphviz] -.... -graph { - a -- b; b -- c; c -- d; d -- e; e -- f; a -- f; a -- c[color=red]; - a -- d; a -- e; b -- d; b -- e; b -- f; c -- e; c -- f; - d -- f; -} -....
