You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by ss...@apache.org on 2016/11/19 05:02:17 UTC
svn commit: r1770469 - in
/sling/site/trunk/content/documentation/bundles/context-aware-configuration:
context-aware-configuration-override.mdtext
context-aware-configuration-spi.mdtext context-aware-configuration.mdtext
Author: sseifert
Date: Sat Nov 19 05:02:17 2016
New Revision: 1770469
URL: http://svn.apache.org/viewvc?rev=1770469&view=rev
Log:
SLING-6060 override documentation
Added:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-override.mdtext
Modified:
sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.mdtext
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-override.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-override.mdtext?rev=1770469&view=auto
==============================================================================
--- sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-override.mdtext (added)
+++ sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-override.mdtext Sat Nov 19 05:02:17 2016
@@ -0,0 +1,67 @@
+Title: Apache Sling Context-Aware Configuration - Override
+
+[TOC]
+
+
+# About
+
+Using overrides it is possible to override context-aware configuration globally or for specific content paths (and their subtrees) within an instance. This overrides the configuration read and inherited by the default ways.
+
+An example use case is to overwrite the Site URLs on your staging system which has a copy of the configuration content of the production system installed.
+
+Via the [SPI](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html) you can add your own override providers - but in most cases the built-in ones described in this page are sufficient. All override providers use the same override syntax.
+
+
+# Override syntax
+
+Generally an override consists of one single line. Syntax examples:
+
+ {configName}/{propertyName}={propertyJsonValue}
+ {configName}={propertyJsonObject}
+ [{contextPath}]{configName}/{propertyName}={propertyJsonValue}
+ [{contextPath}]{configName}={propertyJsonObject}
+
+The different parts:
+
+* `{configName}` - Configuration name - can be a relative path with sub-resources
+* `{propertyName}` - Property name
+* `{propertyJsonValue}` - Property value in JSON value syntax.
+* `{propertyJsonObject}` - If the property name is missing a JSON object can be defined containing all properties as key-value pairs.
+* `{contextPath}` - If the context path is missing, the override is applied to all context path. If it is defined (enclosed in brackets), the override is applied only to this content path and it's subtree.
+
+When the syntax `{configName}/{propertyName}={propertyJsonValue}` is used, only this specific property is overwritten leaving all other properties in the configuration resource untouched. When the syntax `{configName}={propertyJsonObject}` is used, all configuration properties in the configuration resources are replaced with the set from the JSON object.
+
+Override string examples with real values:
+
+ my-config/property1="value 1"
+ my-config/sub1/property1='value 1'
+ my-config/property1=['value 1','value 2']
+ my-config/property1=123
+ x.y.z.MyConfig={prop1='value1', prop2=[1,2,3], prop3=true, prop4=1.23}
+ [/content/region1]my-config/property1='value 1'
+ [/content/region1]my-config/sub1={prop1="value 1"}
+
+If multiple statements are defined affecting the same content path, configuration name and property name, they overwrite each other. That means the override string defined last wins.
+
+
+# Built-in override providers
+
+## Override via system properties
+
+Allows to define configuration property overrides from system environment properties.
+
+The parameters are defined when starting the JVM using the -D command line parameter. Each parameter contains an override string. All parameter names have to be prefixed with the string `sling.caconfig.override.`.
+
+Example:
+
+ -Dsling.caconfig.override.my-config/sub1/property1=123
+ -D"sling.caconfig.override.my-config/property1=['value 1','value 2']"
+ -D"sling.caconfig.override.[/content/region1]x.y.z.MyConfig={prop1='value1', prop2=[1,2,3], prop3=true, prop4=1.23}"
+
+This provider is not active by default, it has to be activated via OSGi configuration ("Apache Sling Context-Aware System Property Configuration Override Provider").
+
+## Override via OSGi configuration
+
+Allows to define configuration property overrides from OSGi configuration.
+
+You can provide multiple providers using a factory configuration ("Apache Sling Context-Aware OSGi Configuration Override Provider"), each of them provides list of override strings.
Modified: sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.mdtext?rev=1770469&r1=1770468&r2=1770469&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.mdtext Sat Nov 19 05:02:17 2016
@@ -34,6 +34,11 @@ E.g. you could implement detecting conte
By providing an implementation of `org.apache.sling.caconfig.resource.spi.ConfigurationResourceResolvingStrategy` you can define where configuration data is looked up, and how resource and property inheritance is handled.
+# Configuration Inheritance Strategy
+
+By providing an implementation of `org.apache.sling.caconfig.spi.ConfigurationInheritanceStrategy` you can define if and how resource are inherited across the inheritance chain.
+
+
# Configuration Persistence Strategy
By providing an implementation of `org.apache.sling.caconfig.spi.ConfigurationPersistenceStrategy` you can define the peristence structure of the configuration within the configuration resources.
@@ -44,3 +49,10 @@ E.g. you could use a specific JCR node t
# Configuration Metadata Provider
By providing an implementation of `org.apache.sling.caconfig.spi.ConfigurationMetadataProvider` you can provide information about configuration metadata from other sources than annotation classes.
+
+
+# Configuration Override Provider
+
+By providing an implementation of `org.apache.sling.caconfig.spi.ConfigurationOverrideProvider` you can provide your own overrides - if the built-in override provider do not fit your needs.
+
+See [Override](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-override.html) for the list of built-in providers and the override syntax.
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=1770469&r1=1770468&r2=1770469&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 Sat Nov 19 05:02:17 2016
@@ -159,10 +159,13 @@ The Context-Aware Configuration implemen
See [SPI](http://sling.apache.org/documentation/bundles/context-aware-configuration/context-aware-configuration-spi.html) 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.
+
# 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)
* [Sling Context-Aware Configuration - Talk from adaptTo() 2016](https://adapt.to/2016/en/schedule/sling-context-aware-configuration.html)