Robotics Service Bus

h1. URI Schema

{{>toc}}

h2. Use Cases

URIs or URLs are used in the following situations
* Specifying how to connect to the bus (i.e. specifying a scope and transport configuration)
* Naming a thing on the bus
** A channel
** Multiple participants
** A single participant
*** A service

h2. Generic URIs

h3. Syntax and Semantic

<pre>
rsb:[PATH][#FRAGMENT]
</pre>

Components of the URL are interpreted as follows:

* @SCHEME@ -> has to be "rsb"
* @PATH@ -> A [[Glossary|scope]] which designates a one of the following things
** A channel
** A participant
*** A service (which is-a participant)
* @FRAGMENT@ ->
** Not allowed when designating a channel
** ID of a participant otherwise

This may resolve to:

* Service and/or Participant
** If there is only one of these entities this is enough for resolving it
** If multiple entities reside on this scope, a single instance can be selected using their UUID.
@rsb:/hierarchical/service/definition/further/to/participant#UniqueIDOfParticipant [UUID]@
* Nothing

These generic URIs require a global naming service.

Examples:
<pre>
rsb: -> The channel designated by the scope "/"
rsb:/ -> The channel designated by the scope "/"
rsb:/foo/bar -> The channel designated by the scope "/foo/bar"
rsb:/foo/bar#10838319-09A4-4D15-BD59-5E054CDB4403 -> The participant with UUID 10838319-09A4-4D15-BD59-5E054CDB4403
</pre>

h3. Rationale

Usually location transparency should be available.

h2. Transport-specific URLs

h3. Syntax and Semantic

<pre>
[SCHEME:][//HOST][:PORT][PATH][?QUERY][#FRAGMENT]
transport://<location.transport.specific[:PORT]>/hierarchical/service/definition/further/to/participant
</pre>
Components of the URL are interpreted as follows:

* @SCHEME@ -> transport name (e.g spread)
* @HOST@ -> Transport-specific "host" option (e.g. host that runs the daemon for Spread transport)
* @PORT@ -> Transport-specific "port" option (e.g. port on which daemon listens for Spread transport)
* @PATH@ -> A [[Glossary|scope]] which designates one of the following things
** A channel
** A participant
*** A service (which is-a participant)
* @QUERY@ -> "freestyle" transport-specific options
* @FRAGMENT@ ->
** Not allowed when designating a channel
** ID of a participant otherwise

What does this mean?

Location uniquely identifies a single participant or service, hence an ID part is not required any more.
Specific IDs can be resolved by the respective connectors and do not require a global naming.

Examples for specifying bus connections when creating participants:
<pre>
-> participate in channel with scope "/" using the default transport configuration
spread: -> participate in channel with scope "/" using the Spread transport with its default configuration
inprocess: -> participate in channel with scope "/" using the in-process transport with its default configuration
spread://localhost:5555 -> participate in channel with scope "/" via the Spread daemon running on localhost and listening on port 5555
inprocess://someotherhost -> syntactically correct, but does not make sense
spread:/foo/bar -> participate in channel with scope "/foo/bar" using the default transport configuration
spread:?maxfragmentsize=10000 -> participate in channel with scope "/" using the Spread transport with default host and port and a maximum event fragment size of 10000 bytes
spread:?maxfragmentsize=10000&tcpnodelay=yes -> likewise, but with additional tcpnodelay set to "yes" option
</pre>

h3. Rationale

* Transport-specific access is possible without naming service.
* UUIDs should ideally not be required to keep URIs simple

h2. Implementations

|_.Language |_.File(s) |
| C++ | _not yet implemented_ |
| Java | _not yet implemented_ |
| Python | _not yet implemented_ |
| Common Lisp | source:trunk/cl/cl-rsb/src/uris.lisp |