Writing Converters » History » Version 3
Version 2 (J. Moringen, 06/22/2011 11:17 PM) → Version 3/10 (J. Moringen, 06/22/2011 11:47 PM)
h1. Writing Converters
h2. Introduction
In RSB, converters are used to serialize and deserialize programming-language objects for transportation (e.g. over a network connection). RSB comes with converters for the fundamental types listed [[Types|here]]. However, in many use-cases it is necessary to use additional converters for domain-specific types and/or serialization mechanisms.
This page describes how to add such converters to RSB using the running example of a converter for a fictional @SimpleImage@ [[Glossary|data-type]].
*Warning: this tutorial has been written with simplicity in mind and should not be used as a blueprint for production code. In particular:*
* It does not handle machine Endianess properly
* It does not handle machine word sizes properly
* It leaks memory
* It does not validate any data
h2. Preparation
In order to implement a new converter, the following information is required:
* To/from which [[Glossary|wire-type]] will the converter serialize/deserialize? In our example, the wire-type is an array of octets which maps to @std::string@ in C++.
* Which [[Glossary|data-type]] or (data-types) will be handled by the converter? The struct @SimpleImage@ in our example.
* What is the [[Glossary|wire-schema]] of the converter? In our example, we use the following ad-hoc wire-schema:
** Name: @simple-image@
** Binary layout: one integer encoding the image width, one integer encoding the image height, width x height bytes for the image data
h2. Implementation: C++
h3. @SimpleImage@ Domain type
The domain data-type is defined in: source:trunk/cpp/core/example/custom_converter/SimpleImage.h
source:trunk/cpp/core/examples/custom_converter/SimpleImage.h
h3. @SimpleImageConverter@ Class
For the actual converter implementation, four things are needed:
# The wire-type has to be passed to the @Converter@ interface as a template parameter
# The wire-schema and data-type name have to be passed to the @Converter@ constructor
# The @serialize@ method has to be implemented
# The @deserialize@ method has to be implemented
A naive and incomplete implementation can be found here:
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.h source:trunk/cpp/core/example/custom_converter/SimpleImageConverter.h
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.cpp
h3. Using the Converter
A simple program that demonstrates the use of our @SimpleImageconverter@ can be found in
source:trunk/cpp/core/examples/custom_converter/sender.cpp
A similar program in which the registration of the converter is missing can be found in
source:trunk/cpp/core/examples/custom_converter/senderNoConverter.cpp
This second program servers the purpose of familiarizing you with the "missing-converter" error message, that you will encounter sooner or later ;) source:trunk/cpp/core/example/custom_converter/SimpleImageConverter.cpp
h2. Introduction
In RSB, converters are used to serialize and deserialize programming-language objects for transportation (e.g. over a network connection). RSB comes with converters for the fundamental types listed [[Types|here]]. However, in many use-cases it is necessary to use additional converters for domain-specific types and/or serialization mechanisms.
This page describes how to add such converters to RSB using the running example of a converter for a fictional @SimpleImage@ [[Glossary|data-type]].
*Warning: this tutorial has been written with simplicity in mind and should not be used as a blueprint for production code. In particular:*
* It does not handle machine Endianess properly
* It does not handle machine word sizes properly
* It leaks memory
* It does not validate any data
h2. Preparation
In order to implement a new converter, the following information is required:
* To/from which [[Glossary|wire-type]] will the converter serialize/deserialize? In our example, the wire-type is an array of octets which maps to @std::string@ in C++.
* Which [[Glossary|data-type]] or (data-types) will be handled by the converter? The struct @SimpleImage@ in our example.
* What is the [[Glossary|wire-schema]] of the converter? In our example, we use the following ad-hoc wire-schema:
** Name: @simple-image@
** Binary layout: one integer encoding the image width, one integer encoding the image height, width x height bytes for the image data
h2. Implementation: C++
h3. @SimpleImage@ Domain type
The domain data-type is defined in: source:trunk/cpp/core/example/custom_converter/SimpleImage.h
source:trunk/cpp/core/examples/custom_converter/SimpleImage.h
h3. @SimpleImageConverter@ Class
For the actual converter implementation, four things are needed:
# The wire-type has to be passed to the @Converter@ interface as a template parameter
# The wire-schema and data-type name have to be passed to the @Converter@ constructor
# The @serialize@ method has to be implemented
# The @deserialize@ method has to be implemented
A naive and incomplete implementation can be found here:
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.h source:trunk/cpp/core/example/custom_converter/SimpleImageConverter.h
source:trunk/cpp/core/examples/custom_converter/SimpleImageConverter.cpp
h3. Using the Converter
A simple program that demonstrates the use of our @SimpleImageconverter@ can be found in
source:trunk/cpp/core/examples/custom_converter/sender.cpp
A similar program in which the registration of the converter is missing can be found in
source:trunk/cpp/core/examples/custom_converter/senderNoConverter.cpp
This second program servers the purpose of familiarizing you with the "missing-converter" error message, that you will encounter sooner or later ;) source:trunk/cpp/core/example/custom_converter/SimpleImageConverter.cpp