1.2.2. System Handle

class eprosima::is::SystemHandle

It is the base interface class for all middleware systems.

All middleware systems that want to interact with Integration Service must implement, at least, this interface.

Depending on the type of middleware, it should also implement the derived classes, using multiple virtual inheritance:

A SystemHandle implementing the four interfaces described above is called a FullSystem, and it is usually the base class used for implementing a middleware plugin for the Integration Service.

Subclassed by eprosima::is::ServiceClientSystem, eprosima::is::ServiceProviderSystem, eprosima::is::TopicPublisherSystem, eprosima::is::TopicSubscriberSystem

Public Functions

SystemHandle() = default

Default constructor.

SystemHandle(const SystemHandle&) = delete

SystemHandle shall not be copy constructible.

SystemHandle &operator=(const SystemHandle&) = delete

SystemHandle shall not be copy assignable.

SystemHandle(SystemHandle&&) = delete

SystemHandle shall not be move constructible.

SystemHandle &operator=(SystemHandle&&) = delete

SystemHandle shall not be move assignable.

~SystemHandle() = default

Destructor.

bool configure(const core::RequiredTypes &types, const YAML::Node &configuration, TypeRegistry &type_registry) = 0

Configures the Integration Service handle for this middleware’s system.

Return

true if the configuration process was successful, false otherwise.

Parameters

  • [in] types: The set of types (messages and services) that this middleware needs to support. The SystemHandle must register this type into the is::TypeRegistry, using for that the storage class is::internal::SystemHandleInfo.

  • [in] configuration: The configuration specific for this SystemHandle, as described in the user-provided YAML input file. See the specific SystemHandle implementation documentation for a list of accepted configuration parameters for each middleware.

  • [in] type_registry: The set of type definitions that this middleware is able to support.

bool okay() const = 0

Method that allows to check if a SystemHandle is correctly working.

Return

true if the SystemHandle is under normal behavior, false otherwise.

operator bool() const

bool() operator overload. Implicit conversion, same as okay().

Return

true if the SystemHandle is under normal behavior, false otherwise.

bool spin_once() = 0

Tell the SystemHandle to spin once, e.g. read through its subscriptions.

Return

true if the SystemHandle is still working; false otherwise.

class eprosima::is::TopicSubscriberSystem : public virtual eprosima::is::SystemHandle

Extends the SystemHandle class with subscription capabilities.

Subclassed by eprosima::is::TopicSystem

Public Types

using SubscriptionCallback = std::function<void(const xtypes::DynamicData &message, void *filter_handle)>

Signature of the callback that gets triggered when a subscriber receives some data.

Public Functions

TopicSubscriberSystem() = default

Constructor.

~TopicSubscriberSystem() = default

Destructor.

bool subscribe(const std::string &topic_name, const xtypes::DynamicType &message_type, SubscriptionCallback *callback, const YAML::Node &configuration) = 0

Has this SystemHandle instance subscribed to a topic.

Return

true if subscription was successfully established, false otherwise.

Parameters

  • [in] topic_name: Name of the topic to get subscribed to.

  • [in] message_type: Message type that this topic should expect to receive.

  • [in] callback: The callback which should be triggered when a message comes in.

  • [in] configuration: A YAML node containing any middleware-specific configuration information for this subscription. This may be an empty node.

bool is_internal_message(void *filter_handle) = 0

Check if a certain message in a subscriber comes from a middleware publisher created by Integration Service in the same SystemHandle instance.

This method must be implemented by each SystemHandle according to its middleware and protocol intricacies and particularities. Some protocols might not need this at all. This method is called, during the SubscriptionCallback function, to avoid sending messages indefinitely, thus creating an infinite loop.

Parameters

  • [in] filter_handle: Opaque pointer to entity containing the information used to perform the filtering; this is usually meta-information regarding the just received message instance in the middleware’s subscriber side.

class eprosima::is::TopicPublisher

This is the abstract interface for objects that can act as publisher proxies.

These objects will be created by Integration Service as bridges between the common data representation (eprosima::xtypes) and the user subscription applications, when data are to be published from one middleware to another.

These objects should be generated by the TopicPublisherSystem advertise() method.

Public Functions

TopicPublisher() = default

Constructor.

~TopicPublisher() = default

Destructor.

bool publish(const xtypes::DynamicData &message) = 0

Publishes to a topic.

Return

true if the data was correctly published, false otherwise.

