Serialization

Table of Contents

1. Serialization list
2. Serialization description
   1. Managed serializations settings
      1. File
         1. JSON File
         2. XML File
         3. Manifest explanation
      2. Sql Table
   2. serialization node
   3. properties node
      1. Serialization name
      2. Aggregation
3. Serialization Person example

Serialization list

The list of all your serializations must be referenced in an XML or JSON file. The path to this file must be defined in the file config.json with the key serializationList (see Installation page for more informations).
You have to specify the manifest serialization list version to determine witch parser will be used to parse the document. There is currently only one version allowed 2.0.

If you decide to define your serialization list in XML format, your file must have "xml" extention and content must look like :

<serializations version="2.0">
    <list>
        <person>relative/path/to/person/serialization/manifest.xml</person>
        <house>relative/path/to/house/serialization/manifest.xml</house>
        <town>relative/path/to/town/serialization/manifest.xml</town>
    </list>
</serializations>

If you decide to define your serialization list in JSON format, your file must have "json" extention and content must look like :

{
    "version" : "2.0",
    "list" : {
        "person" : "relative/path/to/person/serialization/manifest.json",
        "house"  : "relative/path/to/house/serialization/manifest.json",
        "town"   : "relative/path/to/town/serialization/manifest.json"
    }
}

As you can see the list permit to associate a name to a serialization path. Each name is unique and each manifest path must have "xml" or "json" extention. Finally the serialization path must be relative to the folder that contain serialization list file.

Serialization description

A Serialization is attached to a model and permit to serialize/deserialize (save/load) object in/from a specific input/output. For example I have defined a manifest Person and I want to serialize persons in sql database; I have to define table name and database connection.

Serialization settings are described by their own manifest (for example for sql database serialization, there is a manifest sqlDatabase and a manifest sqlTable). All allowed serializations are described in next section.

You have to specify the manifest serialization version to determine witch parser will be used to parse the document. There is currently only one version allowed 2.0.

Serializations can be defined in XML or JSON format. For each example we will illustrate XML and JSON format.

<manifest version="2.0">
    <serialization/>
    <properties/>
</manifest>

{
    "version": "2.0",
    "serialization" : {},
    "properties"    : []
}

• serialization node describe your serialization settings
• properties node describe some needed properties informations for serialization

Managed serializations settings

File

There are currently two supported formats : JSON and XML.

JSON file

this serialization permit to store objects in JSON files in local file system. The model name that correspond to this serialization is jsonFile.
jsonFile is described in manifest Comhon/Manifest/Collection/Manifest/JsonFile/manifest.json

XML file

this serialization permit to store objects in XML files in local file system. The model name that correspond to this serialization is xmlFile.
xmlFile is described in manifest Comhon/Manifest/Collection/Manifest/XmlFile/manifest.json

Manifest explanation

JSON and XML manifests are exactly the same. they have two properties :

• saticPath that define the folder where objects will be stored
• staticName that define the file name of all saved objects

each object will be saved in intermediate folder identified by the object id.

For example if you have an XML file serialization :

{
    "saticPath": "/asolute/path/to/a/folder",
    "staticName": "file_name.json"
}

and you want to serialize an object with id an_id, file will be saved at :

/asolute/path/to/a/folder/an_id/file_name.json

Sql Table

this serialization permit to store objects in sql table in local or distant database. The model name that correspond to this serialization is sqlTable.
sqlTable is described in manifest Comhon/Manifest/Collection/Manifest/SqlTable/manifest.json and is linked to another manifest sqlDatabase that is described in manifest Comhon/Manifest/Collection/Manifest/SqlDatabase/manifest.json. Actually if you take a look at sqlTable manifest you will see a property database with type sqlDatabase.

In sqlDatabase manifest you can see a property DBMS, it permit to identify your database management system. Comhon! currently manage followings DBMS :

• mysql
• pgsql

sqlTable and sqlDatabase have their own serialization file. They are respectively :

• Comhon/Manifest/Collection/Serialization/SqlTable/manifest.json
• Comhon/Manifest/Collection/Serialization/SqlDatabase/manifest.json.

In these files you will find in which folder you have to serialize your tables and databases informations. They are respectively :

• /var/data/table
• /var/data/database

Currently there are no configurations to customize these paths but you can edit manifest serializations and put your own path.
But you have to be careful if you update Comhon! (for example for a newer version), it could overwrite your modifications.

Example of a right serialized sql serialization :

• A table file /var/data/table/my_table_name/table.json

{
    "name": "my_table_name",
    "database": "my_db"
}

