svn commit: r1644787 - /incubator/tamaya/site/trunk/content/modules.mdtext

[an...@apache.org]

Author: anatole
Date: Thu Dec 11 23:14:57 2014
New Revision: 1644787

URL: http://svn.apache.org/r1644787
Log:
Added modules doc.

Modified:
    incubator/tamaya/site/trunk/content/modules.mdtext

Modified: incubator/tamaya/site/trunk/content/modules.mdtext
URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/modules.mdtext?rev=1644787&r1=1644786&r2=1644787&view=diff
==============================================================================
--- incubator/tamaya/site/trunk/content/modules.mdtext (original)
+++ incubator/tamaya/site/trunk/content/modules.mdtext Thu Dec 11 23:14:57 2014
@@ -1,4 +1,4 @@
-Title: Documentation
+Title: Modules
 Notice:    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
@@ -21,43 +21,103 @@ Notice:    Licensed to the Apache Softwa
 
 ***
 
-# Sources
+# Overview
 
-[Tamaya Documentation](/documentation/) is available with [Tamaya Source](documentation/source.html).
+Tamaya has a modular design comprising the following parts:
 
-# Format
+* The **API** contains a complete API and **SPI** with interfaces for *Configuration, Environment, PropertyProvider*
+  and the frameworks **Bootstrap** mechanism.
+* The **Core** contains a minimal implementation of the API that contains everything but
+  the effective meta-model.
+* The **Modules** contains extensions and adapters to 
+  * integrate Tamaya with other frameworks such as Apache Commons Configuration, Spring and Java EE, CDI.
+  * additional helper modules that support developers assembling complex meta-models from simpler providers.
+  * different preconfigured environment models.
+  * different rebuilt configuration meta-models.
+* The **Documentation** module contains several documentations in _asciidoc_ .
 
-The format used for Tamaya documentation is [ASCIIDOC](http://www.methods.co.nz/asciidoc/) because it's easily exportable to PDF, HTML, and it's also easy to contribute. It can be used to export also to epub and also be used to write books
+# API
 
-# Rendering documentation as HTML
+The **API** contains a complete SE API with interfaces for *Configuration, Environment, PropertyProvider*.
+This interfaces also offer access to related instances, e.g.
 
-_Requirenment:_ Have [Maven](http://maven.apache.org/) installed.
+    Configuration config = Configuration.current();
+    Environment env = Environment.current();
 
-If you cloned the source repository and want to render the documentation as HTML, you just need to run the following command:
+Most users in a SE context will typically only work with _Configuration_, since it offers all functionality
+available regarding configuration. Additionally the API allows to inject configuration
+by adding annotations:
 
-    $ cd REPO_ROOT/documentation
-    $ mvn site
+    String myKey = Configuration.current().get("myKey").orElse("myDefaultValue");
+    int myLimit = Configuration.current().getInt("all.size.limit").getAsInt();
 
-The generate documentation will be available at `REPO_ROOT/documentation/target/site`
+# Core
 
-# Contribute
+The Core module implements the API based on Java SE and provides additional features as useful.
+The Core part hereby does _not have any external dependencies_. So it can be directly
+accessed and consumed as artifact:
 
-If you would like to submit a documentation patch through Jira, you can have a look at the [suggested approach](suggested-git-workflows.html).
+Put the following information in your ~/.m2/settings.xml file
 
-# Publish procedure (for committers only)
+    <dependency>
+      <artifactId>org.apache.tamaya</id>
+      <artifactId>tamaya-core</artifactId>
+      <version><CURRENT_VERSION></version>
+    </dependency>
 
-If you're a committer and want to publish the documentation at [Tamaya Site](http://tamaya.incubator.apache.org/documentation/) you have do the following steps:
+The core modules out of the box supports _.properties, .xml-properties and .ini files
+as valid input formats. It is capable of reading configuration resources from
 
-Put the following information in your ~/.m2/settings.xml file
+* the classpath
+* the file system
+* any resource addressable by an URL
+
+Additionally the core part provides a _Environment_ implementation that maps CLI arguments,
+system and environment properties into a _root_ Environment.
+
+# Modules
+## Meta-Models
+### Minimal SE Meta-Model
+
+Nevertheless the core part does not provide any meta-configuration models, so to run Tamaya
+in a minimal setup, you must provide, e.g. by adding the following dependency:
+
+    <dependency>
+      <artifactId>org.apache.tamaya.meta</id>
+      <artifactId>tamaya-metamodel-minimal</artifactId>
+      <version><CURRENT_VERSION></version>
+    </dependency>
+
+This will allow you to organize your configuration as follows:
+
+    classpath:META-INF/cfg/default/**/*.xml,classpath:META-INF/cfg/default/**/*.properties,classpath:META-INF/cfg/default/**/*.ini
+    classpath:META-INF/cfg/config/**/*.xml,classpath:META-INF/cfg/config/**/*.properties,classpath:META-INF/cfg/config/**/*.ini
+
+Additional you set the following two system properties to define external properties to be 
+considered that will **override** the configuration provided with your code:
+
+    -Dconfig.default.location=... -Dconfig.location=...
+
+So for simple use cases this is far enough and easy to understand.
+
+### Classloader Aware Meta-Model
+
+tbd
+
+### Java EE Default Meta-Model
+
+tbd
+
+## Environment Models
+### Extended SE Environment-Model
+
+tbd
+
+### Classloader Aware Environment-Model
 
-    <server>
-      <id>tamaya-site</id>
-      <username><YOUR_USERNAME></username>
-      <password><YOUR_PASSWORD></password>
-    </server>
+tbd
 
-Then run:
+### Java EE Default Environment-Model
 
-    $ mvn site-deploy
+tbd
 
-After log in to <https://cms.apache.org/tamaya/publish> and click on the `Submit` button.
\ No newline at end of file