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, LANGUAGE refers to the implementation language):

<pre>

+ qualityofservice

+-- reliability                     { UNRELIABLE, RELIABLE }

+-- ordering                        { UNORDERED, ORDERED }

+ errorhandling

+-- onhandlererror                  { LOG, PRINT, EXIT }

+ plugins

+-- LANGUAGE

+---- path                          list of strings

+---- load                          list of strings

+ transport

+-- NAME

+---- enabled                       bool

+---- TRANSPORT_SPECIFIC_OPTION     ?

+---- converter

+------ LANGUAGE

+-------- WIRE-SCHEMA               string

+-- spread

+---- host                          string

+---- port                          uint

+---- maxfragmentsize               uint

+---- tcpnodelay                    boolean

+-- 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 = 5301

</pre>

* Contents of @(pwd)/rsb.conf@

<pre>

[transport.spread]

host = localhost

</pre>

* Environment Variables

  @RSB_TRANSPORT_SPREAD_PORT='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":http://en.wikipedia.org/wiki/INI_file or "desktop-files":http://standards.freedesktop.org/desktop-entry-spec/latest/:

* 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

enabled = 1                          # this is the default

[spread.converter.cpp]

image = IplImage                     # wire-schema = data-type

[transport.inprocess]

foo     = barbar

factor  = 1.5

enabled = 1

[plugins.cpp]

path = /vol/vampire/lib:/vol/cor/lib

load = 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

Examples:

* @RSB_PLUGINS_CPP_LOAD      <-> plugins.cpp.load@

* @RSB_TRANSPORT_SPREAD_PORT <-> transport.spread.port@

h3. Commandline Options

_This section is a proposal._

Commandline options are processed according to the following rules:

# Language-specific name components (such as @plugins.cpp.load@) are dropped

# Components are joined with/strings are split at @-@ characters

Examples:

* @--plugins-load          <-> plugins.cpp.load@

* @--transport-spread-port <-> transport.spread.port@