Serialization

Table of Contents

1. Serialization list
2. Serialization description
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).

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

<serializations>
    <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>
</serializations>

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

{
	"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. Finaly 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 exemple I have defined a manifest Person and I want to serialize persons in sql database; I have to define table name and database connection.

A loaded serialization is an instance of a class that extends from class SerializationUnit that extends from Object. So serializations models are described in manifests and can be serialized/deserialized (you can find them in manifestCollection folder).

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

<manifest>
    <serialization/>
    <properties/>
</manifest>

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

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

managed serializations

• table in sql database : sqlTable (local or distant)
• json file : jsonFile (local)
• xml file : xmlFile (local)

serialization node

There is two way to define your serialization :
1. describe directly your serialization (see corresponding manifest to know how to describe your serialization)

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

{
	"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>
    <serialization type="sqlTable">a_table_id</serialization>
    <properties/>
</manifest>

{
	"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 exemple 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>
    <serialization type="sqlTable">person</serialization>
    <properties/>
        <firstName serializationName="first_name"/>
    </properties>
</manifest>

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

composition

Composition is a way to associate a model to others models by matching properties (this information is used only for slqTable serialization and for sql database request). For example model Person has a foreign property homes (see Manifest page), model Home has it own serialization and would have a property owner (serialized in a column like owner_id or person_id), so composition would refer owner and look like :

<manifest>
    <serialization type="sqlTable">person</serialization>
    <properties>
        <homes>
            <compositions>
                <composition>owner</composition>
            </compositions>
        </homes>
    </properties>
</manifest>

{
	"serialization": {
		"type": "sqlTable",
		"id": "person"
	},
	"properties": {
		"homes": {
			"compositions": [
				"owner"
			]
		}
	}
}

A property can refer to several compositions :

<manifest>
    <serialization type="sqlTable">person</serialization>
    <properties>
        <children>
            <compositions>
                <composition>mother</composition>
                <composition>father</composition>
            </compositions>
        </children>
    </properties>
</manifest>

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

Serialization Person example

<manifest>
    	<serialization type="sqlTable">person</serialization>
    	<properties>
    		<firstName serializationName="first_name"/>
    		<birthPlace serializationName="birth_place"/>
    		<father serializationName="father_id"/>
    		<mother serializationName="mother_id"/>
    		<children>
        		<compositions>
            		<composition>mother</composition>
            		<composition>father</composition>
        		</compositions>
    		</children>
    		<homes>
        		<compositions>
            		<composition>owner</composition>
        		</compositions>
    		</homes>
    	</properties>
</manifest>

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