ORM Designer Blog

Create support for your own framework in ORM Designer, part VI – import / export

Part VI:  How to define an import/export from ORM Designer model to ORM

Now lets look on next important step for ORM framework support implementation into ORM Designer. It is a data import and export between ORM Designer and ORM framework. Both of these steps are implemented separately and don't have to solved at all. In some framework for example it isn't needed or possible to do import. That's why only a support for data export from ORM Designer into ORM is created. In order to make import/export as flexible as possible, XML script language springing from Phing language syntax is used for script writing.

Firstly lets show how to set in our configuration which scripts should be used for import/export:

<orm-configuration
      name="AtomixORM"
      script-import="AtomixORM.import"
      script-export="AtomixORM.export">
</orm-configuration>

<framework-configuration name="AtomixMVC">
      <supported-orm
            name="AtomixORM"
            script-import-files-scanner="AtomixMvc.import.scanner.AtomixOrm">
      </supported-orm>
</framework-configuration>

During ORM framework configuration is possible to enter 3 different scripts:

• script-import: script used during model import into ORM Designer
• script-export: script used during export from ORM Designer to ORM definitions
• script-import-files-scanner: script serving to automatic finding of all definition files during automatic import

ORM Designer automatically loads all the scripts which are saved in files with mask *.uscript.xml. These files can be stored in anywhere in %ORM_Designer_Path%\Config or in %User_Application_Data%\OrmDesignerCore\config. Concrete location of these files can be found in ORM Designer configuration window at System Info tab:

Script files

Now we are going to show how the file with a simple script looks like. In directory %User_Application_Data%\OrmDesignerCore\Config\AtomixORM we create a file AtomixOrm.uscript.xml. Into this file we enter following XML fragment:

<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<uscript>
	<!-- ========== AtomixMvc.Import.Scanner.AtomixOrm ========== -->
	<function name='AtomixMvc.import.scanner.AtomixOrm'>
		<check>
			<is-set variable='directory'/>
		</check>
	</function>

	<!-- ========== AtomixORM.Import ========== -->
	<function name='AtomixORM.import'>
		<check>
			<is-set variable='lstFiles'/>
			<is-set variable='projectID'/>
		</check>
	</function>

    <!-- ========== AtomixORM.Export ========== -->
	<function name='AtomixORM.export'>
		<check>
			<is-set variable='projectID'/>
			<default variable='exportToOneFile' value=''/>
		</check>
	</function>
</uscript>

By this we have created the scripts which will be executed during the data import or export.

Initial values description

Each script has several initial values which we check by the command <check>. Here is their list.

• Import script
  • lstFiles: a list of files to import
  • projectID: project ID to which the files should be imported
• Export scirpt
  • projectID: project ID from which we will export
  • exportToOneFile: This variable determines an output file of project export when  project have to be exported to one file.
• Import scanner scirpt
  • directory: Determines a directory in which the files for import should be found

Conclusion

In this article we have shown how to configure and create basic scripts for ORM Designer. In next parts of serial we will step by step describe how to implement single scripts together with the explanations of some script language commands. If you have any question about this or following chapter, don't hesitate and ask us directly here on the blog or you can contact us at support@orm-designer.com.

How to create support for your own framework in ORM Designer, part V – inheritance support

Part V: how to specify inheritance support

In this part of the serial we are going to show how to configure inheritance types for ORM Designer. Regarding to fact that each framework may support different inheritance types, ORM Designer allows to define inheritance types by the XML configurations.

Again we start with an example from our configuration file AtomixOrm.cfg.xml:

<orm-configuration name="AtomixORM">

	<orm-inheritance-type name="SINGLE_TABLE" caption="Simple inheritance" discriminator-column-type="text" discriminator-column-size="255"/>
	<orm-inheritance-type name="JOINED" caption="Class table inheritance" discriminator-column-type="text" discriminator-column-size="255"/>
	<orm-inheritance-type name="MAPPED_SUPERCLASS" caption="Mapped superclass"/>

</orm-configuration>

If you use the code from this example in ORM Designer you should see following options when marking the inheritance:

<orm-inheritance-type>

name
Name of inheritance

caption
Visual caption of inheritance. This value is shown in inheritance-wizard dialogs.

discriminator-column-type
When discriminator field is automatically created in root inheritance table, this type is assigned to new field.

discriminator-column-size
Same as discriminator-column-type. Set size of a new created field.

If you have any question about this or following chapter, don't hesitate and ask us directly here on the blog or you can contact us at support@orm-designer.com.

How to create support for your own framework in ORM Designer, part IV – default values

Part IV: How to predefine values in ORM Designer

In this part of serial lets show how to pre-set some initial values for our framework.

In the case we use ORM in a combination with MVC framework, a directory structure for data saving is exactly specified. In this case it is possible to set default values in ORM Designer configuration files, which are used during creation of new objects in a model.

