Update documentation about osgi installer and configurations
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 f6eda54..8418c6e 100644
--- a/src/main/jbake/content/documentation/bundles/configuration-installer-factory.md
+++ b/src/main/jbake/content/documentation/bundles/configuration-installer-factory.md
@@ -6,25 +6,24 @@
The configuration installer factory provides support for configurations to the [OSGI installer](/documentation/bundles/osgi-installer.html). The provisioning of artifacts is handled by installer providers like the [file installer](/documentation/bundles/file-installer-provider.html) or the [JCR installer](/documentation/bundles/jcr-installer-provider.html).
-
## Configurations
-
+
Configuration file names are related to the PID and factory PID. The structure of the file name is as follows:
-
+
filename ::= <pid> ( ( '-' | '~' ) <subname> ) ? ( '.cfg' | '.config' | '.cfg.json')
-
+
If the form is `<pid>('.cfg'|'.config'|'.cfg.json')`, the file contains the properties for a Managed Service. The `<pid>` is then the PID of the Managed Service. See the Configuration Admin service for details.
-
+
When a Managed Service Factory is used, the situation is different. The `<pid>` part then describes the PID of the Managed Service Factory. You can pick any `<subname>`, the installer will then create an instance for the factory for each unique name. For example:
-
+
com.acme.xyz.cfg // configuration for Managed Service
// com.acme.xyz
com.acme.abc-default.cfg // Managed Service Factory,
// creates an instance for com.acme.abc
-
+
Since Installer Configuration Factory 1.2.0 ([SLING-7786](https://jira.apache.org/jira/browse/SLING-7786)) you should use the tilde `~` as separator between `<pid>` and `<subname>` instead of the `-`.
@@ -32,32 +31,34 @@
The code for parsing the configuration files is in [InternalResource#readDictionary](https://github.com/apache/sling-org-apache-sling-installer-core/blob/7b2e4407baa45b79d954dd20c53bb2077c3a5e49/src/main/java/org/apache/sling/installer/core/impl/InternalResource.java#L230).
-### Property Files (.cfg)
+### Configuration Files (.cfg.json)
-Configuration files ending in `.cfg` are plain property files (`java.util.Property`). The format is simple:
-
+This is the preferred way to specify configurations as it is an official format specified by OSGi in the [OSGi R7 Service Configurator Spec](https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html) and is also used by the [Feature Model](https://github.com/apache/sling-org-apache-sling-feature/blob/master/readme.md). The detailed JSON format is described in that specification. It allows for typed values, allowing all possible types including Collections and comments.
- file ::= ( header | comment ) *
- header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
- comment ::= '#' <any>
+There are some differences to the [resource format specification](https://osgi.org/specification/osgi.cmpn/7.0.0/service.configurator.html#service.configurator-resources) as outlined below:
-Notice that this model only supports string properties. For example:
-
- # default port
- ftp.port = 21
+* Each file contains exactly one configuration, therefore it only contains the properties of the configuration.
+* Keys starting with `:configurator:` should not be used (in general they are validated but not further evaluated)
+* The PID is given via the file name (the part preceeding the `.cfg.json`) instead of `:configurator:symbolic-name`
+* There is no version support i.e. `:configurator:version` should not be used either
-In addition the XML format defined by [java.util.Property](https://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#loadFromXML%28java.io.InputStream%29) is supported if the file starts with the character `<`.
+This is an example file
+
+ {
+ "key": "val",
+ "some_number": 123,
+ // This is an integer value:
+ "size:Integer" : 500
+ }
#### Limitations
-* Only String types are supported
-* Only ISO 8859-1 character encoding supported
-* No multi-values
-* No writeback support
+* No writeback support yet ([SLING-8419](https://issues.apache.org/jira/browse/SLING-8419))
+* This is only supported since Installer Configuration Factory 1.2.0 ([SLING-7787](https://issues.apache.org/jira/browse/SLING-7787)).
### Configuration Files (.config)
-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). This format allows to specify the type and cardinality of a configuration property and is not limited to string values. It must be stored in UTF-8 encoding.
+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). This format allows to specify the type and cardinality of a configuration property and is not limited to string values. It must be stored in UTF-8 encoding. This format is preferred over properties files and nodes stored in the repository.
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.
@@ -67,9 +68,9 @@
comment ::= '#' <any>
header ::= prop '=' value
prop ::= symbolic-name // 1.4.2 of OSGi Core Specification
- symbolic-name ::= token { '.' token }
+ symbolic-name ::= token { '.' token }
token ::= { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' }
- value ::= [ type ] ( '[' values ']' | '(' values ')' | simple )
+ value ::= [ type ] ( '[' values ']' | '(' values ')' | simple )
values ::= ( simple { ',' simple } | '\' <nl> simple { ', \' <nl> simple } <nl> )
simple ::= '"' stringsimple '"'
type ::= <1-char type code>
@@ -114,27 +115,37 @@
* No support for nested multivalues (arrays or Collections)
* No user-friendly (readable) values for floating points ([SLING-7757](https://issues.apache.org/jira/browse/SLING-7757))
-### Configuration Files (.cfg.json)
+### Property Files (.cfg)
-This is only supported since Installer Configuration Factory 1.2.0 ([SLING-7787](https://issues.apache.org/jira/browse/SLING-7787)).
+Configuration files ending in `.cfg` are plain property files (`java.util.Property`). The format is simple:
-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).
-The only differences to the spec are outlined below
+ file ::= ( header | comment ) *
+ header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
+ comment ::= '#' <any>
-* `:configurator:resource-version` may be used, but only version 1 is supported
-* other keys starting with `:configurator:` should not be used (in general they are validated but not further evaluated)
- * The PID is given via the file name (the part preceeding the `.cfg.json`) instead of `:configurator:symbolic-name`
- * There is no version support i.e. `:configurator:version` should not be used either
+Notice that this model only supports string properties. For example:
+
+ # default port
+ ftp.port = 21
+
+In addition the XML format defined by [java.util.Property](https://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#loadFromXML%28java.io.InputStream%29) is supported if the file starts with the character `<`.
#### Limitations
-* No writeback support yet ([SLING-8419](https://issues.apache.org/jira/browse/SLING-8419))
+* Only String types are supported
+* Only ISO 8859-1 character encoding supported
+* No multi-values
+* No writeback support
+
+
### sling:OsgiConfig resources
Only the [JCR Installer](/documentation/bundles/jcr-installer-provider.html#configuration-and-scanning) supports also configurations given as resources with properties of type `sling:OsgiConfig`. Internally those are converted directly into the Dictionary format being supported by the [OSGi Configuration Admin](https://osgi.org/javadoc/r4v42/org/osgi/service/cm/Configuration.html#update%28java.util.Dictionary%29) in [ConfigNodeConverter](https://github.com/apache/sling-org-apache-sling-installer-provider-jcr/blob/fcb77de40973672548e79f3a42c19f5decd95651/src/main/java/org/apache/sling/installer/provider/jcr/impl/ConfigNodeConverter.java#L44).
+While this way of specifying configurations in a JCR repository seems like a natural fit, it should be avoided as it neither supports all required types nor is it portable.
+
#### Limitations
* Not all types supported ([SLING-2477](https://issues.apache.org/jira/browse/SLING-2477))
@@ -144,4 +155,3 @@
# Project Info
* Configuration installer factory ([org.apache.sling.installer.factory.configuration](https://github.com/apache/sling-org-apache-sling-installer-factory-configuration))
-
