Author: anatole Date: Tue Mar 3 11:42:16 2015 New Revision: 1663674 URL: http://svn.apache.org/r1663674 Log: Updated Site.
Modified: incubator/tamaya/site/trunk/content/documentation.mdtext incubator/tamaya/site/trunk/content/modules.mdtext incubator/tamaya/site/trunk/content/quickstart.mdtext Modified: incubator/tamaya/site/trunk/content/documentation.mdtext URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/documentation.mdtext?rev=1663674&r1=1663673&r2=1663674&view=diff ============================================================================== --- incubator/tamaya/site/trunk/content/documentation.mdtext (original) +++ incubator/tamaya/site/trunk/content/documentation.mdtext Tue Mar 3 11:42:16 2015 @@ -18,33 +18,41 @@ Notice: Licensed to the Apache Softwa [TOC] - *** -# Sources +# Available Documentation + +The current project documentation can be found [here](documentation/index.html). + + +# Enhancing Documentation +## Documentation Sources -[Tamaya Documentation](/documentation/) is available with [Tamaya Source](documentation/source.html). +The documentation is managed as part of the [Tamaya Source](source.html) -# Format +## Documentation Format -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 +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 -# Rendering documentation as HTML +## Rendering documentation as HTML _Requirenment:_ Have [Maven](http://maven.apache.org/) installed. If you cloned the source repository and want to render the documentation as HTML, you just need to run the following command: - $ cd REPO_ROOT/documentation + $ cd REPO_ROOT/docs $ mvn site -The generate documentation will be available at `REPO_ROOT/documentation/target/site` +The generate documentation will be available at `REPO_ROOT/docs/target/site` -# Contribute +## Contribute -If you would like to submit a documentation patch through Jira, you can have a look at the [suggested approach](suggested-git-workflows.html). +If you would like to submit a documentation patch through Jira, you can have a look at the +[suggested approach](suggested-git-workflows.html). -# Publish procedure (for committers only) +## Publish procedure (for committers only) 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: Modified: incubator/tamaya/site/trunk/content/modules.mdtext URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/modules.mdtext?rev=1663674&r1=1663673&r2=1663674&view=diff ============================================================================== --- incubator/tamaya/site/trunk/content/modules.mdtext (original) +++ incubator/tamaya/site/trunk/content/modules.mdtext Tue Mar 3 11:42:16 2015 @@ -24,45 +24,50 @@ Notice: Licensed to the Apache Softwa Tamaya has a modular design comprising the following parts: -* Tamaya contains a complete **API** with interfaces for *Configuration, ConfigurationProvider, - ConfigOperator, ConfigQuery, PropertyConverter, TypeLiteral, ConfigException* +* Tamaya contains a **API** with artifacts such as **Configuration, ConfigurationProvider, + ConfigOperator, ConfigQuery, PropertyConverter, TypeLiteral, ConfigException** * Besides the API Tamaya defines an **SPI**, which provides powerful extension mechanisms with artifacts such as **ConfigurationContext, ConfigurationContextBuilder, ConfigurationProviderSpi, PropertyFilter, PropertySource, PropertySourceProvider, PropertyValueCombinationPolicy, ServiceContext, ServiceContextManager**. -* The **Core** contains a small and minimal implementation of the API that contains everything needed for SE based use cases. -* The **Modules** are planned to contain extensions (based on the API, no dependencies to Core) to - ** provide injection mechanism for configuration (injection) - ** provide support for dynamic placeholders and custom resolvers (resolver) - ** provide mechanism to declaratively lookup resources in the filesystem and the classpath (resources) - ** event mechanism for modelling and propagating configuration changes (events) - ** define a common model for decoupling formatting from building up concrete property sources (formats) - ** enrich Tamaya with an extendible environment model (environment) - ** provide more complex met-configuration schemes, e.g. for OSGI, Java EE and other runtime container technologies. - ** integrate Tamaya with other frameworks such as Apache Commons Configuration, Spring and Java EE, CDI. - ** and possibly more... +* The **Core** contains a small and minimal implementation of the API that contains everything needed for SE based use + cases. +* The **Modules** are extensions (based on the API) providing different functionality such as + ** a configuration injection mechanism, including an injection SPI (**tamaya-injection**). + ** support for dynamic placeholders and resolvers, including a resolver API (**tamaya-resolver**). + ** a mechanism to declaratively lookup resources on the filesystem and the classpath (**tamaya-resources**) + ** an event mechanism for modelling and propagating configuration changes (**tamaya-events**) + ** a common model for decoupling formatting from building up concrete property sources (**tamaya-formats**) + ** an extendible environment model (tamaya-environment) + ** preconfigured more complex configuration schemes, e.g. for OSGI, Java EE and other runtime container technologies. + ** integrate of Tamaya with other frameworks such as Apache Commons Configuration, Spring and Java EE, CDI. + ** and more... -* The **Documentation** module contains overall documentations in _asciidoc_ . +NOTE: This modules are published based on the individual maturity. Check the release notes, which modules are part +of a _Tamaya_ release and which not. + +* Finally the dhe **Documentation** module contains overall documentations in _asciidoc_ . # API -The *API* models a complete Java SE API for configuration. It is possible to implement an application completely -against this API. Nevertheless the API is minimalistic and many users will add additional extensions for additional -comfort. The API is available from Maven central as +The **API** models a complete Java SE API for configuration. It is possible to implement an application completely +against this API only. The API takes about 20k of disk space (Java 8) and is available from Maven central as - <dependency> - <artifactId>org.apache.tamaya</id> - <artifactId>tamaya-api</artifactId> - <version><CURRENT_VERSION></version> - </dependency> + <dependency> + <artifactId>org.apache.tamaya</id> + <artifactId>tamaya-api</artifactId> + <version><CURRENT_VERSION></version> + </dependency> + +Nevertheless the API is also minimalistic and many users will wish more functionality available. This is where +so called _Tamaya_ extensions come into the place (see later). # Core 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_, beside the API. So it can be directly -accessed and consumed as artifact: - +The Core part hereby does _not have any external dependencies_, beside the API and also only takes about 70k of space. +So with the API less than 100k of space is needed for configuring your application. Put the following information in your pom.xml file <dependency> @@ -71,7 +76,7 @@ Put the following information in your po <version><CURRENT_VERSION></version> </dependency> -The core modules out of the box supports _.properties files +The core modules out of the box supports _.properties_ files as valid input formats. It is capable of reading configuration resources from * the classpath @@ -95,21 +100,20 @@ companies: * Configuration Context (in relation to the current _Environment_) * ... (and more) -By default _Tamaya_ implicitly registers and loads a **simple** meta-model by default, which is as follows -(first sources have lower priority): +Nevertheless, by default, _Tamaya_ registers and loads a **simple** configuration meta-model by default, which is as +follows (first sources have lower priority): * **Default entries:** META-INF/cfg/default-config.properties * **Explicit entries:** META-INF/cfg/config.properties * **System Properties** * **Environment Properties**, mapped to _env.*_ - -By default _.properties_ and _.xml_ (properties) formats as defined by _java.util.Properties_ are supported. +The_.properties_ format hereby is as defined by _java.util.Properties_. # Modules -Tamaya ships with several extension modules that provide additional APIs or integration functionality. The +Tamaya ships with several extension modules that provide additional APIs, SPIs or integration functionality. The most important ones are shortly listed in this section. @@ -170,16 +174,8 @@ existing configuration solutions can tra ### CDI Integration -When using CDI configuration injection can be provided by simply adding the following library -to your classpath: - - <dependency> - <artifactId>org.apache.tamaya.integration</id> - <artifactId>tamaya-cdi</artifactId> - <version><CURRENT_VERSION></version> - </dependency> +Planned for the future. -Additionally _Configuration_ and also other artifacts are known by CDI and can be injected. ### Spring Integration @@ -235,6 +231,6 @@ Planned for the future. ## Environment Module -There is an experimaental _Environment_ available, but not yet as a mature module ready to use. +Planned for the future. Modified: incubator/tamaya/site/trunk/content/quickstart.mdtext URL: http://svn.apache.org/viewvc/incubator/tamaya/site/trunk/content/quickstart.mdtext?rev=1663674&r1=1663673&r2=1663674&view=diff ============================================================================== --- incubator/tamaya/site/trunk/content/quickstart.mdtext (original) +++ incubator/tamaya/site/trunk/content/quickstart.mdtext Tue Mar 3 11:42:16 2015 @@ -48,7 +48,7 @@ following configuration model (most sign # Adding additional features -Depenending on your likingy you may add additional extensions such as: +Depenending on your liking you may add additional extensions such as: ## Dynamic Resolution and Value Placeholders @@ -59,7 +59,11 @@ Depenending on your likingy you may add </dependency> With that it is possible to define values with Unix styled placeholders that are resolved on configuration access, -e.g. _mykey=my${dynamicValue}_. For further details refer to the module documentation. +e.g. _mykey=my${dynamicValue}_. For further details refer to the module documentation. This module also provides +a *Resolver* singleton: + + String myExpression = ...; + String resolved = Resolver.evaluateExpression(myExpression); ## Ant-styled Path Resolution of Resources @@ -70,7 +74,7 @@ e.g. _mykey=my${dynamicValue}_. For furt <version><CURRENT_VERSION></version> </dependency> -This module provides a *ResourceResolver* service that allows to resolve configuration resources using a ant-styled +This module provides a *Resolver* singleton that allows to resolve configuration resources using a ant-styled resource description, e.g. Collection<URL> urls = ResourceResolver.getResources("META-INF/cfg/**/*.properties"); @@ -103,7 +107,7 @@ corresponding configuration: } MyType type = new MyType(); - ConfigurationInjector.injectConfiguration(type); + ConfigurationInjector.configure(type); Or the same as template: