Serialization Tutorial

First Steps

In this section we introduce a simple example to show how the serialization works in practice.

Basic serialization

We will introduce Serialization using the PingPong sample provided by Ariba. You will find the following code in PingPongMessage.h:

#ifndef PINGPONGMESSAGES_H_
#define PINGPONGMESSAGES_H_

#include <string>
#include "ariba/ariba.h"

using namespace ariba;
using std::string;

namespace ariba {
namespace application {
namespace pingpong {

using_serialization;

class PingPongMessage : public Message {
        VSERIALIZEABLE;
public:
        PingPongMessage();
        PingPongMessage( uint8_t _id, string name = string("<ping>") );
        virtual ~PingPongMessage();

        string info();
        uint8_t getid();

        inline string getName() const {
                return name;
        }
private:
        uint8_t id;
        string name;
};

}}} // namespace ariba, appplication , pingpong

sznBeginDefault( ariba::application::pingpong::PingPongMessage, X ) {
        X && id && T(name);
} sznEnd();

#endif /* PINGPONGMESSAGES_H_ */

The message format for communication between Ariba PingPong instances is defined in the class PingPongMessage. It inherits from the Message class and uses the macro VSERIALIZEABLE; to declare this class as being able to serialize and deserialize itself. Note, that each such class must provide a default constructor that takes no arguments. The PingPongMessage defines two properties id and name that it wants to communicate to a remote instance.

To define the actual serialization code, use the following code as template:

sznBeginDefault( CLASSNAME, X ) {
        X && SERIALIZATION-VARIABLE-1 && SERIALIZATION_VARIABLE-2 && ...;
} sznEnd();

As you can see above, CLASSNAME is in the case of the PingPong sample the complate namespace with the class name ariba::application::pingpong::PingPongMessage. Furthermore the variables that are meant for serialization are combined to the X using the && operator. This operator is invoked both when serializing and when deserializing. Therefore, this is the only special code handling required.

The actual code from PingPongMessage looks as follows:

sznBeginDefault( ariba::application::pingpong::PingPongMessage, X ) {
        X && id && T(name);
} sznEnd();

Note the T() macro that is used for serialization of std::string objects. The following special handlers are provided:

• integer support - I( value, length )
• const int support - cI( uintmax_t )
• const char* support - cT( const char* )
• string and char* support, T( char* | std::string )

It is always best to use types that have a specified length, e.g. uint8_t, uint16_t, ... etc. If you are serializing through a inherited type where the serialization is provided in the base class, use the & operator before. Such a case is e.g. the NodeID class:

NodeID n;
SpoVNetID s
...
sznBeginDefault( Classname, X ) {
        X && &n && &s;
} sznEnd();

In your *.cpp class you require a further macro. In case of the PingPong sample this is simply:

vsznDefault(PingPongMessage);

The code which is between sznBeginDefault and sznEnd is called for serialization and for deserialization. Sometimes it is necessary to distinguish between the two for special handling. Therefore, you can use the functions

X.isSerializer()
X.isDeserializer()

When you want to have several message classes, you require one contained class where to can store which inner class is carried. This is, because messages don't carry there type with them. This means you always must know what kind of message you are delivered. Therefore, make a container class where you store the specific type stored. Make sure that your base class serializer always triggers serialization of the encapsulated class through

X && Payload();

You will find the following code in the PingPong sample that shows how to convert the incoming message to your format and invoke the deserializer:

void PingPong::onMessage(const DataMessage& msg, const NodeID& remote, const LinkID& lnk) {
    PingPongMessage* pingmsg = msg.getMessage()->convert<PingPongMessage> ();
    ...
}