Firstly again an example from configuration file:

<framework-configuration name="AtomixMVC">
	<supported-orm name="AtomixORM"
		default-new-module-file-name="atomix-module"
		default-new-module-path="/app/plugins/%NAME%"
		default-first-module-file-name="first-module"
		default-first-module-path="/app"
		default-first-module-name="Atomix application"
		default-export-module-data-format="AtomixOrmXml"
		default-export-module-path="/data/models"
		script-import-files-scanner="AtomixMvc.import.scanner.AtomixOrm"
	/>
</framework-configuration>

Now lets go through single params of attribute <supported-orm> together with an example of their usage:

default-new-module-file-name and default-new-module-path
These attributes serve to set initial value during a creation of a new module. File-name determines a name of file, path determines a relative path to file with a project (*.ormdesigner). The result path is then composed from module-path and module-file-name as shown in following picture.

default-first-module-file-name, default-first-module-path and default-first-module-name
These attributes serve to set attributes of initial module which is created together with a new project. Module-path and module-file-name determine relative path to project, module-name determine visual caption of newly created module.

default-export-module-data-format and default-export-module-path
By these setting we can automatically define a format for data export into ORM framework. More about data export in chapter VI - import / export. Each newly created module (including the first module created with new project) has set this export format and export path.

script-import-files-scanner
This param serves to set a script which is used during automatic data import of our framework. More about this param in chapter VI - import/export.

If you have any question about this or following chapter, don't hesitate and ask us directly here on the blog or you can contact us at support@orm-designer.com.

How to create support for your own framework in ORM Designer, part III – custom ORM properties

Part III: How to define custom ORM properties for any object type (entity, field, module, association, ...)

This article is a part of serial about implementation of a support for an own ORM into ORM Designer. Now we are going to show how to add definitions of single properties which are specific for our ORM framework. Each ORM framework has several specific properties which uses for its configuration. By these properties you can modify entity behaviours, a way of work with fields etc. Therefore ORM Designer has a complex system for definition of these properties.

Here is an article describing all options of ORM properties configuration. How to configure new ORM properties and data types. Then we recommend to check up other ORM frameworks configurations where you can find many of ORM properties definitions (available in application directory OrmDesignerCore\config). These definitions can serve you as examples of all options of usage.

Now lets show how we can set several attributes for entity and field in our AtomixORM framework.

<orm-configuration name="AtomixORM">

	<attribute name="TABLE">
		<attribute name="useTable" type="string" help="Custom database table name"/>
		<attribute name="cacheQueries" type="bool" help="Whether or not to cache queries for this entity."/>
	</attribute>

	<attribute name="COLUMN">
		 <attribute name="readonly"  type="bool" help="Checks if a field is modified."/>
	</attribute>

</orm-configuration>

After saving of above mentioned definition into our configuration file (and restarting ORM Designer) we can see following properties in ORM Designer:

Element description <attribute>

In our example we define 2 attributes for the entity and 1 for the field. The attribute definition is proceeded by writing down the element <attribute> with attribute name including one of following enabled values:

PROJECT, MODULE, REGION, TABLE, COLUMN, FOREIGN-KEY, FOREIGN-KEY-COLUMN, MANY-TO-MANY-RELATION, MANY-TO-MANY-FOREIGN-KEY, INDEX, INDEX-COLUMN, COMMENT, INHERITANCE-PARENT, INHERITANCE-CHILD.

Into this root <attribute> then we insert one or more child elements by which we create a hierarchy of the properties. Each element attribute can have following attributes:

name
An attribute name, this attribute is required.

type
An attribute data type. Currently the following values are enabled:

• STRING, DECIMAL, FLOAT, BOOL: Simple values.
• ENUM, ENUM-RO: Enumeration values. In case of using ENUM-RO isn't possible to enter other value than pre-defined.
• COLUMN, TABLE, TABLE-PARENTS, TABLE-CHILDREN. A list of fields, all entities or parent/children entities
• PATH-RELATIVE, PATH-ABSOLUTE, FILE-RELATIVE, FILE-ABSOLUTE: File data types. Relative paths are relative to project root file (.ormdesigner)
• STRUCT - Defines a complex data type which holds another property. If <attribute> has any child, this type is automatically assigned.
• LIST,SET - A list or set of structs

abstract
Used in a combination with LIST/SET and STRUCT. If <atribute> have abstract="true" flag then this attribute isn't displayed in ORM editor and show only children.

child-type
Used in a combination with LIST/SET to define child types of this attribute.

default
A default value, currently not implemented.

enum-value
Defines values which are offered to a user when editing this attribute. Values are separated by |.

help
A help text displayed in the bottom of ORM editor.

help-url
Url to more information about selected attribute. Currently not implemented.

