Author: sseifert
Date: Thu Oct 13 13:32:39 2016
New Revision: 1764671
URL: http://svn.apache.org/viewvc?rev=1764671&view=rev
Log:
Context-Aware Configuration docs
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/
sling/site/trunk/content/documentation/bundles/context-aware-configuration/config-resource-lookup.png
(with props)
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-and-config-reference.png
(with props)
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-default-implementation.mdtext
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-example.png
(with props)
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-spi.mdtext
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext
sling/site/trunk/content/documentation/bundles/context-aware-configuration/illustration-sources.pptx
(with props)
sling/site/trunk/content/documentation/bundles/context-aware-configuration/resource-inheritance.png
(with props)
Modified:
sling/site/trunk/content/documentation/bundles.mdtext
Modified: sling/site/trunk/content/documentation/bundles.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles.mdtext?rev=1764671&r1=1764670&r2=1764671&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles.mdtext Thu Oct 13 13:32:39
2016
@@ -47,6 +47,7 @@ The OSGi installer is a very flexible an
* [Sling Pipes]({{ refs.sling-pipes.path }})
* [Sling Metrics]({{ refs.metrics.path }})
* [Servlet Helpers]({{ refs.servlet-helpers.path }})
+* [Context-Aware Configuration]({{ refs.context-aware-configuration.path }})
## Content Presentation
* [Scripting]({{ refs.scripting.path }}) (aka Templating)
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/config-resource-lookup.png
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/config-resource-lookup.png?rev=1764671&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/config-resource-lookup.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/config-resource-lookup.png
------------------------------------------------------------------------------
svn:needs-lock = *
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-and-config-reference.png
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-and-config-reference.png?rev=1764671&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-and-config-reference.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-and-config-reference.png
------------------------------------------------------------------------------
svn:needs-lock = *
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-default-implementation.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-default-implementation.mdtext?rev=1764671&view=auto
==============================================================================
---
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-default-implementation.mdtext
(added)
+++
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-default-implementation.mdtext
Thu Oct 13 13:32:39 2016
@@ -0,0 +1,96 @@
+Title: Apache Sling Context-Aware Configuration - Default Implementation
+
+[TOC]
+
+# About
+
+By default the 'default implementation' us used by the Context-Aware
Configuration concerning lookup and persistence of configuration data, resource
and property inheritance and context path detection. Using the [SPI]({{
ref.context-aware-config-spi.path }}) it is possible to overlay, extend or
replace this functionality.
+
+This page documents the details of the default implementation.
+
+
+# Repository paths
+
+By default all configuration data is stored in `/conf`. Fallback paths are
`/conf/global`, `/apps/conf`and `/libs/conf`.
+
+The paths are configurable in the service configuration.
+
+
+# Context paths
+
+The content resource hierarchy is defined by setting `sling:config-ref`
properties. Each resource that has a `sling:config-ref` property set defines
the root resource of a context, the whole subtree is the context. Within the
subtree further nested contexts can be defined.
+
+
+# Configuration resource resolving
+
+This illustration shows an example for configuration resource lookup:
+
+
+
+If you get the context-aware configuration via the API for any resource below
`/content/tenant1/region1/site1` it is looked up in this path in this order:
+
+1. `/conf/brand1/tenant1/region1/site1` - because referenced by
`/content/tenant1/region1/site1`
+2. `/conf/brand1/tenant1/region1` - because referenced by
`/content/tenant1/region1` (parent context)
+3. `/conf/brand1/tenant1` - because referenced by `/content/tenant1` (parent
context)
+4. `/conf/brand1` - because it is a parent of by `/conf/brand1/tenant1`
+5. `/conf/global` - because it is configured as fallback path
+6. `/apps/conf` - because it is configured as fallback path
+7. `/libs/conf` - because it is configured as fallback path
+
+So the basic rules are:
+* Go up in the content resource tree until a resource with `sling:config-ref`
is found. This is the 'inner-most' context. Check if a configuration resource
exists at the path the property points to.
+* Check for parent resources of the references configuration resource (below
`/conf`)
+* Go further up in the content resource tree for parent contexts, and check
their configuration resources as well (they may reference completely different
location below `/conf`)
+* Check the fallback paths
+
+
+# Configuration persistence
+
+Example for the resource structure for a configuration resource at
`/conf/mysite`:
+
+ /conf
+ /mysite
+ /sling:configs
+ /x.y.z.MyConfig
+ @prop1 = 'value1'
+ @prop2 = 123
+ @prop3= true
+
+Explanation:
+
+* `sling:configs` is the bucket named which is used by the
ConfigurationResolver by default for context-aware configurations. May be
another name if you use the ConfigurationResourceResolver directly.
+* `x.y.z.MyConfig` is the configuration name, in this case derived from an
annotation class. May be any other custom name as well.
+* `prop1..3`are example for configuration properties
+* It is possible to use deeper hierarchies below `sling:configs` as well.
+* Nested configurations are supported as well. This can be mapped to
annotation classes referencing other annotation classes.
+
+
+# Resource inheritance
+
+We distinguish between:
+
+- Singleton resources: Configuration resources looked up by the `get`/`as`
method variants
+- Collection resources: Configuration resources lists looked up by the
`getCollection`/`asCollection` method variants
+
+For singleton resources, there is not resource inheritance. The first resource
that is found in the configuration resource resolving lookup order is returned.
+
+For collection resources there is no resource inheritance enabled by default.
The children of the first resource that is found in the configuration resource
resolving lookup order are returned.
+
+By defining a property `sling:config-collection-inherit` on the configuration
resource, the children of the next resource that is found in the configuration
resource resolving lookup order are combined with the children of the current
configuration resource, returned a merged list. If both configuration resources
contain child resources with the same name, duplicates are eliminated and only
the children of the first resource are included.
+
+By setting the property `sling:config-collection-inherit` on multiple
configuration resources that are part of the lookup order it is possible to
form deeper inheritance chains following the same rules.
+
+Example for resource inheritance:
+
+
+
+The result of this example is: **C, A, B**. It would by just **C** if the
`sling:config-collection-inherit` is not set.
+
+
+# Property inheritance
+
+By default, no property inheritance takes place. That means only the
properties that are stored in the configuration resource are mapped to the
annotation class or returned as value map, regardless wither singleton or
collection resources are returned, or if resource collection inheritance is
enabled or not.
+
+By defining a property `sling:config-property-inherit` on the configuration
resource, property merging is enabled between the current configuration
resource and the next resource with the same name (singleton or resource
collection item) in the configuration resource lookup order. That means that
all properties that are not defined on the current configuration resource are
inherited from the next resources and a merged value map is used for the
configuration mapping.
+
+By setting the property `sling:config-property-inherit` on multiple
configuration resources that are part of the lookup order it is possible to
form deeper inheritance chains following the same rules.
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-example.png
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-example.png?rev=1764671&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-example.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-example.png
------------------------------------------------------------------------------
svn:needs-lock = *
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-spi.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-spi.mdtext?rev=1764671&view=auto
==============================================================================
---
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-spi.mdtext
(added)
+++
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-config-spi.mdtext
Thu Oct 13 13:32:39 2016
@@ -0,0 +1,46 @@
+Title: Apache Sling Context-Aware Configuration - SPI
+
+[TOC]
+
+
+# About
+
+The Context-Aware Configuration implementation provides a set of Service
Provider Interfaces (SPI) that allows you to overlay, enhance or replace the
default implementation and adapt it to your needs.
+
+Please use the SPI with care, and first check if the [Default
Implementation]({{ ref.context-aware-config-default-implementation.path }})
does not already fulfill your needs.
+
+
+
+# General principles
+
+All SPIs share a common principle:
+
+- Support multiple strategies at the same time
+- No need to switch off or âcopyâ the initial strategy
+- Apply additional strategies only for those places where needed (âminimally
invasiveâ)
+
+All existing implementations are iterated in order of their service ranking.
+
+
+# Context Path Strategy
+
+By providing an implementation of
`org.apache.sling.contextaware.config.resource.spi.ContextPathStrategy` you can
provide additional ways how context paths are detected in your content resource
hierarchy.
+
+E.g. you could implement detecting context paths by project-specific
conventions.
+
+
+# Configuration Resource Resolver Strategy
+
+By providing an implementation of
`org.apache.sling.contextaware.config.resource.spi.ConfigurationResourceResolvingStrategy`
you can define where configuration data is looked up, and how resource and
property inheritance is handled.
+
+
+# Configuration Persistence Strategy
+
+By providing an implementation of
`org.apache.sling.contextaware.config.spi.ConfigurationPersistenceStrategy` you
can define the peristence structure of the configuration within the
configuration resources.
+
+E.g. you could use a specific JCR node type or slightly different content
structure to store the configuration data.
+
+
+# Configuration Metadata Provider
+
+By providing an implementation of
`org.apache.sling.contextaware.config.spi.ConfigurationMetadataProvider` you
can provide information about configuration metadata from other sources than
annotation classes.
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext?rev=1764671&view=auto
==============================================================================
---
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext
(added)
+++
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext
Thu Oct 13 13:32:39 2016
@@ -0,0 +1,167 @@
+Title: Apache Sling Context-Aware Configuration
+
+[TOC]
+
+# About
+
+These bundles provide a service API that can be used to get context-aware
configurations. Context-aware configurations are configurations that are
related to a content resource or a resource tree, e.g. a web site or a tenant
site.
+
+Here is an example how your content structure may look like:
+
+
+
+The application needs different configuration for different sites, regions and
tenants = different contexts. Some parameters may be shared, so inheritance for
nested contexts and from global fallback values is supported as well. You have
full control which content subtrees are the contexts in your application, the
structure above is only an example.
+
+Using the Context-Aware Configuration Java API you can get the matching
configuration for each content resource without caring where it is stored or
how the inheritance works.
+
+
+# Java API
+
+To get and use configurations, the Java API must be used. Any using code must
not make any assumptions on how the context-aware configurations are searched
or stored!
+
+The Java API consists of two parts:
+
+- Context-Aware Resources: 'Low-level' API for accessing configuration
resources (which can be anything, e.g. workflow definitions)
+- Context-Aware Configurations: 'High-level' API for accessing configuration
data (key/value pairs)
+
+In most cases you will use only the 'High-level' API for getting context-aware
configurations.
+
+
+## Context-Aware Resources
+
+The base concept are context-aware resources: for a given content resource, a
named configuration resource can be get.
+The service for getting the configuration resources is called the
ConfigurationResourceResolver. This service has two methods:
+
+- getting a named configuration resource
+- getting all child resources of a named configuration resource.
+
+For example to get a configuration resource for a content resource at
/content/mysite/page1, you would get a reference to the OSGi service
+`org.apache.sling.contextaware.config.resource.ConfigurationResourceResolver`
and write:
+
+ #!java
+ Resource contentResource =
resourceResolver.getResource("/content/mysite/page1");
+
+ Resource configResource =
configurationResourceResolver.getResource(contentResource, "my-bucket",
"my-config");
+
+Or if you have several configuration resources of the same type and you need
all of them:
+
+ #!java
+ Collection<Resource> configResources =
configurationResourceResolver.getResourceCollection(contentResource,
"my-bucket", "my-config");
+
+The ConfigurationResourceResolver has a concept of "buckets" (2nd parameter in
the method signatures) that allows to separate different types of configuration
resources into different resource hierarchies, so you have a separate
"namespaces" for the named configuration resources. For example one bucket for
workflow definitions, one bucket for template definitions, one for
key/value-pairs.
+
+The configuration name (3rd parameter) defines which configuration you are
interested in. The name can be a relative path as well (e.g.
`"sub1/my-config"`).
+
+
+## Context-Aware Configurations
+
+While context-aware resources give you pure resources and your application
code can decide what to do with it,
+the most common use case is some configuration. A configuration is usually
described by an annotation class
+(like Declarative Services does for component configurations). These are typed
configuration objects
+and the context-aware configuration support automatically converts resources
into the wanted configuration type.
+
+Context-aware configurations are built on top of context-aware resources. The
same concept is used: configurations are
+named and the service to get them is the ConfigurationResolver. You can get a
reference to the OSGi service
+`org.apache.sling.contextaware.config.ConfigurationResolver` - it has a single
method to get a ConfigurationBuilder.
+Alternatively you can directly adapt your content resource directly to the
ConfigurationBuilder interface and get the configuration:
+
+ #!java
+ Resource contentResource =
resourceResolver.getResource("/content/mysite/page1");
+
+ MyConfig config =
contentResource.adaptTo(ConfigurationBuilder.class).as(MyConfig.class);
+
+Or if you want to get a list of configurations:
+
+ #!java
+ Collection<MyConfig> configs =
contentResource.adaptTo(ConfigurationBuilder.class).asCollection(MyConfig.class);
+
+The ConfigurationBuilder also supports getting the configurations as ValueMap
or by adapting the configuration resources e.g. to a Sling Model. In this case
you have to specify a configuration name which is otherwise derived
automatically from the annotation class.
+
+Internally the ConfigurationResolver used the ConfigurationResourceResolver to
get the configuration resources. It uses always the bucket name `sling:configs`.
+
+
+# Contexts and configuration references
+
+When you use the [Default Implementation]({{
ref.context-aware-config-default-implementation.path }}) contexts in the
content resource hierarchy is defined by setting `sling:config-ref` properties.
Each resource that has a `sling:config-ref` property set defines the root
resource of a context, the whole subtree is the context. Within the subtree
further nested contexts can be defined. The property contains a resource path
pointing to a resource below `/conf`. This is the configuration reference.
+
+Example:
+
+
+
+If you define nested contexts or use a deeper hierarchy of resourced in
`/conf` the inheritance rules are applied. Additionally it is possible to
define default values as fallback if no configuration resource exists yet in
`/conf`. See [Default Implementation]({{
ref.context-aware-config-default-implementation.path }}) for details.
+
+
+# Describe configurations via annotation classes
+
+You need an annotation class for each configuration you want to read via the
ConfigurationBuilder. The annotation classes may be provided by
+the applications/libraries you use, or you can define your own annotation
classes for your application.
+
+The annotation class may look like this:
+
+ #!java
+ @Configuration(label="My Configuration", description="Describe me")
+ public @interface MyConfig {
+
+ @Property(label="Parameter #1", description="Describe me")
+ String param1();
+
+ @Property(label="Parameter with Default value",
description="Describe me")
+ String paramWithDefault() default "defValue";
+
+ @Property(label="Integer parameter", description="Describe me")
+ int intParam();
+
+ }
+
+The `@Configuration` annotation is mandatory. All properties on the
`@Configuration` annotation and the `@Property` annotations are optional - they
provide additional metadata for tooling e.g. configuration editors.
+
+By default the annotation class name is used as configuration name, which is
also the recommended option. If you want to use an arbitrary configuration name
you can specify it via a `name` property on the `@Configuration` annotation.
+
+You may specify custom properties (via `property` string array) for the
configuration class or each properties. They are not used by the Sling
Context-Aware configuration implementation, but may be used by additional
tooling to manage the configurations.
+
+If you provide your own configuration annotation classes in your bundle, you
have to export them and list all class names in a bundle header named
`Sling-ContextAware-Configuration-Classes` - example:
+
+ Sling-ContextAware-Configuration-Classes: x.y.z.MyConfig, x.y.z.MyConfig2
+
+To automate this you can use the Context-Aware Configuration BND plugin (see
next chapter).
+
+
+# Context-Aware Configuration BND plugin
+
+A [BND](http://bnd.bndtools.org/) plugin is provided that scans the classpath
of a bundle Maven project at build time and automatically generates a
`Sling-ContextAware-Configuration-Classes` bundle header for all annotation
classes annotated with `@Configuration`. It can be used by both
[maven-bundle-plugin](http://felix.apache.org/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html)
and [bnd-maven-plugin](https://github.com/bndtools/bnd/tree/master/maven), as
both use the BND library internally.
+
+Example configuration:
+
+ #!xml
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <extensions>true</extensions>
+ <configuration>
+ <instructions>
+ <!-- Generate bundle header containing all configuration
annotation classes -->
+
<_plugin>org.apache.sling.contextaware.config.bndplugin.ConfigurationClassScannerPlugin</_plugin>
+ </instructions>
+ </configuration>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.sling</groupId>
+
<artifactId>org.apache.sling.contextaware.config.bnd-plugin</artifactId>
+ <version>1.0.0</version>
+ </dependency>
+ </dependencies>
+ </plugin>
+
+
+# Customizing the configuration lookup
+
+The Context-Aware Configuration implementation provides a set of Service
Provider Interfaces (SPI) that allows you to overlay, enhance or replace the
default implementation and adapt it to your needs.
+
+See [SPI]({{ ref.context-aware-config-spi.path }}) for details.
+
+
+# References
+
+* [Context-Aware Configuration - Default Implementation]({{
ref.context-aware-config-default-implementation.path }})
+* [Context-Aware Configuration - SPI]({{ ref.context-aware-config-spi.path }})
+* [Sling Context-Aware Configuration - Talk from adaptTo()
2016](https://adapt.to/2016/en/schedule/sling-context-aware-configuration.html)
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/illustration-sources.pptx
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/illustration-sources.pptx?rev=1764671&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/illustration-sources.pptx
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/illustration-sources.pptx
------------------------------------------------------------------------------
svn:needs-lock = *
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/resource-inheritance.png
URL:
http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/resource-inheritance.png?rev=1764671&view=auto
==============================================================================
Binary file - no diff available.
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/resource-inheritance.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Propchange:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/resource-inheritance.png
------------------------------------------------------------------------------
svn:needs-lock = *