• A database file /var/data/table/my_db/database.json

{
    "id": "my_db",
    "DBMS": "mysql",
    "host": "localhost",
    "name": "database",
    "user": "my_user",
    "password": "my_passord",
    "options": {
        "charset": "utf8",
        "timezone": "UTC"
    }
}

Comhon! is optimized to load only one time serializations. For example if you have two tables that refer the same database, and if you use them in a single script execution, tables will share the same instance of database.

serialization node

serialization node describe your serialization settings and there are two way to define your serialization settings :
1. describe directly your serialization settings (see corresponding manifest to know how to describe your serialization)

<manifest version="2.0">
    <serialization type="jsonFile">
        <value saticPath="/asolute/path/to/a/folder" staticName="a_file_name.json"/>
    </serialization>
    <properties/>
</manifest>

{
    "version": "2.0",
    "serialization": {
        "type": "jsonFile",
        "value": {
            "saticPath": "/asolute/path/to/a/folder",
            "staticName": "a_file_name.json"
        }
    }
}

2. reference an id of a serialization (obviously reference a serialization that has been serialized)

<manifest version="2.0">
    <serialization type="sqlTable" id="a_table_id"/>
    <properties/>
</manifest>

{
    "version": "2.0",
    "serialization": {
        "type": "sqlTable",
        "id": "a_table_id"
    }
}

properties node

properties node is a list of properties. Each property node refer to a property in corresponding Model.
For the following explanations we will build a serialization Person like example.

Serialization name

some serialization doesn't manage certain characters so you can replace a property name when you serialize your Object. For example pgsql doesn't manage columns names with uppercase, so if you have a property name APropertyName you can define a serialization name a_property_name that will match with your column name.

<manifest version="2.0">
    <serialization type="sqlTable" id="person"/>
    <properties/>
        <firstName serializationName="first_name"/>
    </properties>
</manifest>

{
    "version": "2.0",
    "serialization": {
        "type": "sqlTable",
        "id": "person"
    },
    "properties": {
        "firstName": {
            "serializationName": "first_name"
        }
    }
}

Aggregation

Aggregation is a way to associate a model to others models by matching properties. This information is used only for slqTable serialization, actually it permit to make automatic join between sql tables when it's needed (typically during request). For example model Person has a foreign property homes (see Manifest example), model home has it own serialization and would have a property owner (serialized in a column like owner_id or person_id), so aggregation would refer owner and look like :

<manifest version="2.0">
    <serialization type="sqlTable" id="person"/>
    <properties>
        <homes>
            <aggregations>
                <aggregation>owner</aggregation>
            </aggregations>
        </homes>
    </properties>
</manifest>

{
    "version": "2.0",
    "serialization": {
        "type": "sqlTable",
        "id": "person"
    },
    "properties": {
        "homes": {
            "aggregations": [
                "owner"
            ]
        }
    }
}

A property can refer to several aggregations :

<manifest version="2.0">
    <serialization type="sqlTable" id="person"/>
    <properties>
        <children>
            <aggregations>
                <aggregation>mother</aggregation>
                <aggregation>father</aggregation>
            </aggregations>
        </children>
    </properties>
</manifest>

{
    "version": "2.0",
    "serialization": {
        "type": "sqlTable",
        "id": "person"
    },
    "properties": {
        "children": {
            "aggregations": [
                "mother",
                "father"
            ]
        }
    }
}

Serialization Person example

<manifest version="2.0">
        <serialization type="sqlTable" id="person"/>
        <properties>
            <firstName serializationName="first_name"/>
            <birthPlace serializationName="birth_place"/>
            <father serializationName="father_id"/>
            <mother serializationName="mother_id"/>
            <children>
                <aggregations>
                    <aggregation>mother</aggregation>
                    <aggregation>father</aggregation>
                </aggregations>
            </children>
            <homes>
                <aggregations>
                    <aggregation>owner</aggregation>
                </aggregations>
            </homes>
        </properties>
</manifest>

{
    "version": "2.0",
    "serialization": {
        "type": "sqlTable",
        "id": "person"
    },
    "properties": {
        "firstName": {
            "serializationName": "first_name"
        },
        "birthPlace": {
            "serializationName": "birth_place"
        },
        "father": {
            "serializationName": "father_id"
        },
        "mother": {
            "serializationName": "mother_id"
        },
        "children": {
            "aggregations": [
                "mother",
                "father"
            ]
        },
        "homes": {
            "aggregations": [
                "owner"
            ]
        }
    }
}