MIRA
Classes | Public Types | Public Member Functions | Protected Member Functions | List of all members
RPCManager Class Reference

This class is for internal use only. More...

#include <rpc/RPCManager.h>

Inheritance diagram for RPCManager:
Inheritance graph
[legend]

Classes

class  RemoteFinishHandler
 Handler that must be implemented by the remote module to send RPC responses to a remote server which sent a previous RPC request. More...
 
class  RemoteRequestHandler
 Handler that must be implemented by the remote module to send RPC requests to a remote server. More...
 

Public Types

typedef boost::shared_ptr< RemoteRequestHandlerRemoteRequestHandlerPtr
 
typedef boost::shared_ptr< RemoteFinishHandlerRemoteFinishHandlerPtr
 
typedef RPCServer::ServiceInfo< RPCServer::MethodInfoSetRemoteService
 

Public Member Functions

template<typename Reflector >
void reflect (Reflector &r)
 Reflect method for serialization. More...
 
template<typename Service >
void addLocalService (const std::string &name, Service &service, AbstractRPCHandlerPtr handler)
 Adds a local service. More...
 
void removeLocalService (const std::string &name)
 Remove the local service. More...
 
std::set< std::string > getLocalServices () const
 Get all registered local services. More...
 
const RPCServer::ServicegetLocalService (const std::string &name) const
 Returns a reference to the local service object with the given name. More...
 
void addRemoteService (const RemoteService &serviceInfo, RemoteRequestHandlerPtr handler, uint8 binaryFormatVersion=BinaryBufferSerializer::getSerializerFormatVersion())
 Adds a remote service. More...
 
void removeRemoteService (const std::string &name)
 Remove a remote service. More...
 
std::set< std::string > getRemoteServices () const
 Get all registered remote services. More...
 
const RemoteServicegetRemoteService (const std::string &name) const
 Returns a reference to the remote service info object with the given name. More...
 
void registerCallback (const std::string &interface, AbstractInterfaceCallbackHandlerPtr callback)
 Registers a callback handler that is called whenever a service registers the interface, which is specified as first parameter. More...
 
void unregisterCallback (const std::string &interface, AbstractInterfaceCallbackHandlerPtr callback)
 Unregisters a callback handler for a specific interface. More...
 
void unregisterCallback (AbstractInterfaceCallbackHandlerPtr callback)
 Unregisters a callback handler for all interfaces. More...
 
bool existsService (const std::string &name) const
 Returns true, if a service with the given name exists, otherwise false. More...
 
bool waitForService (const std::string &name, Duration timeout=Duration::invalid()) const
 Waits until a service with the specified name becomes available. More...
 
std::string waitForServiceInterface (const std::string &interface, Duration timeout=Duration::invalid()) const
 Waits until a service with the specified interface becomes available. More...
 
std::list< std::string > queryServicesForInterface (const std::string &interface) const
 Returns a string list with the names of all registered services (local and remote), that implement the specified interface. More...
 
bool implementsInterface (const std::string &name, const std::string &interface) const
 Returns if the given service implements a certain interface. More...
 
void handleRemoteRequest (Buffer< uint8 > buffer, RemoteFinishHandlerPtr handler=RemoteFinishHandlerPtr())
 Request to handle the given remote request, whose content is stored in the specified buffer. More...
 
void handleRemoteRequest (Buffer< uint8 > buffer, RemoteFinishHandlerPtr handler, uint8 binaryFormatVersion)
 Request to handle the given remote request, whose content is stored in the specified buffer. More...
 
void handleRemoteResponse (Buffer< uint8 > buffer)
 Handles the response on a previous remote request, that was sent through a RemoteRequestHandler. More...
 
void handleRemoteResponse (Buffer< uint8 > buffer, uint8 binaryFormatVersion)
 Handles the response on a previous remote request, that was sent through a RemoteRequestHandler. More...
 
