Configuration Installer Factory

The configuration installer factory provides support for configurations to the OSGI installer. The provisioning of artifacts is handled by installer providers like the file installer or the JCR installer.

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) you should use the tilde ~ as separator between <pid> and <subname> instead of the -.

If a configuration is modified, the file installer will write the configuration back to a file to ensure persistence across restarts (if sling.fileinstall.writeback is enabled). A similar writeback mechanism is supported by the JCR installer.

The code for parsing the configuration files is in InternalResource#readDictionary.

Configuration Files (.cfg.json)

This is the preferred way to specify configurations as it is an official format specified by OSGi in the OSGi R7 Service Configurator Spec and is also used by the Feature Model. The detailed JSON format is described in that specification. It allows for typed values, allowing all possible types including Collections and comments.

There are some differences to the resource format specification as outlined below:

  • 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

This is an example file

{
   "key": "val",
   "some_number": 123,
   // This is an integer value:
   "size:Integer" : 500
}

Limitations

  • No writeback support yet (SLING-8419)
  • This is only supported since Installer Configuration Factory 1.2.0 (SLING-7787).

Configuration Files (.config)

Configuration files ending in .config use the format of the Apache Felix ConfigAdmin implementation (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.

The format is:

file ::= (comment) (header) *
comment ::= '#' <any>
header ::= prop '=' value
prop ::= symbolic-name // 1.4.2 of OSGi Core Specification
symbolic-name ::= token { '.' token }
token ::= { [ 0..9 ] | [ a..z ] | [ A..Z ] | '_' | '-' }
value ::= [ type ] ( '[' values ']' | '(' values ')' | 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>

The quoted string format is equal to the definition from HTTP 1.1 (RFC2616), except that both '"' and '=' need to be escaped.

The 1 character type code is one of:

  • 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 and Double.longBitsToDouble 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 and Double-precision floating-point format. A more user-friendly format is not yet supported for these types (SLING-7757).

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, in case you use single-value entries or collections the deserialization will autobox primitives.

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 user-friendly (readable) values for floating points (SLING-7757)

Property Files (.cfg)

Configuration files ending in .cfg are plain property files (java.util.Property). The format is simple:

file ::= ( header | comment ) *
header ::= <header> ( ':' | '=' ) <value> ( '\<nl> <value> ) *
comment ::= '#' <any>

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 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
  • No writeback support

sling:OsgiConfig resources

Only the JCR Installer 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 in ConfigNodeConverter.

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)
  • No writeback support
  • Only array multivalue support (SLING-4183)

Project Info