ProtocolBufferConverter » History » Version 6
Version 5 (J. Moringen, 06/27/2011 01:57 PM) → Version 6/19 (S. Wrede, 08/05/2011 05:44 PM)
h1. ProtocolBufferConverter
*Warning: this tutorial explains how to use RSB's converter mechanism for domain data which is represented in Google protocol buffer messages. However, Google's protocol buffer tutorial advises against using protocol buffer messages directly as domain classes (see "Protocol Buffers and O-O Design" in "the protocol buffer tutorial":http://code.google.com/apis/protocolbuffers/docs/cpptutorial.html).*
h2. Introduction
Google protocol buffers are an approach for IDL-driven generation of data-holder classes and associated serialization and deserialization code. In RSB, arbitrary protocol buffer messages can be processed using the converter mechanism. Depending on the programming language, the particular protocol buffer messages, that will be used, may have to be registered in the converter system in some way. However, after the registration, serialization and deserialization works transparently without further implementation or configuration work.
Advantages of this approach over manual converter writing (as described [[Writing_Converters|here]]) include:
* IDL-defined message format (as opposed to an informal "definition" through a particular implementation)
* Proper handling of machine Endianess
* Proper handling of machine word sizes
* Some degree of data validation
* Introspection support
* Generated data-holder classes and (de)serializers
** Available in multiple programming languages without additional effort
** Inter-language consistency of data-holder classes and serialized representations
This page describes how to use the @ProtocolBufferConverter@ class with user-defined protocol buffer messages. The running example of a fictional @SimpleImage@ data-type (introduced [[Writing_Converters|here]]) is reused.
h2. Message Definition
A @SimpleImage@ consists of
* a width (a non-negative integer)
* a height (a non-negative integer)
* image data (an array of bytes)
This structure is reflected in the protocol buffer message definition:
source:trunk/cpp/core/examples/protobuf_converter/SimpleImage.proto
h2. Code (C++)
As explained above, no code has to written for the data-holder class or its (de)serialization. However, it is necessary to register a template instantiation of the @ProtocolBufferConverter@ class in the converter registry. The @sender@ and @receiver@ program programs below demonstrate how to do this and additionally send and receive @SimpleImage@ messages respectively. respectively:
h3. C++
source:trunk/cpp/core/examples/protobuf_converter/sender.cpp
source:trunk/cpp/core/examples/protobuf_converter/receiver.cpp
h3. Java
Java support for Protocol Buffer encoding of user-level datatypes is available since RSB version 0.4.
source:trunk/java/core/examples/tutorial/protobuf/InformerExample.java
source:trunk/java/core/examples/tutorial/protobuf/ListenerExample.java
*Warning: this tutorial explains how to use RSB's converter mechanism for domain data which is represented in Google protocol buffer messages. However, Google's protocol buffer tutorial advises against using protocol buffer messages directly as domain classes (see "Protocol Buffers and O-O Design" in "the protocol buffer tutorial":http://code.google.com/apis/protocolbuffers/docs/cpptutorial.html).*
h2. Introduction
Google protocol buffers are an approach for IDL-driven generation of data-holder classes and associated serialization and deserialization code. In RSB, arbitrary protocol buffer messages can be processed using the converter mechanism. Depending on the programming language, the particular protocol buffer messages, that will be used, may have to be registered in the converter system in some way. However, after the registration, serialization and deserialization works transparently without further implementation or configuration work.
Advantages of this approach over manual converter writing (as described [[Writing_Converters|here]]) include:
* IDL-defined message format (as opposed to an informal "definition" through a particular implementation)
* Proper handling of machine Endianess
* Proper handling of machine word sizes
* Some degree of data validation
* Introspection support
* Generated data-holder classes and (de)serializers
** Available in multiple programming languages without additional effort
** Inter-language consistency of data-holder classes and serialized representations
This page describes how to use the @ProtocolBufferConverter@ class with user-defined protocol buffer messages. The running example of a fictional @SimpleImage@ data-type (introduced [[Writing_Converters|here]]) is reused.
h2. Message Definition
A @SimpleImage@ consists of
* a width (a non-negative integer)
* a height (a non-negative integer)
* image data (an array of bytes)
This structure is reflected in the protocol buffer message definition:
source:trunk/cpp/core/examples/protobuf_converter/SimpleImage.proto
h2. Code (C++)
As explained above, no code has to written for the data-holder class or its (de)serialization. However, it is necessary to register a template instantiation of the @ProtocolBufferConverter@ class in the converter registry. The @sender@ and @receiver@ program programs below demonstrate how to do this and additionally send and receive @SimpleImage@ messages respectively. respectively:
h3. C++
source:trunk/cpp/core/examples/protobuf_converter/sender.cpp
source:trunk/cpp/core/examples/protobuf_converter/receiver.cpp
h3. Java
Java support for Protocol Buffer encoding of user-level datatypes is available since RSB version 0.4.
source:trunk/java/core/examples/tutorial/protobuf/InformerExample.java
source:trunk/java/core/examples/tutorial/protobuf/ListenerExample.java