template<typename R , typename... ARGS>
RPCFuture< R > call (const std::string &service, const std::string &method, ARGS &&... args)
 Method that is used by local C++ clients for requesting an rpc call. More...
 
RPCFuture< JSONRPCResponsecallJSON (const json::Value &jsonCall)
 Invokes a JSON RPC call. More...
 
RPCFuture< JSONRPCResponsecallJSON (const std::string &jsonCall)
 Provided for convenience. More...
 
RPCFuture< JSONRPCResponsecallJSON (const std::string &service, const std::string &method, const json::Value &params=json::Value())
 Invokes a JSON RPC call, on the specified service and method with the given params by generating a JSON RPC 2.0 conform json request. More...
 
RPCFuture< JSONRPCResponsecallJSON (const std::string &service, const std::string &method, const std::string &params)
 Provided for convenience. More...
 
RPCFuture< JSONRPCResponsecallJSON (const RPCCallDefinition &rpc)
 Provided for convenience. More...
 

Protected Member Functions

RPCFuture< JSONRPCResponsecallJSONIntern (const std::string &service, const std::string &callID, const json::Value &request)
 Internally doing a JSON RPC call. More...
 
template<typename Backend >
void handleLocalRequest (typename Backend::ContainerType buffer, const std::string &service)
 Internally used, to handle rpc requests for services that are also maintained by this local RPCManager, taking into account that these service may be handled from the same thread that sent the request. More...
 
template<typename Backend >
void handleRequest (typename Backend::ContainerType buffer, RemoteFinishHandlerPtr finishHandler, bool remote)
 Internally used, to handle incoming rpc requests. More...
 
virtual void onRPCfinished (AbstractDeferredInvoker *invoker)
 called upon finish of the RPC call, the ID of the call is passed as parameter. More...
 

Detailed Description

This class is for internal use only.

Be aware, that the interface may change significantly in future versions.

Invokation of a remote service:
                                                     remote         remote
               RPCManager                           RPCManager      service
                  |                                     |              |
  call() -----—>|                 handleRemoteRequest |              |
                  |---------------------------------—>| invoke       |
                  |                                     |----------—>|
                  | handleRemoteResponse                |<----------—|
result via future |<---------------------------------—|              |
         <-----—|                                     |              |
Invokation of a local service:
           RPCManager                          local service
              |                                      |
call() -----—>| handleLocalBinaryRequest invoke | |----------------------------------—>| result via future |<----------------------------------—| <-----—| |
 

Member Typedef Documentation

◆ RemoteRequestHandlerPtr

typedef boost::shared_ptr<RemoteRequestHandler> RemoteRequestHandlerPtr

◆ RemoteFinishHandlerPtr

typedef boost::shared_ptr<RemoteFinishHandler> RemoteFinishHandlerPtr

◆ RemoteService

Member Function Documentation

◆ reflect()

void reflect ( Reflector &  r)
inline

Reflect method for serialization.

◆ addLocalService()

void addLocalService ( const std::string &  name,
Service &  service,
AbstractRPCHandlerPtr  handler 
)
inline

Adds a local service.

The specified handler is used to process the actual RPC call. It usually is part of a dispatcher thread that belongs to an authority. Hence, the call is handled within the authorities thread that registered the service.

◆ removeLocalService()

void removeLocalService ( const std::string &  name)

Remove the local service.

◆ getLocalServices()

std::set<std::string> getLocalServices ( ) const

Get all registered local services.

◆ getLocalService()

const RPCServer::Service& getLocalService ( const std::string &  name) const
inline

Returns a reference to the local service object with the given name.

Exceptions
XInvalidParameterIf no such service exists.

◆ addRemoteService()

void addRemoteService ( const RemoteService serviceInfo,
RemoteRequestHandlerPtr  handler,
uint8  binaryFormatVersion = BinaryBufferSerializer::getSerializerFormatVersion() 
)

Adds a remote service.