Parameters

  • [in] message: DynamicData that is being published.

class eprosima::is::TopicPublisherSystem : public virtual eprosima::is::SystemHandle

This class extends the SystemHandle class by providing it with publishing capabilities.

Subclassed by eprosima::is::TopicSystem

Public Functions

TopicPublisherSystem() = default

Constructor.

~TopicPublisherSystem() = default

Destructor.

std::shared_ptr<TopicPublisher> advertise(const std::string &topic_name, const xtypes::DynamicType &message_type, const YAML::Node &configuration) = 0

Advertises the ability to publish to a topic.

Return

true if the advertisement was successful, false otherwise.

Parameters

  • [in] topic_name: Name of the topic to advertise.

  • [in] message_type: Message type that this entity will publish.

  • [in] configuration: A YAML node containing any middleware-specific configuration information for this publisher. This may be an empty node.

class eprosima::is::TopicSystem : public virtual eprosima::is::TopicPublisherSystem, public virtual eprosima::is::TopicSubscriberSystem

It is the conjunction of TopicPublisherSystem and TopicSubscriberSystem. It allows to create a middleware library for Integration Service fully compatible with the publish/subscribe paradigm.

Subclassed by eprosima::is::FullSystem

Public Functions

TopicSystem() = default

Constructor.

~TopicSystem() = default

Destructor.

class eprosima::is::ServiceClient

This is the abstract interface for objects that can act as client proxies.

This class is different from ServiceClientSystem, because ServiceClientSystem is the interface for SystemHandle libraries that are able to support client proxies, whereas ServiceClient is the interface for the client proxy objects themselves.

This class, when overridden by the specific middleware implementation, will typically contain a middleware::server object, so that receive_response can fetch the response sent by the user server application (usually, implemented using a different middleware) and pass this response to the target user client application, which will receive the final response by means of the internal server created by this ServiceClient.

Public Functions

ServiceClient() = default

Constructor.

~ServiceClient() = default

Destructor.

void receive_response(std::shared_ptr<void> call_handle, const xtypes::DynamicData &response) = 0

Receives the response of a service request.

Attention

Services are assumed to all be asynchronous (non-blocking), so this function may be called by multiple threads at once. developers implementing a ServiceClient derived class must make sure that they can handle multiple simultaneous calls to this function.

Parameters

  • [in] call_handle: The handle that was given to the call by this ServiceClient. The usage of the handle is determined by the ServiceClient implementation. Typically, receive_response will cast this handle into a useful object type that contains information on where to send the service response message.

  • [in] response: The message that represents the response from the service.

class eprosima::is::ServiceClientSystem : public virtual eprosima::is::SystemHandle

This class extends the SystemHandle class with service client handling capabilities.

Subclassed by eprosima::is::ServiceSystem

Public Types

using RequestCallback = std::function<void(const xtypes::DynamicData &request, ServiceClient &client, std::shared_ptr<void> call_handle)>

Signature of the callback that gets triggered when a client has made a request.

Public Functions

ServiceClientSystem() = default

Constructor.

~ServiceClientSystem() = default

Destructor.

bool create_client_proxy(const std::string &service_name, const xtypes::DynamicType &service_type, RequestCallback *callback, const YAML::Node &configuration)

Create a proxy for a client application.

Return

true if a client proxy could be created, false otherwise.

Parameters

  • [in] service_name: Name of the service this client proxy shall listen to.

  • [in] service_type: Service request and reply type to expect.

  • [in] callback: The callback that should be used when a request comes in from the middleware.

  • [in] configuration: A YAML node containing any middleware-specific configuration information for this service client. This may be an empty node.

bool create_client_proxy(const std::string &service_name, const xtypes::DynamicType &request_type, const xtypes::DynamicType &reply_type, RequestCallback *callback, const YAML::Node &configuration)

Create a proxy for a client application.

Return

true if a client proxy could be created, false otherwise.

Parameters

  • [in] service_name: Name of the service for this client to listen to.

  • [in] request_type: Type of service request to expect.

  • [in] reply_type: Type of service reply to expect.

  • [in] callback: The callback that should be used when a request comes in from the middleware.

  • [in] configuration: A YAML node containing any middleware-specific configuration information for this service client. This may be an empty node.

class eprosima::is::ServiceProvider

This is the abstract interface for objects that can act as service server proxies.

This class is different from ServiceProviderSystem, because ServiceProviderSystem is the interface for SystemHandle libraries that are able to support service server proxies, whereas ServiceProvider is the interface for the service server proxy objects themselves.

This class, when overridden by the specific middleware implementation, will typically contain a middleware::client object that will actually send the request to the user server application. After processing the request by means of the call_service method, thanks to the associated ServiceClient entity, receive_response will be called, to pass the response to the user client application (typically, implemented using a different middleware, which justifies the use of the Integration Service to interconnect them).

Public Functions

ServiceProvider() = default

Constructor.

~ServiceProvider() = default

Destructor.

void call_service(const xtypes::DynamicData &request, ServiceClient &client, std::shared_ptr<void> call_handle) = 0

Call a service.

Attention

It is important that this function:

  1. Is non-blocking.

  2. Calls client.receive_response() when the service finishes.

Parameters

  • [in] request: Request message for the service.

  • [inout] client: The proxy for the client that is making the request.

  • [in] call_handle: A handle for the call. The usage of this handle is determined by the ServiceClient implementation. The ServiceProvider should not attempt to cast or modify it in any way; it should only be passed back to the ServiceClient later on, when receive_response() is called.

class eprosima::is::ServiceProviderSystem : public virtual eprosima::is::SystemHandle

This class extends the SystemHandle class with service server handling capabilities.

Subclassed by eprosima::is::ServiceSystem

Public Functions

ServiceProviderSystem() = default

Constructor.

~ServiceProviderSystem() = default

Destructor.

std::shared_ptr<ServiceProvider> create_service_proxy(const std::string &service_name, const xtypes::DynamicType &service_type, const YAML::Node &configuration)

Create a proxy for a service server.

Return

true if the middleware’s SystemHandle can offer this service, false otherwise.

Parameters

  • [in] service_name: Name of the service to offer.

  • [in] service_type: Type of service being offered.

  • [in] configuration: A YAML node containing any middleware-specific configuration information for this service provider. This may be an empty node.

std::shared_ptr<ServiceProvider> create_service_proxy(const std::string &service_name, const xtypes::DynamicType &request_type, const xtypes::DynamicType &reply_type, const YAML::Node &configuration)

Creates a proxy for a service server.

Return

true if the middleware’s SystemHandle can offer this service, false otherwise.

Parameters

  • [in] service_name: Name of the service to offer.

  • [in] request_type: Type of service request being offered.

  • [in] reply_type: Type of service reply being offered.

  • [in] configuration: A YAML node containing any middleware-specific configuration information for this service provider. This may be an empty node.

class eprosima::is::ServiceSystem : public virtual eprosima::is::ServiceClientSystem, public virtual eprosima::is::ServiceProviderSystem

It is the conjunction of ServiceProviderSystem and ServiceClientSystem. Allows to create a middleware library for Integration Service fully compatible with the request/reply paradigm.

Subclassed by eprosima::is::FullSystem

Public Functions

ServiceSystem() = default

Constructor.

~ServiceSystem() = default

Destructor.

class eprosima::is::FullSystem : public virtual eprosima::is::TopicSystem, public virtual eprosima::is::ServiceSystem

It is the conjunction of ServiceSystem and TopicSystem. It allows to define a whole middleware, in terms of both publish/subscribe and request/reply paradigms.

Usually, most middleware plugins for Integration Service will inherit from this class.

Public Functions

FullSystem() = default

Constructor.

~FullSystem() = default

Destructor.

struct eprosima::is::core::RequiredTypes

Contains the set of topics and services types required in order to successfully create an Integration Service instance, based on the configuration provided.

Public Members

std::set<std::string> messages

Set of topic types stated within the configuration file.

std::set<std::string> services

Set of service types stated within the configuration file.

using eprosima::is::TypeRegistry = std::map<std::string, xtypes::DynamicType::Ptr>

Map used to store the DynamicType name mapped to its representation.

IS_REGISTER_SYSTEM(middleware_name_str, SystemType)

Call this macro in a .cpp file of your middleware’s plugin library, so that the Integration Service can find your eprosima::is::SystemHandle implementation when your plugin library gets dynamically loaded. For example:

IS_REGISTER_SYSTEM("my_middleware", my::middleware::SystemHandle)

The first argument should be a string representing the name of the middleware. This should match the name in the system: dictionary of your Integration Service configuration file. Each middleware should have a unique name.

The second argument should be the literal type (not a string) of the class that implements eprosima::is::SystemHandle in your plugin library.