How ORM Designer performs import and export model schema files

Import and export in ORM Designer

In ORM Designer import and export consits of two steps. One of these steps is a transformation between ORM Designer format and temporary format. During this process, it is recommended to perform all main transformations. The second step is a transformation between the temporary format and single definition files of the ORM.

The argument for this split-up is that sometimes on a base of one definition file isn't possible to get all needed data. That's why the single definition files are first of all merged into a one file and then all the transformation operations are performed above this file. More about the transformations is in following articles.

How orm designer imports schema files

As shown above, the import is devided into more steps. These steps allow ORM Designer to import correctly all data.

1) Import start-up: Input to import process can be one or more files which should be imported into ORM Designer

2) First transformation: On every single XML file defined by step 1 is performed XSLT transformation (In the case that the file type is different from XML, the file is first converted to XML. Currently XML and YML files are supported.)

3) Merging into temporary file: Files transformed as desribed in the previous step are merged in one XML file.

4) Main transformation: On temporary file created in previous step is performed main XSLT transformation to ORM Designer data format.

5) ORM Designer exchange format: The output of the transformation is XML file containing a description of all result files of ORM Designer project.

6) XML validation: Output XML file is then validated by an XSD schema.

7) Open model: Successfully validated output XML file is opened in ORM Designer.

How orm designer exports schema files

As well as the import, the export is also devided into more steps. The reason for the separation is the same as in the case of import - because of correct export of any model into ORM schema files.

1) ** Export start-up**: Input to export process is a project created in ORM Designer.

2) One-file project: The whole project is serialized to one single XML.

3) Exchange format: The file generated in the previous step includes information about all modules, their original location and designated export location.

4) Main transformation: Main XSLT transformation is performed on exchange file. This transformation could convert the major part of data to the requested format. The output of this process is one file again.

5) Merged transformated files: This file is result from transformation in previous step. This file is again in XML format and describing the final structure off all output files.

6) Split-up and the second transformation: The output file from the previous step is now split and above each of the file is run the second transformation modifying them into designated format. In the case that YML or other non-XML file should be an output, additional transformation is performed to convert XML into result format.

7) Saving: After files are splitted up and transformated to the result format they are saved to destination file.

Configuration of XSLT transformation

Settings for concrete ORM framework could be changed by its configuration files. Complete information about configuration files you will find in the article Structure of ORM Designer configuration file. Here is only the concise description of XML configuration files related to import and export.

Description of configuration file

The used sample configuration is taken over from Propel framework which supports two types of definition files (XML and YML).

<orm-configuration name="Propel" 
    import-template="...\PropelXml2Xml.xsl"
    export-template="...\Xml2PropelXml.xsl"
    >

    <orm-data-format 
        name="PropelXml" 
        file-type="XML" 
        import-filename-mask=".*(schema\.xml)" 
    />

    <orm-data-format 
        name="PropelYml" 
        file-type="YML" 
        pre-import-template = "...\PropelYml2PropelXml.xsl"
        post-export-template = "...\PropelXml2PropelYml.xsl"
        import-filename-mask=".*(schema\.yml)" 
    />
</orm-configuration>

• The configuration file defines ORM framework by tag <orm-configuration/> (Propel)

  • Attribute import-template defines the template performed during the import in step(4)
  • Attribute export-template defines the template performed during the export in step(4)

• The configuration file defines two file formats by tag <orm-data-format/> ( PropelXML a PropelYML).

  • Attribute name serves to unique naming of data type.
  • Attribute file-type defines a file data type. Currently the XML and YML file is supported.
  • Attribute import-filename-mask defines by regular term which files will be considered as definition during automatic import.
  • Attribute pre-import-template defines a path to XSLT file by a template performed during import in step (2)
  • Attribute post-export-template defines a path to XSLT file by a template performed during export in step(6)

What is needed for defining new ORM framework

In the case that the support for a new ORM is implemented, it is necessary to perform following steps:

• create transformation XSLT for import/export into concrete files,
• to define XML configuration file for the ORM
  • an ORM name, recommended paths and ORM file name,
  • a path to XSLT teplates,
  • attribute data types of the ORM,
  • additional attributes of the ORM,
  • define behaviour or other special features.

This article is only about data import and export principle in ORM Designer. Further information about configuration files you will find in the article Structure of ORM Designer configuration file. For general information about framework implementation read New framework in ORM Designer.

Unit testing of import and export

Because XSLT templates for transformation between ORM Designer format and ORM can be very complicated, for assuring the quality it is recommended to use unit test. ORM Designer currently support several methods how to run unit-testing for XSLT templates. More about unit testing you can find in article Testing ORM Designer import and export.

I want to implement my framework

If you decide to implement your own framework, we believe that this article grants you general information how ORM designer generate definition files. Further information you will find in the article How to create support for new ORM and MVC framework.

Detailed previews of XSLT templates, samples of configuration files, eventually qualified help with settings we afford on request. We will also help you with the implementation process.

Author: Ludek Vodicka