The specified handler is called, whenever a method of the registered service is requested. The handler must ship the request to the remote side, where it is passed to the remote RPCManager via handleRemoteRequest(). When registering the service, its implemented interfaces need to be specified.

◆ removeRemoteService()

void removeRemoteService ( const std::string &  name)

Remove a remote service.

◆ getRemoteServices()

std::set<std::string> getRemoteServices ( ) const

Get all registered remote services.

◆ getRemoteService()

const RemoteService& getRemoteService ( const std::string &  name) const

Returns a reference to the remote service info object with the given name.

Exceptions
XInvalidParameterIf no such service exists.

◆ registerCallback()

void registerCallback ( const std::string &  interface,
AbstractInterfaceCallbackHandlerPtr  callback 
)

Registers a callback handler that is called whenever a service registers the interface, which is specified as first parameter.

When a new service is registered that implements the interface the handler is notified with the name of the service and the interface.

◆ unregisterCallback() [1/2]

void unregisterCallback ( const std::string &  interface,
AbstractInterfaceCallbackHandlerPtr  callback 
)

Unregisters a callback handler for a specific interface.

◆ unregisterCallback() [2/2]

void unregisterCallback ( AbstractInterfaceCallbackHandlerPtr  callback)

Unregisters a callback handler for all interfaces.

◆ existsService()

bool existsService ( const std::string &  name) const
inline

Returns true, if a service with the given name exists, otherwise false.

◆ waitForService()

bool waitForService ( const std::string &  name,
Duration  timeout = Duration::invalid() 
) const

Waits until a service with the specified name becomes available.

If a timeout is specified, the method times out if no such service becomes available after the given time. Returns true, if the desired services became available, or false, if the method timed out or the thread was interrupted.

◆ waitForServiceInterface()

std::string waitForServiceInterface ( const std::string &  interface,
Duration  timeout = Duration::invalid() 
) const

Waits until a service with the specified interface becomes available.

If a timeout is specified, the method times out if no such service becomes available after the given time. Returns the name of the service, if the desired services became available, or an empty string, if the method timed out or the thread was interrupted.

◆ queryServicesForInterface()

std::list<std::string> queryServicesForInterface ( const std::string &  interface) const
inline

Returns a string list with the names of all registered services (local and remote), that implement the specified interface.

◆ implementsInterface()

bool implementsInterface ( const std::string &  name,
const std::string &  interface 
) const
inline

Returns if the given service implements a certain interface.

◆ handleRemoteRequest() [1/2]

void handleRemoteRequest ( Buffer< uint8 >  buffer,
RemoteFinishHandlerPtr  handler = RemoteFinishHandlerPtr() 
)

Request to handle the given remote request, whose content is stored in the specified buffer.

The specified finish handler is called when the RPC request has finished in order to return the response to the caller.

◆ handleRemoteRequest() [2/2]

void handleRemoteRequest ( Buffer< uint8 >  buffer,
RemoteFinishHandlerPtr  handler,
uint8  binaryFormatVersion 
)

Request to handle the given remote request, whose content is stored in the specified buffer.

The specified finish handler is called when the RPC request has finished in order to return the response to the caller. The specified format version is used when encoding binary data, enabling communication with a framework still using legacy format.

◆ handleRemoteResponse() [1/2]

void handleRemoteResponse ( Buffer< uint8 >  buffer)

Handles the response on a previous remote request, that was sent through a RemoteRequestHandler.

◆ handleRemoteResponse() [2/2]

void handleRemoteResponse ( Buffer< uint8 >  buffer,
uint8  binaryFormatVersion 
)

Handles the response on a previous remote request, that was sent through a RemoteRequestHandler.

The specified format version is used when checking the response matches the original request type.

◆ call()

RPCFuture<R> call ( const std::string &  service,
const std::string &  method,
ARGS &&...  args 
)
inline

Method that is used by local C++ clients for requesting an rpc call.

