svn commit: r1792590 - /sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext

[ss...@apache.org]

Author: sseifert
Date: Tue Apr 25 09:26:49 2017
New Revision: 1792590

URL: http://svn.apache.org/viewvc?rev=1792590&view=rev
Log:
SLING-6788 add section about the Management API

Modified:
    sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext

Modified: 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=1792590&r1=1792589&r2=1792590&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration.mdtext Tue Apr 25 09:26:49 2017
@@ -82,13 +82,13 @@ Internally the ConfigurationResolver use
 
 # Contexts and configuration references
 
-When you use the [Default Implementation](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html) contexts in the content resource hierarchy is defined by setting `sling:configRef` properties. Each resource that has a `sling:configRef` 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.
+When you use the [Default Implementation][default-impl] contexts in the content resource hierarchy is defined by setting `sling:configRef` properties. Each resource that has a `sling:configRef` 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:
 
 ![Context and config reference](context-and-config-reference.png)
 
-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](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html) for details.
+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][default-impl] for details.
 
 
 # Describe configurations via annotation classes
@@ -210,9 +210,9 @@ Full example: [Apache Sling Context-Awar
 
 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](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html) for details.
+See [SPI][spi] for details.
 
-You can also override specific context-aware configuration within an instance - see [Override](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html) for details.
+You can also override specific context-aware configuration within an instance - see [Override][override] for details.
 
 
 # Web Console plugins
@@ -225,10 +225,23 @@ The Context-Aware Configuration implemen
 To use the web console plugin you need to configure a "Service User" mapping for the bundle `org.apache.sling.caconfig.impl` to a system user which has read access to all context and configuration resources. By default this should be `/content`, `/conf`, `/apps/conf` and `/libs/conf`.
 
 
+# Management API
+
+The Context-Aware Configuration Implementation Bundle provides a Management API which allows to read and write configuration data. It supports only Context-Aware configurations, not context-aware resources. It should not be used directly in applications, but is intended to provide an API for editor GUIs and other tools which allow to manage configurations.
+
+The main entry point is the OSGi service `org.apache.sling.caconfig.management.ConfigurationManager`. It allows to get, write or delete singleton configurations and configuration lists. Configuration data is returned using `ConfigurationData` and `ConfigurationCollectionData` objects which also provide access to additional metadata about the resolving process and inheritance/override status of each property. Internally the configuration manager uses the [SPI][spi] implementation to resolve and write the configuration data.
+
+Whenever configuration data is read or written from the configuration resources a filtering of property names is applied to make sure "system-properties" like `jcr:primaryType` or 'jcr:created' are not returned as part of the configuration data. A list of regular expressions for this filtering can be configured via the "Apache Sling Context-Aware Configuration Management Settings" OSGi configuration. The configuration is accessible to custom persistence implementations via the `org.apache.sling.caconfig.management.ConfigurationManagementSettings` OSGi service. By default all properties in the `jcr:` namespace are filtered out.
+
+
 # References
 
-* [Context-Aware Configuration - Default Implementation](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html)
-* [Context-Aware Configuration - SPI](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html)
-* [Context-Aware Configuration - Override](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html)
+* [Context-Aware Configuration - Default Implementation][default-impl]
+* [Context-Aware Configuration - SPI][spi]
+* [Context-Aware Configuration - Override][override]
 * [Sling Context-Aware Configuration - Talk from adaptTo() 2016](https://adapt.to/2016/en/schedule/sling-context-aware-configuration.html)
  
+
+[default-impl]: http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-default-implementation.html
+[spi]: http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html
+[override]: http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html