[sling-site] 01/01: improve documentation around config file formats

[kw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kwin pushed a commit to branch feature/improve-osgi-installer-config-documentation
in repository https://gitbox.apache.org/repos/asf/sling-site.git

commit 7d4f400416a5ef5c85481ccef6f0094c979f50eb
Author: Konrad Windszus <kw...@apache.org>
AuthorDate: Thu Mar 14 15:43:58 2019 +0100

    improve documentation around config file formats
---
 .../bundles/configuration-installer-factory.md     | 62 +++++++++++++++++-----
 .../bundles/jcr-installer-provider.md              | 24 ++++-----
 2 files changed, 62 insertions(+), 24 deletions(-)

diff --git a/src/main/jbake/content/documentation/bundles/configuration-installer-factory.md b/src/main/jbake/content/documentation/bundles/configuration-installer-factory.md
index 89ac103..a3be6f0 100644
--- a/src/main/jbake/content/documentation/bundles/configuration-installer-factory.md
+++ b/src/main/jbake/content/documentation/bundles/configuration-installer-factory.md
@@ -46,9 +46,15 @@ Notice that this model only supports string properties. For example:
 
 In addition the XML format defined by [java.util.Property](https://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#loadFromXML(java.io.InputStream)) is supported if the file starts with the character `<`.
 
+#### Limitations
+
+* Only String types are supported
+* Only ISO 8859-1 character encoding supported
+* No multi-values
+
 ### Configuration Files (.config)
 
-Configuration files ending in `.config` use the format of the [Apache Felix ConfigAdmin implementation](https://github.com/apache/felix/blob/trunk/configadmin/src/main/java/org/apache/felix/cm/file/ConfigurationHandler.java). It allows to specify the type and cardinality of a configuration property and is not limited to string values.
+Configuration files ending in `.config` use the format of the [Apache Felix ConfigAdmin implementation](http://svn.apache.org/viewvc/felix/releases/org.apache.felix.configadmin-1.8.12/src/main/java/org/apache/felix/cm/file/ConfigurationHandler.java?view=markup) (in version 1.8.12). It allows to specify the type and cardinality of a configuration property and is not limited to string values.
 
 The first line of such a file might start with a comment line (a line starting with a #). Comments within the file are not allowed.
 
@@ -61,7 +67,7 @@ The format is:
     symbolic-name ::= token { '.' token } 
     token ::= { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' }
     value ::= [ type ] ( '[' values ']' | '(' values ')' | simple ) 
-    values ::= simple { ',' simple } 
+    values ::= ( simple { ',' simple } | '\' <nl> simple { ', \' <nl> simple } <nl> )
     simple ::= '"' stringsimple '"'
     type ::= <1-char type code>
     stringsimple ::= <quoted string representation of the value where both '"' and '=' need to be escaped>
@@ -70,20 +76,52 @@ The quoted string format is equal to the definition from HTTP 1.1 ([RFC2616](htt
 
 The 1 character type code is one of:
 
-* `T` : simple string
-* `I` : Integer
-* `L` : Long
-* `F` : Float
-* `D` : Double
-* `X` : Byte
-* `S` : Short
-* `C` : Character
-* `B` : Boolean
+* `T` : `String`
+* `I` : `Integer`
+* `L` : `Long`
+* `F` : `Float`
+* `D` : `Double`
+* `X` : `Byte`
+* `S` : `Short`
+* `C` : `Character`
+* `B` : `Boolean`
+
+or for primitives
+
+* `i` : `int`
+* `l` : `long`
+* `f` : `float`
+* `d` : `double`
+* `x` : `byte`
+* `s` : `short`
+* `c` : `char`
+* `b` : `boolean`
 
-For Float and Double types the methods [Float.intBitsToFloat](https://docs.oracle.com/javase/7/docs/api/java/lang/Float.html#intBitsToFloat%28int%29) and [Double.longBitsToDouble](https://docs.oracle.com/javase/7/docs/api/java/lang/Double.html#longBitsToDouble%28long%29) are being used to convert the numeric string into the correct type. These methods rely on the IEEE 754 floating-point formats described in [Single-precision floating-point format](https://en.wikipedia.org/wiki/Single-pre [...]
+For Float and Double types the methods [Float.intBitsToFloat](https://docs.oracle.com/javase/7/docs/api/java/lang/Float.html#intBitsToFloat%28int%29) and [Double.longBitsToDouble](https://docs.oracle.com/javase/7/docs/api/java/lang/Double.html#longBitsToDouble%28long%29) are being used to convert the numeric string into the correct type. These methods rely on the IEEE-754 floating-point formats described in [Single-precision floating-point format](https://en.wikipedia.org/wiki/Single-pre [...]
+
+Multiple values enclosed by `[` and `]` lead to an array while those enclosed by `(` and `)` lead to a Collection in the underlying `java.util.Dictionary` of the `org.osgi.service.cm.Configuration` and vice-versa.
+
+Although both objects and primites are supported, both lead to generating the wrapper objects (and not the primitives) in the underlying `java.util.Dictionary` of the `org.osgi.service.cm.Configuration` during deserialization (even for multivalue entries).
 
 A number of such .config files exist in the Sling codebase and can be used as examples.
 
+#### Limitations
+
+* No support for Collections containing different types
+* No support for nested multivalues (arrays or Collections)
+* No write-support for primitive arrays
+
+### Configuration Files (.cfg.json)
+
+This is only supported since Installer Configuration Factory 1.2.0 ([SLING-7787](https://issues.apache.org/jira/browse/SLING-7787)).
+
+The exact JSON format is described in the [OSGi R7 Service Configurator Spec](https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html).
+
+#### Limitations
+
+* None known so far
+
+
 # Project Info
 
 * Configuration installer factory ([org.apache.sling.installer.factory.configuration](https://github.com/apache/sling-org-apache-sling-installer-factory-configuration))
diff --git a/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md b/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
index 4fe69b9..0f63010 100644
--- a/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
+++ b/src/main/jbake/content/documentation/bundles/jcr-installer-provider.md
@@ -6,33 +6,33 @@ tags=installer
 
 The JCR installer provider scans the JCR repository for artifacts and provides them to the [OSGI installer](/documentation/bundles/osgi-installer.html).
 
-## Configuration and Scanning
+# Configuration and Scanning
 
-The JCR installer provider can be configured with weighted paths which are scanned. By default, the installer scans in */apps* and */libs* where artifacts found in */apps* get a higher priority. The installer does a deep scan and uses a regular expression to detect folders containing artifacts to be installed. By default, artifacts from within a folder named *install* are provided to the OSGi installer.
+The JCR installer provider can be configured with weighted paths which are scanned. By default, the installer scans in `/apps` and `/libs` where artifacts found in `/apps` get a higher priority. The installer does a deep scan and uses a regular expression to detect folders containing artifacts to be installed. By default, artifacts from within a folder named `install` are provided to the OSGi installer.
 
 If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html)) this is provided to the OSGi installer. 
 
-In addition every node of type *sling:OsgiConfig* is provided as a configuration to the installer. This has the advantage of leveraging the JCR structure better than binary files, but has the known limitations outlined in [SLING-4183](https://issues.apache.org/jira/browse/SLING-4183) and [SLING-2477](https://issues.apache.org/jira/browse/SLING-2477), therefore it is recommended to stick to one of the binary formats described in [Configuration Installer Factory](/documentation/bundles/con [...]
+In addition every node of type `sling:OsgiConfig` is provided as a configuration to the installer. This has the advantage of leveraging the JCR structure better than binary files, but has the known limitations outlined in [SLING-4183](https://issues.apache.org/jira/browse/SLING-4183) and [SLING-2477](https://issues.apache.org/jira/browse/SLING-2477), therefore it is recommended to stick to one of the binary formats described in [Configuration Installer Factory](/documentation/bundles/con [...]
 
 The JCR installer provider does not check or scan the artifacts itself, the detection and installation is deferred to the OSGi installer.
 
 ### Runmode Support
 
-The JCR installer supports run modes for installing artifacts. By default folders named *install* are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named *install.\[RUNMODE\]* are scanned as well. To be precise, the folder name can be followed by any number of run modes separated by comma. For example, if started with run modes *dev*, *a1*, and *public*, folders like *install.dev*, *install.a1*, *install.public* are searched as well as *insta [...]
+The JCR installer supports run modes for installing artifacts. By default folders named `install` are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named `install.[RUNMODE]` are scanned as well. To be precise, the folder name can be followed by any number of run modes separated by comma. For example, if started with run modes `dev`, `a1`, and `public`, folders like `install.dev`, `install.a1`, `install.public` are searched as well as `install [...]
 
-Artifacts from folders with a run mode get a higher priority. For example by default, an *install* folder underneath */libs* gets the priority *50*. For each run mode in the folder name, this priority is increased by *1*, so *install.dev* has *51* and *install.a1.dev* is *52*.
+Artifacts from folders with a run mode get a higher priority. For example by default, an `install` folder underneath `/libs` gets the priority `50`. For each run mode in the folder name, this priority is increased by `1`, so `install.dev` has `51` and `install.a1.dev` has `52`.
 
-## Write Back Support
+### Start Level Support
 
-The JCR installer supports writing back of configurations which are changed by some other ways, e.g by using the Apache Felix web console. If this is a new configuration which was not originally stored in the repository, a new configuration is stored under */apps/sling/install*. The highest search path is used together with a configurable folder (*sling/install* in this case).
-If a configuration is changed which already exists in the repository, then it depends where the original configuration is stored. If its under */libs* a new configuration at the same path under */apps* is created. Otherwise the configuration is directly modified.
-As JCR properties do not support all Java primitive types like Integer, the write back does not generate a node of type *sling:OsgiConfig* in the repository but a properties file as described in [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html).
+If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with [SLING-2011](https://issues.apache.org/jira/browse/SLING-2011)). So e.g. a bundle in the path `/libs/sling/install/15/somebundle.jar` is having the start level `15`. 
 
-Write back can be turned off by configuration.
+# Write Back Support
 
-### Start Level Support
+The JCR installer supports writing back of configurations which are changed by some other ways, e.g by using the Apache Felix web console. If this is a new configuration which was not originally stored in the repository, a new configuration is stored under `/apps/sling/install`. The highest search path is used together with a configurable folder (`sling/install` in this case).
+If a configuration is changed which already exists in the repository, then it depends where the original configuration is stored. If its under `/libs` a new configuration at the same path under `/apps` is created. Otherwise the configuration is directly modified.
+As JCR properties do not support all Java primitive types like Integer, the write back does not generate a node of type `sling:OsgiConfig` in the repository but a .config file as described in [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html).
 
-If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with [SLING-2011](https://issues.apache.org/jira/browse/SLING-2011)). So e.g. a bundle in the path `/libs/sling/install/15/somebundle.jar` is having the start level **15**. 
+Write back can be turned off by configuration.
 
 # Example
 Here's a quick walkthrough of the JCR installer functionality.