Creating new Data

From MARIEWiki

Contents 1 Data 2 What's a DataFactory ? 3 How to get an instance of a DataFactory 4 How to add support for new datatype within DataFactory 4.1 Create a new datatype class inheriting from DataAbstract class 4.2 Create a corresponding SerDes for each data representation format that needs to be supported 4.3 Create and install SerDes plugin 5 How to unit test the new datatype and its SerDes 5.1 Create build directory 5.2 Create a data generator 5.3 Reuse DataTest unit test template 5.4 Reuse FactoryTest test template

Data

Data plays an important role when designing and implementing components. Being able to define and use specialized data according to the application's domain, usually enhances the design.

In MARIE, data can be represented in two forms :

1. Class derived from DataAbstract based class.
2. Serialized (char*, length)

The first form is usally used within a component to encapsulate information for one datatype and its related operations. The second form is usally used to transmit data between components using communication mechanisms (socket, shared memory, IPC, etc.).

This approach allows to use generic communication classes and interfaces that are not aware of the exact nature of the received or transmitted data, and permits user-defined data to be used. The program marie-info indicates which datatype are available on a MARIE 0.5 setup.

What's a DataFactory ?

DataFactory is a class for data serialization/deserialization (converting form 1. to form 2., and vice versa). It is composed of SerDes classes which are delegated classes responsible of data serialization/deserialization. Each SerDes can serialize/deserialize one datatype according to a specific data representation format (ex. SerDesMarieXMLDataNull class serializes/deserializes DataNull datatype following MarieXML data representation format).

Important Note : You must delete data instance created by the DataFactory when you're done with it to avoid memory leaks.

How to get an instance of a DataFactory

DataFactory are produced by SerDesFactory singleton class. Each created DataFactory contains SerDes for a specific data representation protocol (ex. MarieXML, TabSeparated, etc.) identified with a unique ProtocolID.

Here's an example on how to create a DataFactory instance :

SerDesFactory& serdesFactory = SerDesFactory::getInstance();
DataFactory* dataFactory = serdesFactory.createDataFactory("MARIEXML");

Important Note : You must delete DataFactory instance when you're done with it to avoid memory leaks.

To know which ProtocolIDs are available in your current setup, you can use the marie-info program.

How to add support for new datatype within DataFactory

Create a new datatype class inheriting from DataAbstract class

Here's an empty shell to get started :

MyData.h
MyData.cpp

Create a corresponding SerDes for each data representation format that needs to be supported

Here's an empty shell to get started :

SerDesMyDataProtocolX.h
SerDesMyDataProtocolX.cpp

Create and install SerDes plugin

Each SerDes must be linked in an independant shared library. The library name must have the prefix "libmarieserdes_" in order to be retrieve by the dynamic loader. To find the SerDes libraries, the dynamic loader searches in all the path contained in the environment variable MARIE_SERDES_PATH (each path being separated by colon). Library installation path then needs to be added to that environment variable.

To check if the new SerDes have been loaded properly, you can use the marie-info program.

How to unit test the new datatype and its SerDes

Note : MARIE's unit test classes and headers needs to be installed. If not, executes this command :

scons check install

Create build directory

Create a directory where the unit test will be build, and copy ut.cpp in that directory.

The same unit test can be use for multiple datatypes to test. The following steps of the procedure covers all step to creates unit test from scratch. In the case where datatype needs to be added to existing unit test, it is only a matter of registering the new datatypes and add specialized tests implementations.

Create a data generator

Create a data generator class implementing GenDataIF.h that produces datatype to test. Check GenData.cpp as an example.

Reuse DataTest unit test template

There's already a template class that tests common functionnality on datatype (ex. data creation, data clone, etc.). To reuse that template, create a class the inherits from DataTestT.h which is normally installed with MARIE. Check MarieDataTestT.h and MarieDataTest.cpp as an example.

There's is two important thing to take care of :

1. Make sure that in the constructor of your DataTest class you instanciate the correct DataGenerator and use the right protocolID.
2. Register cppunit tests with your own datatype.

Some data type might have to do specialized operation to be tested :

• testGetSet depends on the datatype to test.
• testOther is available to test other functionnality not covered in the generic tests.

Those specialized implementation must be added in DataTest.cpp (check MarieDataTest.cpp as an example).

Reuse FactoryTest test template

There's already a template class that tests common functionnality on DataFactory (ex. data serialization/deserialization, data supported, etc.). To reuse that template, create a class the inherits from FactoryTestT.h which is normally installed with MARIE. Check FactoryMarieXMLTestT.h and FactoryMarieXMLTest.cpp as an example.

There's is two important thing to take care of :

1. Make sure that in the constructor of your DataTest class you instanciate the correct DataGenerator and use the right protocolID.
2. Register cppunit tests with your own datatype.

Some data type might have to do specialized operation to be tested. Those specialized implementation must be added in DataTest.cpp (check FactoryMarieXMLTest.cpp as an example).