It will internally call handleLocalRequest, if the service is managed by this RPCManager. Otherwise it looks for the service within the registered remote services and calls the onRPCrequested method of the service handler. If the service is completely unknown an XRPC exception is thrown.

◆ callJSON() [1/5]

RPCFuture<JSONRPCResponse> callJSON ( const json::Value jsonCall)

Invokes a JSON RPC call.

jsonCall must follow the JSON RPC 2.0 protocol. It must contain:

  • "jsonrpc" with exactly the value "2.0"
  • "id" an id that can be anything (int, string, null) but should be an unique identifier
  • "method" a service-method combination of the service to call (e.g. "/MyService.myMethod")
  • "params" Optional. Required only for methods with parameters. An array containing the parameters of the method to call (e.g. [1, "Hello World"]).
    {
    "jsonrpc" : "2.0",
    "id" : 1,
    "method" : "/ns/Service.setInt",
    "params" : [255]
    }
    Returns
    Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [2/5]

RPCFuture<JSONRPCResponse> callJSON ( const std::string &  jsonCall)

Provided for convenience.

See callJSON above. Will convert jsonCall into a json::Value and calls callJSON(const json::Value& jsonCall) internally.

Parameters
jsonCallMust contain the JSON RPC request in valid JSON syntax.
Returns
Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [3/5]

RPCFuture<JSONRPCResponse> callJSON ( const std::string &  service,
const std::string &  method,
const json::Value params = json::Value() 
)

Invokes a JSON RPC call, on the specified service and method with the given params by generating a JSON RPC 2.0 conform json request.

Call id will be automatically generated.

Parameters
[in]serviceThe service to call
[in]methodThe method on the service to call
[in]paramsThe parameters for the method to call (must be a json::Array or json null value (default))
Returns
Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [4/5]

RPCFuture<JSONRPCResponse> callJSON ( const std::string &  service,
const std::string &  method,
const std::string &  params 
)

Provided for convenience.

See callJSON above. Will convert params string into an json::Array and calls callJSON(const std::string& service, const std::string& method, const json::Value& params) internally.

Parameters
[in]serviceThe service to call
[in]methodThe method on the service to call
[in]paramsThe parameters of the method as comma separated strings (JSON notation, no enclosing [], empty string if no parameters)
Returns
Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [5/5]

RPCFuture<JSONRPCResponse> callJSON ( const RPCCallDefinition rpc)

Provided for convenience.

Extracts parameters to call callJSON(const std::string& service, const std::string& method, const std::string& params) internally.

Parameters
[in]serviceThe service to call
Returns
Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSONIntern()

RPCFuture<JSONRPCResponse> callJSONIntern ( const std::string &  service,
const std::string &  callID,
const json::Value request 
)
protected

Internally doing a JSON RPC call.

◆ handleLocalRequest()

void handleLocalRequest ( typename Backend::ContainerType  buffer,
const std::string &  service 
)
protected

Internally used, to handle rpc requests for services that are also maintained by this local RPCManager, taking into account that these service may be handled from the same thread that sent the request.

In this case the method is called immediately to avoid deadlocks. For all other local requests the handleRequest method below is called. The content of the request (method name, parameters, etc) is contained in the specified buffer.

◆ handleRequest()

void handleRequest ( typename Backend::ContainerType  buffer,
RemoteFinishHandlerPtr  finishHandler,
bool  remote 
)
protected

Internally used, to handle incoming rpc requests.

The specified buffer contains all necessary data for the RPC call (service name, method name, parameters, etc). Moreover, a finishHandler must be specified whose onRPCfinished method is called, when the RPC request was processed. The last parameter specifies whether the service request is coming from a remote side. This flag will be stored within the AbstractRequestContext that is created internally.

◆ onRPCfinished()

virtual void onRPCfinished ( AbstractDeferredInvoker invoker)
protectedvirtual

called upon finish of the RPC call, the ID of the call is passed as parameter.

Implements DeferredInvokerFinishHandler.


The documentation for this class was generated from the following file: