Sending and Receiving Custom Data Types

See also

Writing Converters Writing new converters instead of registering existing ones.

Converters Detailed description of converters and methods to configure the selection of appropriate instances.

In principle, projects using RSB can exchange data of arbitrary types. However, in order to send and receive custom data types, RSB has to know how to serialize and deserialize data of these types. This task is performed by converters, which transform domain-specific data to a specific wire type. The wire type is the language-specific data holder (typically a string type) passed to the underlying transport mechanism.

Each converter encodes the payload using a specific wire schema that describes the data encoding scheme on the wire. In order to successfully receive events with a specific wire schema, appropriate converters need to be available at runtime. While there exist converters for some basic data types, you need to register the converters for your own domain-specific data types by yourself.

Registering Converters

To add a converter to the repository, the converter object has to be created and the repository object has to be obtained. The following example demonstrates this.

Important

Converters have to be registered before participants are created. Otherwise, the participants can still be created, but will not use the desired converters. In case a converter for a wire schema is missing, sending operations will throw an exception and receiving operations will fail in the background thread depending on the Configuration entry errorhandling.onhandlererror.

The function rsb.converter.registerGlobalConverter() is used to register new converters (line 26).

import logging
import sys

import rsb
import rsb.converter

# Load the generated protocol buffer data holder class from the
# current directory. This would look different if the protocol buffer
# code generation was properly integrated in a build process.
#
# See the comment in SimpleImage.proto for how to manually perform the
# code generation.
sys.path.append('.')
from SimpleImage_pb2 import SimpleImage  # noqa: I100 correct path required

if __name__ == '__main__':
    # Pacify logger.
    logging.basicConfig()

    # Register a protocol buffer converter for SimpleImage:
    # The generated data holder class is
    #   SimepleImage_pb2.SimpleImage
    # The protocol buffer message is called
    #   .tutorial.protobuf_converter.SimpleImage
    converter = rsb.converter.ProtocolBufferConverter(
        message_class=SimpleImage)
    rsb.converter.register_global_converter(converter)

    print("Registered converter {}".format(converter))
    print("Registered converters:\n{}".format(
        rsb.converter.get_global_converter_map(bytes)))

Note

In previous versions of RSB the default participant configuration had to be recreated after adding a converter by calling rsb.setDefaultParticipantConfig(rsb.ParticipantConfig.fromDefaultSources()). This is not required anymore starting with RSB 0.9. Additionally, it is explicitly discouraged now since multiple libraries using this strategy might conflict by erasing converters previously registered by other libraries. Please remove these lines from your existing code.

Download this example

After creating a converter object (lines 19 and 20), the template function rsb::converter::converterRepository() is used to obtain the converter repository (line 21) and register the converter object via the rsb::converter::Repository::registerConverter method (line 21). The rsb::Factory is obtained only after the converter has been registered, so it can pick up the changed converter set (line 25).

#include <rsb/Factory.h>

#include <rsb/converter/Repository.h>
#include <rsb/converter/ProtocolBufferConverter.h>

// See ../CMakeLists.txt for the generation of this file.
// The generated file can be found in ${BUILD_DIR}/protobuf_converter
#include <protobuf_converter/SimpleImage.pb.h>

using namespace rsb;

// The generated protocol buffer class is in this namespace.
using namespace tutorial::protobuf_converter;

int main() {
    // Register a specific template instantiation of the
    // ProtocolBufferConverter for our SimpleImage protocol buffer
    // message.
    boost::shared_ptr< rsb::converter::ProtocolBufferConverter<SimpleImage> >
        converter(new rsb::converter::ProtocolBufferConverter<SimpleImage>());
    rsb::converter::converterRepository<std::string>()->registerConverter(converter);

    // After the converter has been registered, the default
    // configuration used by the Factory includes the converter.
    Factory& factory = getFactory();

    return EXIT_SUCCESS;
}

Download this example

After creating the converter object (lines 14 and 15), it is globally registered using the rsb.converter.ConverterRepository.addConverter method (line 19). The repository is obtained by calling rsb.converter.DefaultConverterRepository.getDefaultConverterRepository (line 18).

import rsb.Factory;
import rsb.converter.DefaultConverterRepository;
import rsb.converter.ProtocolBufferConverter;
import rsb.examples.protobuf.ImageMessage.SimpleImage;

public class RegistrationExample {

    public static void main(final String[] args) throws Throwable {

        // Instantiate generic ProtocolBufferConverter with
        // SimpleImage exemplar.
        final ProtocolBufferConverter<SimpleImage> converter = new ProtocolBufferConverter<SimpleImage>(
                SimpleImage.getDefaultInstance());

        // Register converter for the SimpleImage type.
        DefaultConverterRepository.getDefaultConverterRepository()
                .addConverter(converter);

        // The factory now uses the modified set of converters.
        @SuppressWarnings("unused")
        final Factory factory = Factory.getInstance();

    }

}

Download this example

Note

In Common Lisp, the mechanism is quite different; will be documented later.