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)