inherit
Defines another attribute to inherit all his childs. Usefull when lots of attribute share simmilar child values.

export-tag
Export-tag is added to <attribute> element when exporting model to ORM definitions. Usefull to add additional information for XML processing.

merge-column
Used for internal usage only.

More information about ORM properties defining can be found in the article How to configure new ORM properties and data types.

Note: Names of each type spring from historical reasons from ERD diagram. That's why in place of ENTITY is used TABLE etc.

Note2: Some of types can't be currently visually edited in ORM Designer. These types are INDEX-COLUMN, INHERITANCE-PARENT a FOREIGN-KEY-COLUMN.

If you have any question about this or following chapter, don't hesitate and ask us directly here on the blog or you can contact us at support@orm-designer.com.

How to create support for your own framework in ORM Designer, part II – ORM data types

Part II: define ORM data types

In this part of the serial about a support implementation for an own ORM into ORM Designer we are going to show you how to configure ORM framework data types. Each ORM uses its own types that reflect the framework orientation and usage. That's why ORM Designer offers the possibility of all types setting.

Here you can find an article about preliminary settings and configuration files creating.

An example of several data types settings for our AtomixORM:

<orm-configuration name="AtomixORM">
	<orm-data-type name="integer"   unified-name="@INTEGER,@INT" primary-key-data-type="true"/>
	<orm-data-type name="string"    unified-name="@TEXT,@LONGVARCHAR,@VARCHAR,@CHAR"/>
	<orm-data-type name="date"      unified-name="@DATE"/>
	<orm-data-type name="time"      unified-name="@TIME"/>
	<orm-data-type name="enum"      unified-name="@ENUM" has-enum-values="true"/>
</orm-configuration>

If you have defined ORM data types as shown in our XML example, during an entity editing you should see following data types in field editor:

Popis elementu <orm-data-type>

For the data type defining use an element orm-data-type. Here is a description of all its attributes:

name
This is the only one attribute which is required. It includes a data type name.

unified-name
By this attribute it is possible to enumerate the data types that are transformed into a specific ORM data type during an import from external applications or another sources. For example when is a model imported from a database. All the columns with datatype TEXT,LONGVARCHAR,VARCHAR and CHAR will be transformed to ORM data type string. All the datatypes in "unified-name" attribute have to start with char @.

primary-key-data-type
By this attribute is defined which of datatypes is used as datatype for automatically created primary keys. If more datatypes have this attribute, the first found attribute will be used.

has-enum-values
By this attribute are marked the datatypes of enumeration type. Currently using of this attribute has no influence on any ORM Designer functionality. We recommend to fill this attribute because it can be used in future ORM Designer versions with new functions implementation.

If you have any question about this or following chapter, don't hesitate and ask us directly here on the blog or you can contact us at support@orm-designer.com.

How to create support for your own framework in ORM Designer, part I – basic XML configuration

Introduction

Currently there exists a batch of smaller, rising or corporate ORM frameworks which can also benefit from ORM Designer. In next parts of this serial we are going to show how to easily implement a support for an own framework in ORM Designer.

The whole implementation is very simple and customizable. Configuration consists of settings of several configuration XML files, implementation of XSLT templates for data import and export from ORM Designer format into ORM framework native data and writing scripts that process the single steps and these configuration (the script arises from the syntax of script language Phing).

In these articles we are going to describe how to create a support for imaginary framework AtomixORM. Step by step we are going to show the implementation of required parts for allowing ORM Designer to work with target ORM.

In following page is available several documents concerning ORM Designer file structure, a work with configuration repository etc.

http://www.orm-designer.com/tag/developers

Part I: create basic XML configuration for our framework.

We start with a creation of basic configuration file AtomixOrm.cfg.xml. We place it to a user's configuration repository (more information you can find in the article Configuration files location and validation), which is in this directory:

%User_Application_Data%\OrmDesignerCore\config\AtomixORM

We are assuming that besides ORM you have also some MVC framework which this ORM uses. In our case we call the MVC framework as AtomixMVC. Hence, we write into our configuration file the following code:

<?xml version="1.0" encoding="utf-8"?>
<orm-designer-configuration>

	<framework-configuration name="AtomixMVC">
		<supported-orm  name="AtomixORM"/>
	</framework-configuration>

	<orm-configuration name="AtomixORM">
	</orm-configuration>

</orm-designer-configuration>

By this code we define our AtomixMVC and AtomixORM. Now if you restart ORM Designer you should see the following screen during new project creation.

Note: For more information about the single elements and its all allowed attributes look at XML schema for configuration files - configuration.xsd. This and other schemata for all types of XML files are available in an application directory in subdirectory Schema (i.e.: "c:\Program Files (x86)\OrmDesignerCore\Schema").

If you have any question about this or following chapter, don't hesitate and ask us directly here on the blog or you can contact us at support@orm-designer.com.