Author: sseifert Date: Thu Oct 13 14:02:01 2016 New Revision: 1764685 URL: http://svn.apache.org/viewvc?rev=1764685&view=rev Log: link to new documentation
Modified: sling/trunk/contrib/extensions/contextaware-config/README.md Modified: sling/trunk/contrib/extensions/contextaware-config/README.md URL: http://svn.apache.org/viewvc/sling/trunk/contrib/extensions/contextaware-config/README.md?rev=1764685&r1=1764684&r2=1764685&view=diff ============================================================================== --- sling/trunk/contrib/extensions/contextaware-config/README.md (original) +++ sling/trunk/contrib/extensions/contextaware-config/README.md Thu Oct 13 14:02:01 2016 @@ -1,113 +1,5 @@ Apache Sling Context-Aware Configuration ======================================== -Apache Sling Context-Aware Configuration is work-in-progress. - -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. - -1. 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! - -1.1 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 write: - - Resource pageResource = resourceResolver.getResource("/content/mysite/page1"); - - Resource configResource = configurationResourceResolver.getResource(pageResource, "configs", "site-configuration"); - -Or if you have several configuration resources of the same type and you need all of them: - - Collection<Resource> configResources = configurationResourceResolver.getResourceCollection(pageResource, "configs", socialmedia"); - -1.2 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. It has a single method to get a ConfigurationBuilder -and this builder can then be used to get configurations: - - Resource pageResource = resourceResolver.getResource("/content/mysite/page1"); - - ConfigurationBuilder builder = configurationResolver.get(pageResource); - - SiteConfiguration siteConfig = builder.as(SiteConfiguration.class); - Collection<SocialMediaConfig> configs = builder.name("socialmedia").asCollection(SocialMediaConfig.class); - -2. Default Implementation -========================= - -The above API is completely agnostic to the way context-aware resources / configurations are searched and stored in the resource tree. -The following is how the default implementation in Apache Sling works: - -2.1 Context Resolving -===================== - -The first step is to find out to which context (e.g. site or tenant) a resource belongs. The mechanism starts at the given content resource -and looks for a property named "sling:config-ref". It traverses up the resource hierarchy until either root is reached or such a property is found. -If no property is found, there are the following fallbacks which will be searched in the given order : "/conf/global", "/apps/conf", and "/libs/conf". -These fallbacks are also used if a configuration resource is requested which does not exist in the given context. - -For example with this content structure - - /content - /mysite - @sling:config-ref = /conf/tenants/piedpiper - /page1 - /page2 - /sub - @sling:config-ref = /conf/tenants/piedpiper/sub - /pageA - /pageB - -The context for "/content/mysite/page1" is "/conf/tenants/piedpiper" while for "/content/mysite/sub/pageA" it is "/conf/tenants/piedpiper/sub" - -For "/content/mysite/page1" the implementation searches at these paths for a configuration resource named "socialmedia/facebook": - - /conf/tenants/piedpiper/sling:configs/socialmedia/facebook - /conf/global/sling:configs/socialmedia/facebook - /apps/conf/sling:configs/socialmedia/facebook - /libs/conf/sling:configs/socialmedia/facebook - -The first resource found at these locations is used, if none is found, no context-aware resource will be returned. - -For "/content/mysite/sub/pageA" the implementation searches at these paths for a configuration resource named "socialmedia/facebook" - - /conf/tenants/piedpiper/sub/sling:configs/socialmedia/facebook - /conf/global/sling:configs/socialmedia/facebook - /apps/conf/sling:configs/socialmedia/facebook - /libs/conf/sling:configs/socialmedia/facebook - -2.2 Content Model -================= - -Configurations are stored under /conf - - /conf - /global - /sling:configs - /socialmedia - /youtube - @enabled = false - @url = https://youtube.com - /tenants - /piedpiper - /sling:configs - /socialmedia - /facebook - @enabled = true - @url = https://facebook.com - +The documentation can be found here: +http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration.html