Robotics Service Bus

h1. Request/Reply Communication

h2. Introduction

The Request/Reply communication pattern is provided by pair of classes called @Server@ and @RemoteServer@ or similar:
* @Server@: This class is instantiated in the service-providing RSB process. Provided methods are registered by name and signature.
* @RemoteServer@: This class is instantiated in the service-using RSB process. Each @RemoteServer@ instance has one or more corresponding @Server@ instance, potentially in different processes, that provide the service in question. Client code calls methods on the @RemoteServer@ instance which cause methods of a @Service@ instance to be called and perform the requested task.

h2. Mapping to Event Concepts

h3. @Server@ Representation

Conceptually, the @Server@ instance is the root of the following object graph:

* @Server@
** Scope
** Method
*** Name
*** Request Listener
Scope: @/SERVER-SCOPE/request/METHOD-NAME/@
*** Reply Informer
Scope: @/SERVER-SCOPE/reply/METHOD-NAME/@
** more methods

h3. @RemoteServer@ Representation

Conceptually, the @RemoteServer@ instance is the root of the following object graph:

* @RemoteServer@
** Scope
** Method
*** Name
*** Request Informer
Scope: @/SERVER-SCOPE/request/METHOD-NAME/@
*** Reply Listener
Scope: @/SERVER-SCOPE/reply/METHOD-NAME/@
*** A collection of in-progress method calls
** more methods

h3. Communication

# Client code calls a method on a @RemoteServer@ instance
# The request informer of the method publishes an @Event@ containing
#* The argument of the method call as [[Events|payload]]
#* -A [[Events#Meta Data|user-info]] item with key @ServerRequestId@ and the string representation of a UUID as value-
#* The value @"REQUEST"@ in its [[Events|method field]]
# A record containing the -above UUID- event id is created for the method call
# The call blocks until a reply event is received (see below)
# The request listener of the method in a corresponding @Server@ instance receives the @Event@
# The event is dispatched to a handler for processing
# After processing, the reply informer of the method in the @Server@ sends an @Event@ containing
#* The result of the processing as payload, if the processing succeeded without errors
#* The textual description of the error as payload, if an error occurred
#* A user-info item with key @rsb:error?@ and an arbitrary value, if an error occurred
#* -A user-info item with key @ServerRequestId@ and the value received in the user-info item of the same key in the request @Event@-
A user-info item with key @rsb:reply@ and the id of the request event as value
#* The value @"REPLY"@ in its [[Events|method field]]
# The reply listener of the method in the @RemoteServer@ receives the reply @Event@
# The call record is located using the value of the user-info item with key -@ServerRequestId@- @rsb:reply@
# The blocking call is notified and
#* returns the payload of the reply event, if a user-item with key @rsb:error?@ is not present in the @Event@
#* signals an error, if a user-item with key @rsb:error?@ is present in the @Event@

h2. Implementations

|_.Language |_.File(s) |
| C++ | source:trunk/cpp/core/src/rsb/patterns |
| Java | source:trunk/java/core/src/rsb/patterns |
| Python | source:"trunk/python/core/rsb/patterns/__init__.py" |
| Common Lisp | source:trunk/cl/cl-rsb/src/patterns |