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 @isException@ 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 @replyTo@ 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@- @replyTo@

# The blocking call is notified and

#* returns the payload of the reply event, if a user-item with key @isException@ is not present in the @Event@

#* signals an error, if a user-item with key @isException@ 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                 |