Robotics Service Bus

h1. Configuration

The configuration mechanism is based on the following principles:
* We cannot (and do not want) to handle configuration of individual participants. The configuration mechanism is intended to provide process-wide defaults. Participants that require individual configurations have to be configured programmatically.
* The configuration mechanism works identically across implementation languages
* Configuration options are obtained from multiple configuration sources:
** Configuration files
** Environment variables
** _Commandline options (planned)_
* Configuration options are organized in a tree of name-value pairs

h2. Syntax and Semantics

Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like @[transport.spread]@ are concatenated with names of contained options like @port@ to obtain @transport.spread.port@. For environment variables, the name @RSB_TRANSPORT_SPREAD_PORT@ maps to @transport.spread.port@.

Currently the following option tree is defined (uppercase option name components are placeholders):
<pre>
+ qualityofservice
+-- reliability { UNRELIABLE, RELIABLE }
+-- ordering { UNORDERED, ORDERED }
+ errorhandling
+-- onhandlererror { LOG, PRINT, EXIT }
+ transport
+-- NAME
+---- enabled bool
+---- TRANSPORT_SPECIFIC_OPTION ?
+---- converter
+------ WIRE-SCHEMA string
+-- spread
+---- host string
+---- port uint
+-- inprocess
</pre>

h2. Processing Order

Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:
# Config file @${HOME}/.config/rsb.conf@
# Config file @$(pwd)/rsb.conf@
# Environment variables

h3. Example and test case

Consider the following situation:
* Contents of @${HOME}/.config/rsb.conf@:
<pre>
[transport.spread]
host = azurit
port = <uint>5301
</pre>
* Contents of @(pwd)/rsb.conf@
<pre>
[transport.spread]
host = localhost
</pre>
* Environment Variables
@RSB_TRANSPORT_SPREAD_PORT='<unit>4444'@

This would result in the following effective option values:
* @transport.spread.host = localhost@
* @transport.spread.port = 4444@

h2. Sources

The following sections briefly explains the currently defined configuration sources.

h3. Configuration Files

Configuration files use the following syntax, which is similar to INI-files or desktop-files:
* Comments are initiated by the @#@ character and extend to the end of the current line
* After removing comments, all lines have to be of one of the following forms:
** empty
** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons
** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters

Here is an example:
<pre>
[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED

[errorhandling]
onhandlererror = LOG

[transport.spread]
host = localhost
port = 4803 &lt;uint&gt;4803
enabled = 1 &lt;bool&gt;1 # this is the default

[spread.converter.c++]
image = IplImage # wireSchema = dataType

[transport.inprocess]
foo = barbar
factor = 1.5 &lt;double&gt;1.5
enabled = 1 &lt;bool&gt;1

[plugins.c++]
path = /vol/vampire/lib:/vol/cor/lib
libraries = rsbspread:rsbvampire # no filetype suffix
</pre>

h3. Environment Variables

Environment variables are processed according to the following rules
# Variables whose names start with @RSB_@ are processed
# The @RSB_@ prefix is stripped form the name
# To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters

Example:
@RSB_TRANSPORT_SPREAD_PORT -> transport.spread.port@