Universal Data Modelling Generator · PDF file4.1.1 Check for correct Java version in Xtext...

PPI AG Informationstechnologie

13, 22301 Hamburg Moorfuhrtweg � Wall 55, 24103 Kiel

Peter-Muller-Str. 10, 40468 Düsseldorf � Wilhelm-Leuschner -Straße 79, 60329 Frankfurt/Main

Universal Data Modelling Generator

Administration

Document version: 3.3.

Status: Approved

Date: 17/04/2015

Authors: Jörg Stahnke / Jan Ross

Document version 3.3. from 17/04/2015 AdministratorGuide.docx 2

Approved Universal Data Modelling Generator – Administration

Version management for document AdministratorGuide.docx

Name Date Docu-ment version

Comments

Jörg Stahnke 06/02/2013 1 Initial version

Jan Ross 12/02/2013 2 Extensions in chapters 3 and 6

Jörg Stahnke 28/02/2013 2.1 Revision of all sections

Separation into Administrator Manual and User Manual

Extension by adding project-specific adjustments

Jörg Stahnke 11/04/2013 2.2 Adaptation for version 2.2

Jörg Stahnke 27/06/2013 3.0 Adaptation for version 3.0

Jan Ross 31/07/2013 3.1 Extension by adding information on migration 3.1

Jörg Stahnke 01/08/2013 3.2 Further extensions for migration 3.1

Jan Ross 17/04/2015 3.3 Adaptation for version 3.3

Copyright This document has been produced by the PPI AG Informationstechnologie and is protected by copyright with re-spect to third parties. All rights, including translation, reprint or reproduction of the entire document or parts thereof, shall require the consent of the PPI AG Informationstechnologie.



Table of Contents

1 Introduction ................................................................................................................ 5

2 Defining the project-specific working method ......................................................... 6

2.1 Working method without functional definitions ......................................................................6

2.2 Consequent functional data element hierarchy .......................................................................6

2.3 Rough data element hierarchy ..................................................................................................7

2.4 Tasks of functional data elements and technical data types..................................................7

3 Create initial project ................................................................................................... 9

3.1 Project Java settings ..................................................................................................................9

3.2 Project-specifications .............................................................................................................. 10

3.2.1 Placeholders ............................................................................................................................... 11

3.2.2 Customer Documentation ........................................................................................................... 11

3.2.2.1 How to create the customer documentation ......................................................... 12

3.2.2.2 Defining the structure of the customer documentation ......................................... 12

3.3 Error messages for incorrect project settings ....................................................................... 16

4 Create project-specific extensions .......................................................................... 18

4.1 General preparation ................................................................................................................. 18

4.1.1 Check for correct Java version in Xtext ...................................................................................... 18

4.1.2 The Xtend compiler settings ....................................................................................................... 20

4.2 Derive a project-specific DSL from the UDG .......................................................................... 20

4.2.1 Create a Xtext Project ................................................................................................................ 20

4.2.2 Test the project-specific DSL ...................................................................................................... 25

4.3 Create project-specific generators ......................................................................................... 26

4.4 Project-specific extension of the DSL structures .................................................................. 28

4.5 Project-specific adaptations of the documentation .............................................................. 30

4.6 Recommendations for project-specific extensions ............................................................... 33

4.7 Recommended test when using the wizards ......................................................................... 34

5 Providing features for Eclipse ................................................................................. 35

5.1 Tasks to be performed once .................................................................................................... 35

5.2 Regular tasks ............................................................................................................................ 36

5.2.1 Create and deliver the features .................................................................................................. 36

6 Public interface for project-specific generators ..................................................... 38



6.1 Objective ................................................................................................................................... 38

6.2 Implementation ......................................................................................................................... 38

6.3 Examples for project-specific adaptations............................................................................. 39

6.4 Recommendations ................................................................................................................... 39

7 Migrations ................................................................................................................. 43

7.1 Installation of updates ............................................................................................................. 43

7.2 Version 3.3.0 ............................................................................................................................. 43

8 ANNEX ....................................................................................................................... 44

8.1 Description of setting parameters .......................................................................................... 44

8.1.1 Convention Parameters .............................................................................................................. 44

8.1.2 Capture of free text ..................................................................................................................... 52

8.1.3 Default data elements ................................................................................................................. 53

8.1.4 Tablespace parameters / default tablespace .............................................................................. 54

8.1.5 Default relation and sequence .................................................................................................... 57



1 Introduction

This document is intended for administrators.

Administrators have the following tasks:

� initially creating the model files for recording data models in UDG

� performing project-specific settings of the UDG (generation and customer doc-umentation)

� creating tablespace definitions

� defining project-specific working methods for data modelling

� writing project-specific extensions

• project-specific generators

• structural extensions for the DSL language

• adjustments to the customer documentation

� migration to current versions of the UDG

All these tasks are usually performed at the start of the project without having to be adapted in the course of the project.

Administrators are not responsible for recording and maintaining the actual data model of the project respectively for generating artifacts.

The tasks to be performed are described in the Universal Data Modelling Generator User Manual [1].

This document assumes that the information contained in the user manual is known to the administrator.



2 Defining the project-specific working method

Before creating the data model the working method which suits best for this project should be defined. In general, three methods are available:

� without functional definitions (only recommended for extremely small data mod-els)

� using a rough data element hierarchy

� using a functional data element hierarchy

In order to facilitate this decision the advantages and disadvantages of the proce-dures are compared in the following.

2.1 Working method without functional definitions

If this procedure is used, no functional data elements are created. The formats of re-lation attributes are defined by direct reference to the technical data types.

Advantages:

� Maintenance of data elements is not necessary.

� All information is included in the model files *.dbrel .

Disadvantages:

� Consistency of format definitions is not guaranteed.

For example a single account number can have a different format in each rela-tion.

� Inheritance mechanism for attributes is not used.

� Redundant input is necessary.

� Redundant descriptions are required.

2.2 Consequent functional data element hierarchy

In this procedure all existing data is modeled from a functional point of view. To this end, data properties are defined by starting with the general ones before specifying specific properties into more detail. This applies to both, technical parameters of the data as well as the functional description.

Example:

Currency -> currency identifier according to German Federal Bank sys-tematic ->currency account balance

Most efforts of this approach lie in the modelling of the functional data elements

(*.dbdata model files). Attributes in the model files for relations are (almost)

completely defined by the reference to the respective data element.

Advantages:

� Consistency of the definition of the same data, appearing in different relations is guaranteed.



� No redundant capture of descriptions at attribute level is required.

It is possible to use the data element description.

� Inheritance is used very well.

Disadvantages:

� Information for data elements and relations is distributed.

� This procedure only works if there are exact definitions for the data element hi-erarchy and if these definitions are consequently used.

2.3 Rough data element hierarchy

In fact, this approach is a mixture of the two previous procedures. Specific functional data elements containing all information are defined and used for frequent data oc-currences.

For data that occurs only in one or very few relations, general data elements con-taining only some information are used. The other properties are added directly at attribute level.

These general data elements are mostly defined from a technical point of view.

Examples for frequent data

� currency

� account number

� customer number

� industrial sector identifier

All these data elements have a functional reference.

Examples of common data elements with technical orientation

� amount

� interest rate

� full designation

� date

� date with time

� general string

� external numeric ID

� internal ID

These data elements have no concrete functional reference, but they have always the same technical format.

2.4 Tasks of functional data elements and technical data types

For an understanding of the following chapter, it is important to distinguish exactly between functional data elements and technical data types. Confusion may arise especially if the "functional" data elements are used from a technical point of view.



Technical data types

� are used to map to the technical format of output languages

� are defined in the convention file (*.dbconv ) by the administrator

� have to be defined in such a way that each technical data type can be assigned clearly to a data type in each language

� There are relatively few technical data types.

� A fixed length or a variable length can be defined for the mapping.

Functional data elements

� are used to define attribute properties (name, required field, comment, possibly variable length, etc.)

� reference the technical data types

� can influence the language-specific data type with regard to the length specifi-cation

� Their number can greatly vary depending on the method of operation in the pro-ject.

Example of Boolean

A project has Boolean values which use the expression N and Y . Normally the

fields are mandatory fields with the default value N.

There is a project-specific generator, which maps these fields to the Java class

Boolean .

In this case, a technical data type Boolean is required. Here you can define a map-

ping for databases with fixed-length to CHAR(1) and for Java to Boolean .

At the same time, you should create a top level data element Boolean. All other

relevant data elements and attributes inherit from this top level data element.

This top level element Boolean has the properties notNull and def "N" and in-

herits these properties to its subcomponents1. These properties can be overwritten for individual data elements or attributes.

1 Alternatively the type specific default data element for the technical data type Boolean can have

these properties.



3 Create initial project

It is strongly recommended to create initial projects using the available wizards. By

selecting New->Other->PPI Datamodelling->1.Datamodelling init ial project a fully functional initial project for the PPI data modelling is created.

Figure 1: Wizard to create an initial data model project

It should then be tested whether the generation of files as well as a change of input data is possible with the Xtext editor.

In the local src directory the project-specific adjustments can be made. The

default.* files contain an executable project setting. Adjust these files step by

step according to your project-specific acquirements. The prj* files should be re-

named to meaningful names. They are prepared for your data model. A description of each parameter is located in the annex (see section Description of setting para-meters, page 44).

3.1 Project Java settings

If the project was created using the wizard, the settings described in this sub-section have already been done.

When you created a project without the wizard the following settings must be per-formed:

� Activate Xtext for this project using the context menu of the project via

Configure->Add Xtext Nature .

� Disable the automatic generation of all artifacts in each project containing Xtext model files during storage. To do this perform the following settings in the prop-erties of the Xtext project:



Figure 2: Properties of the Xtext project

Note:

Make sure that the project is created on New->Project->General->Project as a general project (see also section Error messages for in-

correct project settings, page 16).

� If there are project-specific generators use the same compiler settings for the

compiler of the project-specific DSL. (Relation is the definition of the basic

components, myDsl may be a project-specific DSL).

3.2 Project-specifications

Having created the project, you have to specify basic settings for the DDL genera-tion of the project. The UDG for data modelling and DDL generation need the follow-ing files:

� default.dbconf : In this convention file relevant parameters for the entire pro-

ject as well as the appearance of the customer documentation are defined. The project may contain only one convention file.

Note:

Please do not mix up conventions and configurations. Conventions are the project-wide settings of the UDG defined in this file. Configurations are settings in the generator files used to create artifacts.

� default.dbdata: This file is used to assign the technical data types defined

in the default.dbconf to default functional data elements



� default.dbphysic : defines the default tablespaces

� default.dbrel: defines the default relation and default sequence.

3.2.1 Placeholders

The definition how to create technical names uses placeholders. Placeholders are

always enclosed by the character '%' . The following placeholders are available:

Placeholder Meaning

%name% replaced by the name you entered for the object

%table% replaced by the technical relation name

%tableparent% replaced by the technical relation name of the parent relation

%field% replaced by the technical attribute name

%value% replaced by the default value entered

%length% replaced by length specified for the data element / at-tribute

%tableadditional% replaced by the technical relation name of the addi-

tional relation (see property additionalFields in

the generation files described in the User Guide)

Note:

Placeholders cannot be used at any point. If incorrect placeholders are used, the validation of the file fails. The error text contains a note which placeholders are allowed at this point.

3.2.2 Customer Documentation

This section describes the definition of the structure of the customer documentation in the project.

The customer documentation is structured as follows:

1. Loop over all modules to be generated

Here you can define which module information is generated.

2. Loop over all relations per module

Here you can define which relation information is generated.

3. Set the tables to be created in Word (Word tables) for each relation.

Here, you can define the number of Word tables and the header and footer for each Word table.

4. Specify for each Word table the rows to be contained in this table (attributes, in-dexes, foreign keys, constraint).

5. Specify the columns with headings for each Word table.

6. Specify the functions to be used for filling each cell of the Word table.



7. If required: Overwrite the cellular functions to adjust the contents of the cells to the project-specific requirements.

3.2.2.1 How to create the customer documentation

In order to generate documentation in the default.dbconv a documentation

block has to be created. This block contains the basic structure definition for the customer documentation.

In each configuration the output file name is set with the variable

outputfileCustomerHtmlDoku . If the variable contains an empty string no doc-

umentation is generated for this configuration. With the variable

documentationLanguage the language of the documentation can be set.

Note:

For column headings in a table containing more than one word all the words have to be combined with underscores. The underscores are re-moved during generation.

3.2.2.2 Defining the structure of the customer documentation

The output of the documentation is divided into 2 parts. In the first part you can view information about the module and/or the relation. In the second part Word tables with different information about relations, indexes, foreign keys and constraints are possible. All items can be displayed multiple times from different perspectives. The definition of the customer documentation structure is done in the file

default.dbconf and the section documentation .

Notes:

Tables that are empty in the documentation are not shown. For example, if a list of foreign keys is defined for a relation without foreign keys the documentation does not contain a foreign key list for this relation.

Semantic expressions are descriptions entered by means of the HTML editor as formatted text.



Figure 3: Example of a documentation definition

There are different levels by means of which information about the modeled data-base objects in the documentation can be shown. There are amongst others the pa-rameters generating the general information about the module and the table. This will be controlled by the following parameters.

Parameters: modulInformation

Tag Description

startLevel sets the initial level of the top level heading

This sets the heading level on which the generated HTML files have to be integrated into the main Word document.

modulComment displays the entered module comment

modulSemantik displays the entered module semantics

Table 1: All tags for module information

Parameter: tableInformation

Tag Description

tableComment displays the relation comment

tableSemantik displays the entered relation semantics



Tag Description

tableTechnicalName technical name of the relation

Table 2: All tags for relation information

You can also generate information about attributes and other objects in a relation creating several Word tables. These parameters are available for this selection.

Each Word table is defined by a name (used as Word table heading) followed by an opening curly bracket. Then you define the type of object to be listed. You can use the following keywords:

� printAttributes to list all attributes of the relation

� printIndexes to list all indexes of the relation

By defining the additional keywords pimaryKey or unique you can list only

the primary key index or only the unique indexes

� printForeignKey to list all foreign keys of the relation

� printConstraint to list all constraints of the relation

The keywords are followed by the definition of the Word table columns (also en-closed in curly brackets).

The closing curly bracket of the Word table definition must be followed by the man-

datory keyword tableDescription . This keyword is then followed by a descrip-

tion used as Word table footer. Here you can use the placeholder %name% for the

functional name of the relation.

The definition of the Word table columns has the following structure:

� a name, used as column heading

� one or more references to the provided functions

The output of these functions is generated in the cells of the Word table.

If a function name is followed by the keyword listing the output of this func-

tion is generated as a listing. This is recommended e. g. to list all attributes of an index.

The amount of provided functions is varying according to the listed objects.

Parameter: printAttributes

Function Description

commentDoku displays the attribute comment

semanticDoku displays the entered full semantics (attribute and data elements)

semanticAttrOnlyDoku displays the semantics entered directly at attribute lev-el




semanticDataOnlyDoku displays the semantics entered at the associated data element (including the semantics of the hierarchical parent data elements)

nameDoku functional name of the attribute

techNameDoku technical name of the attribute

dataTypeDoku name of the technical data type

dataTopTypeDoku top element of the assigned functional data element

dataDoku name of the assigned functional data element

dataTechFormatDoku technical format mapped to the output language

nullableDoku nullable information of the attribute

defaultValueDoku default value of the attribute

PKDoku indicates whether the attribute is part of the primary key

Table 3: All tags for attribute information

Parameter: printIndex


commentDoku displays the index comment

semanticDoku displays the entered index semantics

nameDoku functional name of the index

techNameDoku technical name of the index

indFieldlistDoku list of index attributes

Table 4: All tags for index information

Parameter: printForeignKey


commentDoku displays the foreign key comment

semanticDoku displays the entered foreign key semantics

nameDoku functional name of the foreign key

techNameDoku technical name of the foreign key

parentTableDoku parent table

fkFieldlistDoku list of attributes



Table 5: All tags for foreign key information

Parameters: printConstraint


commentDoku displays the constraint comment

semanticDoku displays the entered constraint semantics

nameDoku functional name of the constraints

techNameDoku technical name of the constraints

ConstraintBodyDoku language specific code text of the constraints

constraintFieldlistDoku list of attributes assigned to the constraint

Table 6: All tags for constraint information

3.3 Error messages for incorrect project settings

If projects are not created using the wizard you have to pay attention to the correct Eclipse project settings. Otherwise surprising validation messages may occur. Ex-amples are:

� messages about missing conventions although the file default.dbconv is

present and valid

� messages about duplicate default values and identical fully qualified name

� messages "Free Text not configured for language XY" directly to the existing definition for the language XY

One reason could be that copies of files are located in hidden folders (e.g. bin folder of a Java project).

In order to avoid such effects Eclipse projects used for the data modelling should be

as simple as possible. The file .projects should only contain the following entries.

<?xml version="1.0" encoding="UTF-8"?>

<projectDescription>

<name>de.ppi.basis.test.gen</name>

<comment></comment>

<projects>

</projects>

<buildSpec>

<buildCommand>

<name>org.eclipse.xtext.ui.shared.xtextBuilder</na me>



<arguments>

</arguments>

</buildCommand>

</buildSpec>

<natures>

<nature>org.eclipse.xtext.ui.shared.xtextNature</n ature>

</natures>

</projectDescription>

A file .classpath should not exist.

The project should only encompass the following files:

� .projects in the base directory

� files with captured data model information ( *.dbrel, *.dbdata, *.dbphysic, *.dbrel, *.ddldoc as well as project-specific extensions in

any directories)

� artifact files generated by the generator

� folder .svn for version management (or other equivalent folders according to

your versioning tool)

� .settings folder with Eclipse configuration files

It is particularly important to delete any existing bin folder with copies of files.



4 Create project-specific extensions

In principle, the base framework works immediately after installation without any ex-tension. It can, however, be adapted and extended according to the project-specific requirements.

The base framework of PPI data modelling offers the following adaptation possibili-ties:

� generation of project-specific artifacts

� adaptation of the content of data model documentations for customers

� extension of the structure of the DSL language with project-specific items

Note:

The following instructions install a project-specific language

ProjectRelation with the file extension prorel . This name can and

should be chosen in accordance with the naming conventions of your project. The manual does not emphasise at each point that the class, package, path, and other names are different according to the selected name in the project.

4.1 General preparation

The prerequisite is that the UDG are installed. The project-specific DSL should be in a separate workspace which is only used for this task.

At the same time, a separate installation of Eclipse is needed. This installation must be equipped with an installation of Xtext and the basic PPI feature. The project-specific Eclipse feature to be developed with this installation of Eclipse must NOT be installed. It is important to remember that Eclipse is both, the development platform as well as the target platform for which developments are made.

4.1.1 Check for correct Java version in Xtext

For the following tasks, it is extremely important to use the correct Java version (see Universal Data Modelling Generator User Manual [1]). Otherwise, errors may occur, whose messages do not clearly suggest that a wrong Java version is used. There-fore, check the following:

� Which Java version is used to start Eclipse? Enter java version in the com-

mand shell to check the standard version used in the operating system. At the

same time, check the file eclipse.ini of the Eclipse installation. Which ver-

sion of Java is configured there? Possibly the Java version is also contained in the Eclipse call with a link as a parameter (normally this setting is not part of a project file located in your versioning tool SVN).

Pay attention to use a 32 Bit Java version.

You can configure the used java version in eclipse.ini by adding a new

row -vm followed by a new row containing the full path to the correct

javaw.exe. These rows must be inserted in front of the parameter -vmargs .



You can check the loaded java version by Help->About Eclipse SDK->Installation Details->Configuration .

� Windows- >Preferences- >Java- >Installed JREs (normally this set-

ting is not part of SVN)

It is recommended to only install the required version of the Java. In any case the correct version has to be the only activated one.

� Windows->Preferences->Java->Compiler (normally this setting is not

part of SVN)

� in each project on Properties->Java Build Path->Libraries (normally

this setting is part of SVN)

No project-specific adjustment is recommended. Use the workspace settings as the default.

� in each project on Properties- >Java Compiler (normally this setting is

part of SVN)

No project-specific adjustment is recommended. Use the workspace settings as the default.

� in each project of manifest->Overview->Execution Environment (normally this setting is part of SVN)

� Run->Run Configurations->Main->execution environmen t for all

used Run Configurations (normally this setting is part of SVN)



4.1.2 The Xtend compiler settings

Select Window ->Preferences->Xtend->Compiler to perform the following

settings:

Figure 4: Xtend compiler settings

The deactivation of the options mark generated files as derived and

delete generated files, when clean build is trigger ed is neces-

sary to correctly manage the Java classes derived from Xtend classes with SVN.

Note:

SVN placeholders must always be entered as a single line comment in the header of an Xtend class, as otherwise the SVN revision number en-tered in Xtend is transferred to the corresponding Java class and then SVN becomes confused during the change analyzes of the generated Java class.

4.2 Derive a project-specific DSL from the UDG

You have to create your own project-specific DSL (generation language). The DSL created here does not change / extend anything to the UDG. It forms the basis for the changes described in the following chapters.

4.2.1 Create a Xtext Project

The following steps are required:

1. Create a new Xtext project (without selection Create SDK feature project ).



Figure 5: New XText Project

In this step, three new projects are created:

• the core project (without additional extension)

• the user interface project (with additional extension ui )

• the test project (with additional extension tests )

Note:

Do not select file extensions, for which editors in Eclipse (e.g. txt, xsd, java , etc.) already exist. This can lead to malfunctions in Eclipse.

2. Run the mwe2 file (folder src , package without additional supplement) via con-

text menu RUN AS -> MWE2 WORKFLOW.

CAUTION!!!

It is very strongly recommended not to manually perform the following changes. Use

the provided wizard 3.Generator extension project (create your own



Eclipse feature) instead. The changes described in the following pages (up to

page 34) then need not be done manually, but are used only for a better under-standing of the changes.

Figure 6: Wizard to create a project-specific extension

3. Remove the reference to plugin.xml in the header of an Xtend class.

Build.properties must have the following contents.

source.. = src/,\

src-gen/

bin.includes = META-INF/,\

4. Add the directory xtend-gen as source folder in the header of an Xtend class.

Build.properties must have the following contents.

source.. = src/,\

src-gen/,\

xtend-gen/

bin.includes = META-INF/,\

.,\

plugin.xml

5. Add the dependency to the basic DSL in the manifest of the core project.



Figure 7: Dependencies

6. For the new project *.ui add the dependency to

de.ppi.basis.ddl.relation.ui in the manifest.

7. Make the following changes in the file ProjektRelation.xtext (src folder,

package without additional supplement):

grammar de.ppi.project.model.projectrelation.ProjectRelatio n with de.ppi.basis.ddl.relation.Relation

generate projectRelation "http://www.ppi.de/project/model/projectrelation/Pr ojectRelation"

import "http://www.ppi.de/basis/ddl/relation/Relati on" as relation

Root returns relation::RelationModel:

RelationModel;

Greeting: 2

'Hello' name=ID ' ! ';

8. Add the following lines in the mwe2 file (src folder, package without additional

supplement).

Workflow {

bean = StandaloneSetup {

scanClassPath = true

platformUri = "${runtimeProject}/.."

2 This rule has to be specified for formal reasons. Otherwise an error message „generated

package may not be empty" is produced.



registerGeneratedEPackage="org.eclipse.xtext.xbase. XbasePackage"

registerGenModelFile="platform:/resource/org.eclips e.xtext.xbase/model/Xbase.genmodel" registerGeneratedEPackage = "de.ppi.basis.ddl.relation.relation.RelationPackage "

registerGenModelFile = "platform:/resource/de.ppi.basis.ddl.doc/model/Doc. genmodel"

registerGenModelFile = "platform:/resource/de.ppi.basis.ddl.convention/mod el/Convention.genmodel"

registerGenModelFile = "platform:/resource/de.ppi.basis.ddl.data/model/Dat a.genmodel"

registerGenModelFile = "platform:/resource/de.ppi.basis.ddl.physical/model /Physical.genmodel"

registerGenModelFile = "platform:/resource/de.ppi.basis.ddl.relation/model /Relation.genmodel"

}

9. Run the mwe2 file with Run As MWE2 Workflow .

10. Change the validation class ProjectRelationValidator.Xtend to inherit

all validations from the UDG. (src folder, package with additional supplement

validation )

package de.ppi.project.model.projectrelation.valida tion

import de.ppi.basis.ddl.relation.validation.RelationValida tor

class ProjectRelationValidator extends RelationValidator {

}

11. Inherit the formatting from the base class. Change the class

ProjectRelationFormatter.xtend (src folder, package with additional

supplement formatting ) as follows.

package de.ppi.project.model.projectrelation.format ting

import org.eclipse.xtext.formatting.impl.Formatting Config

import de.ppi.basis.ddl.relation.formatting.RelationFormat ter

import de.ppi.project.model.projectrelation.services.Proje ctRelationGrammarAccess

import com.google.inject.Inject

class ProjectRelationFormatter extends RelationFormatter {



@Inject extension ProjectRelationGrammarAccess f

override protected void configureFormatting(FormattingConfig c) {

super.formatStandard(c,f.relationGrammarAccess)

}

}

12. Inherit the formatting from the base class. Change the class

ProjectRelationScopeProvider.xtend (src folder, package with addi-

tional supplement scoping ) as follows.

package de.ppi.project.model.projectrelation.scopin g

import de.ppi.basis.ddl.relation.scoping.RelationScopeProv ider

class ProjectRelationScopeProvider extends RelationScopeProvider {

}

13. Create a feature project.

This project has the task to create an installable project-specific feature for Eclipse which contains the project-specific adjustments and can be installed as a feature in the Installation of Eclipse used for the "normal" project work (see section Providing features for Eclipse, page 35).

14. Create an update project.

The project has the task to provide the installable project-specific feature on a software update site for download. From this download site the project-specific feature can be installed in the Eclipse used for "normal" project work (see sec-tion Providing features for Eclipse, page 35).

4.2.2 Test the project-specific DSL

The created project feature has to be installed in the Eclipse installation used for the "normal" project work. The installation is similar to that of the basic features.

Then create a new file with the extension prorel in the workspace, which is used

for the modelling of the data model using the context menu New- >File . Register

a test relation for testing in this file. Check the validation functionality by using wrong

definitions and call the Format by the context menu Format.

After the error-free registration of the test relation create a generation file for the as-

sociated module with the ending dbrel (not the project-specific extension). Test

the generation of an artifact.

If the test was successful, delete the test file and rename all existing model files with

the extension dbrel as the extension prorel by using the context menu

Refactor- >Rename .

Caution:

Do not change the extension dbrel of the generation files.



As the result your project works now with a project-specific DSL which, however, does not contain any adjustments to the UDG yet.

Note:

After the migration to a new version of the PPI basic features the project-specific DSL must be adapted to the new environment. To do so, you have to re-run the MWE2-Workflow of the project-specific DSL.

4.3 Create project-specific generators

In order to create additional project-specific artifacts generators can be added. The generation files then generate the artifacts provided by the basic PPI feature and any kind of defined project-specific artifacts.

For this purpose the following adjustments are needed:

1. Change the method doGenerate in the class

ProjectRelationGenerator.Xtend (src folder , package with additional

supplement generator ) as follows:

Public void doGenerate(resource input, IFileSystemA ccess fsa) {

FSA.generateFile( "README.TXT", "This is a proj ect-specific file" );

}

README.TXT is the name of the file to be generated. this is a project-specific file is the content to be written to the file.

Note:

In order to create meaningful content the base framework provides a va-riety of methods by means of which relatively simple properties of the data model can be queried (see section Public interface for project-specific generators, page 38.

Generators should in principle be created in the Xtend notification.

2. Define in the manifest of the Editor project (*.UI ) an extension for

de.ppi.base.ddl.relation.ddlGeneratorExtension entry and speci-

fy the changed Xtend class ProjectRelationGenerator .

The class name must be preceded by de.ppi.project.model.projectrelation.ui.ProjectRela tionExecutableExtensionFactory separated with a colon. Otherwise the public

methods of the base classes accessed by Google Inject are not available.



The plugin.xml contains the following entry:

<extension

point="de.ppi.basis.ddl.relation.ddlGeneratorExtens ion">

<generator

class="org.xtext.ePack.mydsl.ui.MyDslwExecutableExt ensionFactory:org.xtext.ePack.mydsl.generator.MyDslwGenerat or">

</generator>

</extension>

Note:

When entering the extensions mistakes may easily be made. In this case, no result is presented (there is no corresponding error message). It is therefore recommended to highlight the class and select the CLASS * link on the right-hand side to check whether the class exists. By marking the extension and selecting the FIND DECLARING EXTENSION POINT link you can check whether the extension point exists.

If project-specific generators and/or adjustments to the customer docu-mentation exist during generation a note in the console output is creat-ed. If this note is missing, the integration by means of the extensions is incorrect.

3. Set the workspace properties for the Xtend Compiler by window- >Preferences set.3

3 If you forgot to perform this step at the start of the project, the files from the Folders Xtend-gen

are not included and updated in SVN. You often get mistakes in Eclipse and subversion because

after a SVN update only the files *.Xtend in the src folder are updated, but not the derived clas-

ses in Xtend-gen folder. These classes are also not updated if you clean the whole project. In

this case, you have to manually remove the property derived for all existing Java classes in

Xtend-gen . It is also possible to remove the folder Xtend-gen and to get the files (provided by

another team member) from SVN by Update and Override .



Figure 8: Workspace properties

4. Implement the desired content of the generator.

5. Re-create the project features and deploy the download on the Update site (see section Providing features for Eclipse, page 35).

Recommendation

Project-specific generators will usually need additional configuration properties in the generation files. A typical example would be the name of the generated project-specific output file. Therefore, it is recommended to define additional configuration

properties in the conventions under the tag projectConfiguration . Use these

additional properties to define artifacts in the generation files.4

4.4 Project-specific extension of the DSL structures

The project-specific extension of the DSL structure allows to register more infor-mation and to use this additional information in project-specific generators. In the

example a project-specific property sequenceId is added for an attribute of a rela-

tion.

Steps to create the example

1. Add the following in the File ProjektRelation.xtext :

AttributHook:

4 This is not yet an extension of the DSL structure of the Eclipse UDG.



ProjectAttributProperty

;

ProjectAttributProperty returns: AttributProperty

{ProjectAttributeProperty}

("sequenceId" sequenceId=[relation::Sequence|QualifiedName)?

( " #" comment=String) ?;

The individual lines have the following meaning:

• The language element AttributHooK defined in the UDG is re-defined.

The new definition is ProjectAttributProperty .

• ProjectAttributProperty is a class derived from the ECore class

AttributProperty and defines a new ECore class ProjectAttributeProperty .

• The keyword sequenceId (the question mark must be at the end) can be

optionally followed by a reference to an object of type Sequence which is

defined in the base language relation (the reference to be entered using

a full a qualified name).

• The line ("#" comment=String)? corresponds to the definition of the

AttributProperty in the base language relation and must be re-

peated here.

2. Run the mwe2 file with Run As MWE2 Workflow .

3. Re-create the project features and deploy the download on the update site (see section Providing features for Eclipse, page 35).

4. Now the added project language is ready and should be tested.

For all objects in the UDG which have a comment (indicated by #) "hooks" exist to perform project-specific extensions. The original definition of comments must always be repeated in the project-specific expansions. This definition of a comment is iden-tical for all hooks and can be taken from the example above.

There are the following hooks in the UDG:

Language element

Base Class

Purpose

DataHook

DataProperty

refers to the language dbdata (not dbrel ) and

allows extensions to functional data elements

RelationHook

RelationProperty

extensions for relations



Language element

Base Class

Purpose

IndexOrForeignKeyHook

IndexOrForeignKeyProperty

extensions for primary keys, indexes and foreign keys

All extensions made here are always used for all three object types because the common base class of primary keys, indexes, and foreign keys are extended.

SequenceHook

SequenceProperty

extensions for sequences

AttributeHook

AttributeProperty

extensions for attributes of relations

ModulHook

ModulProperty

extensions for modules

TriggerHook

TriggerProperty

extensions for trigger of relations

ConstraintHook

ConstraintProperty

extensions for freely definable constraints of rela-tions

ProjectConfigurationHook

ProjectConfiguration

project-specific configuration parameters to extend generation files

In contrast to all the other extensions the project-

specific change does not need to include the line ( " #" comment=String)?

The definition of this hook in the UDG is empty.

This hook is not recognizable by a # character.

The hook precedes the block

generationModules of a generation file and is

invisible.5 6

Table 7: All possible hooks

4.5 Project-specific adaptations of the documentation

There is a possibility to adapt the documentation as required. The basic feature pro-vides functions (see section Defining the structure of the customer documentation, page 12) which can be overwritten by the project. The methods are located in the

Java class HtmlDocumentationGeneratorMethods .

The names of the methods are as follows:

5 In the unchanged UDG components you can enter hook project config here. However this

has no impact on the generation. 6 Before using this hook please check if you can meet your requirements by defining additional prop-

erties for generation files using the tag projectConfiguration in default.dbconv .



<Parameter>_<function>

Example:

The method to output the nullable property of an attribute is

PrintAttributes_NullableDoku . Almost all methods have a

Configuration , a (output language) Language , a (documentation

language) DocLanguage and the Object in question (Attribute, Constraint, Index or ForeignKey ) as parameters. The method

PrintAttributes_NullableDoku looks is called as follows:

PrintAttributes_NullableDoku(config, long, docLang, att)

Some of the methods have an expanded list of parameters. In addition to the al-ready mentioned parameters you have to pass a Boolean value that indicates whether the cell is to be displayed as a list or in a row. These methods are:

� PrintForeignKey_FkFieldlistDoku

� PrintIndexes_IndFieldlistDoku

The method PrintIndexes_IndFieldlistDoku must be called as follows:

PrintIndexes_IndFieldlistDoku(config, long, docLang , att, list)

The following is an example of an Xtend-Class to override a method:

class ProjectHtmlDocumentationMethods extends HtmlDocumentationGeneratorMethods {

@Inject private extension PublicExtensions

override String printAttributes_NullableDoku(Configuration config, Language lang, DocLanguage 7 docLang, Attribute att) {

var result = "" as String

if (att.prjNullable(config)) {

result = "nullable"

} else {

result = "not null"

}

return result

}

}

The created class must be registered as an extension.

7 Pay attention to the correct import. You have to use the class

de.ppi.basis.ddl.doc.doc.DocLanguage



To do this, create an extension for the entry point

de.ppi.base.ddl.relation.htmlDocumentationGenerator Methods and specify the Xtend class ProjectHtmlDocumentationMethods in the manifest of

the Editor project (*.UI) .

The class name must be preceded by de.ppi.project.model.projectrelation.ui.ProjectRela tionExecutableExtensionFactory separated with colon. Otherwise the public methods of

the base classes accessed by Google Inject are not available.

Figure 9: Extensions

The resulting plugin.xml contains the following entry.

<extension

point="de.ppi.basis.ddl.relation.htmlDocumentationG eneratorMethods">



<htmlDocuMethods

class="org.xtext.ePack.mydsl.ui.MyDslwExecutableExt ensionFactory:org.xtext.ePack.mydsl.generator.ProjectHtmlDo cumentationMethods">

</htmlDocuMethods>

</extension>

Note:

When entering the extensions mistakes may easily be made. In this case, no result is presented (there is no corresponding error message). It is therefore recommended to highlight the class and select the CLASS * link on the right-hand side to check whether the class exists. By marking the extension and selecting the FIND DECLARING EXTENSION POINT link you can check whether the extension point exists.

If project-specific generators and/or adjustments to the customer docu-mentation exist during generation a note in the console output is creat-ed. If this note is missing, the integration by means of the extensions is incorrect.

4.6 Recommendations for project-specific extensions

If project-specific generators or hooks for project-specific adjustments to the cus-tomer documentation are part of separate packages, you have to add these pack-

ages to the manifest of the core project on the runtime tab.

Figure 10: Adding packages to the manifest



4.7 Recommended test when using the wizards

If the Java projects for the development of project-specific features have been cre-

ated using the wizard 3.Generator extension project the following tests are

recommended:

� Start the Eclipse test environment for the project-specific feature by calling Run- >Run Configurations- >RunTestProjectspecificGe nerator from the Eclipse development environment.

� Create a test project suitable for the just created project-specific feature in the

test environment by using the wizard 4.Datamedelling extension

example .

Figure 11: Wizard to test project-specific extensions

� Edit the test project.

In addition to the basic functions of the PPI data modelling, you can assign a sequence to an attribute here.

� Generate the artifacts.

Auditable project-specific changes are:

• Additional files ora_project.csv and db2_project.csv containing short data model documentation suitable for Excel are generated. The files contain in-formation about sequences assigned to attributes.

• In the html customer documentation for the not-NULL property the descrip-

tions not null and nullable are issued instead of Wert optional

and Wert Pflicht .

• Notes on the console are issued during generation.

Note:

Before you adapt the development and the test environment for project-specific generators created by the wizard to the concrete project needs read pages 20 to 34. It is important to get a better understanding of the code created by wizards.



5 Providing features for Eclipse

5.1 Tasks to be performed once

The tasks to be performed once are not required when using the wizard

3.Generator extension project .

Otherwise open the below screen and perform the following steps:

Figure 12: Providing features for Eclipse

1. Open the file manifest.mf of the core and the UI project DSL.

2. Add the keyword qualifier to the field version (entry must be e.g.

x.y.z.qualifier ).

3. Modify the name of the vendor.

4. Create a feature project New->project->Plug-in Development->Feature Project .

5. Open the created file feature.xml .

6. Enter the project properties (version number with keyword qualifiers ) on

page Overview .

7. Select the associated projects on page Plug-ins . You have to select the core

project and the UI project. (Maybe further projects used in the programming of

the project-specific DSL are necessary).

8. Select COMPUTE on the Dependencies page.



9. Create an update project New->project->Plug-in Development->Update Site Project .

10. Assign a name to the update project.

11. Open the file site.xml and assign the created feature.

12. Create an ant file build.xml with the targets clean (deletes all temporary

files in the update project), publish (deploys a new version of a feature to the

official update site) and publishBeta (deploys a new version of a feature to a

special beta update site for testing purposes).

Note:

When you create the features in the update project later a relatively great number of files is created. Whether these temporary files must be versioned in the SVN is at the discretion of the administrator. Only the

files site.xml and build.xml have to be versioned in any case.

5.2 Regular tasks

5.2.1 Create and deliver the features

1. If a new version of the UDG is used, re-run the MWE2 workflow of the project-specific DSL

2. Correct the version number in

• the manifests of the associated Core and UI projects of the project-

specific DSL

• the file feature.xml of the feature project

• the file site.xml of the update project

3. in the feature .xml of the feature project

• Customise the description.

• Explain briefly the new functions of the version.

4. Start the ant target clean in the build .xml of the update project.

5. Press the Build All Button in site.xml of the update project.

If nothing happens just delete the associated feature and re-add the feature.

6. Start the ant target publishBeta in the build .xml of the update project.

publishBeta provides the feature temporarily under an update site not shared

with all users. This update site is used by the Administrator to test feature ver-sions which have not been definitively finished.

7. Install and test the newly created beta feature (see Universal Data Modelling Generator User Manual [1]).

8. Start the ant target publish in the build .xml of the update project.

publish provides the current feature version to all users for installation and

should be used only after a successful beta test. At the same time, the feature



is available at a separate archive update site and permanently backed up there.8

8 These older versions will be required for example, if you need to work with old versions of the pro-

ject-specific features on a branch of your code



6 Public interface for project-specific generators

This section gives recommendations how to best realise the project-specific re-quirements.

6.1 Objective

It is the aim of the UDG to provide a simple API for project-specific generators. It is intended to accomplish the following:

� For project-specific generators, inheritance is not an issue. For all required properties there is an access method, which returns the net value of the proper-ty taking into account all possible inheritances.

� The treatment of null-pointer exceptions is not necessary in the generators since the access methods for fully validated model files never return NULL.

� The API has a uniform parameter structure for all methods.

� Common functionalities are already provided by the API.

Examples are

• the mapping of the attribute format to a data type of the project-specific language (this could be a Java class)

• the access to project-specific conventions

� If possible, the parameter structure of the API remains constant over different versions of the UDG.

This is to keep the change effort for project-specific generators during an up-grade of the version of the UDG as low as possible.

6.2 Implementation

The UDG supply the class

de.ppi.base.ddl.publicextensions.PublicExtensions . This class pro-

vides all available methods of the API.

Use this class in a project-specific generator by means of Google Inject.

import com.google.inject.Inject

import de.ppi.base.ddl.publicextensions

class projectclass {

@inject private extension PublicExtensions

As a result, all objects relevant for generators have additional methods. These methods have the following properties.

� The first parameter is the object which an additional method has to be assigned to.

� The second parameter is of type Configuration and corresponds to the data

collected in a generation file for the language-specific configuration of the arti-facts.



• This second parameter is omitted if already the first parameter is of type

Configuration .

• Some methods have additional parameters.

� The name of the method always begins with prj .

� The methods provide always net values of properties, i.e.

• They take into account inheritance rules.

• They do not return any null values.

Except null is a correct value; for instance if an attribute has no default val-ue the corresponding method returns null.

� They take into account any existing deactivations.

Examples:

• If the creation of indexes is disabled in the configuration the query of the in-dexes of a relation returns an empty set.

• If the creation of the indexes is disabled for a foreign key the query of the indexes of the relation does not return this index.

See also the Java documentation for a detailed description of the available methods.

6.3 Examples for project-specific adaptations

An example of a project-specific generator is available if the wizard New->Other->PPI Data modelling->3.Generator extension project (create your own Eclipse feature)

This example demonstrates the following features:

� adding additional information to the DSL structure

� creating a project-specific generator

• create an csv file with a brief data model documentation usable in Excel

• create a list of necessary changes for a database migration

• create Java classes for the data model (planned in future versions of the basic components)

� customizing the methods used for a customer data model documentation

� creating and deploying a project-specific Eclipse feature

By means of the wizard New->Other->PPI Data modelling->4.Datamodelling extension example (use your own Ec lipse feature) you can create a small data model to test the project-specific extensions.

6.4 Recommendations

It is recommended that project-specific generators use the Xtend language. This language is specifically designed for this purpose. It allows you to create specific ar-tifact of any kind quickly with very clear code.



Typical generator code

A project-specific generator will proceed as follows:

class ProjectRelationGenerator implements IGenerato r {

Inserting the UDG of the methods in the API by Google Inject

@Inject extension PublicExtensions

override void doGenerate(Resource resource, IFileSy stemAccess fsa) {

Accessing the current generation file

val genmodel = resource.contents.get(0) as Relatio nModel

Iteration over all defined configurations of artifacts

prjGetDbDonfiguration provides configurations only for database languages

prjGetConfiguration provides all configurations

prjGetprojectConfiguration provides configurations only for project-specific

languages

for(config: genmodel.prjGetDbConfiguration) {

Setting the name of the output file

Is read from a project-specific additional configuration property

val file=Conf.prjConfigurationProjectProperty( "excelFile") as String

Initializing the file content with a SVN Header (optional)

var result=prjGenerateSvnHeader(config) as strin g

Iteration over all modules to be generated

for (module :genmodel.prjGetGenModules) {

Iteration over all relations to be generated

for (rel :module.prjRelations(config)) {

Generating the necessary file content for each relation

result=result.concat( project function generating

code for one relation)

}

}



Writing the artifact file

fsa.generateFile(file, result)

}

}

}


Approved Universal Data Modelling Generator - Administration

Urgent Warnings

It is also technically possible to access the object methods which were automatically generated by Xtext. But it is strongly advised not to do so. These methods only re-turn actually entered values and do not take into account any inheritances. At the same time, the names and parameters of these methods may change without any notification due to changes in the UDG.

Recommendations on how to write a project generator

It is recommended to proceed as follows:

1. Create manually an example of the code to be generated and test this code.

2. Create an Xtend method which returns this example code as a constant output.

3. Create the required loops (see section Typical generator code, page 40) and write the artifact file to the file system.

4. Test the generation.

It is expected that now the constant text is generated per relation.

5. Edit the Xtend Method.

• Replace attribute and relation names, formats etc. with the proper calls of

the prj methods provided by the UDG

• Insert loops over attributes, indexes etc.

6. Test the finished artifact.

This approach has the advantage that you can generate intermediate versions at any time thus getting results very quickly.



7 Migrations

7.1 Installation of updates

By means of Help- >Check for Updates the updated feature can be installed.

This is identical to a new installation procedure.

If the version number changes only in the patch level (third position), no further work is necessary.

Otherwise perform necessary changes to model files and project-specific generators as described in the following sections. Normally these changes have to be made on-ly once by the administrator. The administrator provides the changes for the other team members in the versioning tool.

For each new version the value for versionBase in the file default.dbconv has

to be changed to the current version.

For project-specific generators or structurally extended DSL you have to restart the MWE2 workflow and to provide a new version for the project-specific feature.

7.2 Version 3.3.0

If you generate code for Oracle and have used the keyword compress you have to

change this keyword to compressLow or compressNormal .

� compressLow generates the COMPRESS BASIC clause

In this case you do not need an additional license but the compression is only working for insert commands with the append hint.

� compressNormal generates the COMPRESS FOR OLTP clause

In this case you have to license the Advanced Compression Option in Oracle



8 ANNEX

8.1 Description of setting parameters

This section describes all required parameters of the individual settings. The com-pleteness and partially also the order of the parameters is to observe. This is verified by the Xtext language itself and by validation rules. As long as errors in the default files are detected it is not possible to generate anything.

Note:

Correct errors from top to bottom. Messages of consequential errors can be very confusing.

All file contents start always with a package name. This name can be set by the pro-ject. The packages are followed by the imports. They are based on the dependen-cies to the packages.

Note:

The files should be adapted in the specified order. Start with the adapta-tion of the following file(s) only if the validation of the currently edited file reports no errors.

8.1.1 Convention Parameters

In the file default.dbconv all default parameters for the entire project are defined.

Parameters of the file default.dbconf

Parameter Tag Tag value Description

projectName - - Freely selectable name of the project

Is written in each SVN-header

versionBase - - Version of the Xtext basic com-ponent

have to match the version of the installed version of the UDG

versionProject

- - Version of the project

Can be used by project-specific generators to check if the ver-sion of the installed project-specific feature is matching.

fileHeader - - This parameter configures the file header.

TimestampInHeader

- There is a timestamp in the SVN-generated header.




noTimestampInHeader

- There is no timestamp in the SVN-generated header.

srcInHeader

- With this optional parameter the default SVN-parameter in the file header can be overwritten.

copyRightInHeader

- With this optional parameter the default copy right information in the file header can be overwrit-ten.

dataTypes - - Technical data types can be defined for the project. The defi-nitions are freely selectable.

inheritance - - Controls the behaviour of prop-erties inherited from data ele-ments to attributes. The inher-itance rules have to be specified for all of the properties of the data elements

overwrite - The property in the inheritance hierarchy can be overwritten at any point.

useInData - The property can be used for data items.

useInRelation

- The property can be used for attributes.

migration - - Defines the default name of the output files for documentation and DDL scripts for database migration scripts

Allowed wildcards are

%language% for the name of

the database language.

%modelfile% is the name of

the generation file used to gen-erated the data

%lfdNr% for a serial number,

which is necessary, if there are multiple configurations in the same generation file for the same database language




ddlUser Migration file for synonyms, alias and grant commands

If no entry is made the following applies

migration/ddl/%language%/%modelfile%_%lfdNr%_user.sql.sql

ddlTrigger Migration file for trigger com-mands


migration/ddl/%language%/%modelfile%_%lfdNr%_trigger.sql

ddlStep1 Migration file for DDL com-mands before the functional content migration


migration/ddl/%language%/%modelfile%_%lfdNr%_step1.sql

ddlStep2 Migration file for DDL com-mands after the functional con-tent migration



ddlStep3 Migration file for final DDL com-mands of the migration






fullDocumentation

Name of the full HTML-migration documentation


migration/docu/%language%/%modelfile%_%lfdNr%_Full.html

DeltaDocumentation

Name of the Delta HTML migra-tion documentation which con-tains all changes found


migration/docu/%language%/%modelfile%_%lfdNr%_Delta.html

manuellDocumentation

Name of the manual HTML mi-gration documentation which contains changes to be migrated manually


migration/docu/%language%/%modelfile%_%lfdNr%_Manuell.html

projectConfiguration

- - Optional definitions of the names of additional configura-tion properties which may be entered in generation files

These additional properties can be used by project-specific gen-erators.

void Name of the additional configu-ration property of the generation

(e.g. excelFile to register the

name of the artifact file generat-ed project-specifically)

useProjectspecific

Optionally

If specified, the additional con-figuration property can be used and is mandatory for project-specific output languages.




useDatabase

Optionally

If specified the additional con-figuration property can be used and is mandatory for database output languages

documentation

- - For the creation of the documen-tation and interpretation of pa-rameters (see chapter Defining the structure of the customer documentation, page 12).

language - With the keyword language

different output languages are defined. This may be one of the database language provided by the UDG or a specific language

with any name (e.g. Java) .

conventions

Within this tag the conventions for all database objects are de-fined specific to the output lan-guage. In addition, there is an

object project for project-

specific definitions.

sequence name

Technical name of the sequence to be generated. May include wildcards

nameAutoIDSequence

Name of the sequence for au-tomatic ID's

Only for Oracle and Post-GreSQL.

nameAutoIDTrigger

Name of the trigger for automat-ic ID's

For Oracle use only

length

Maximum length of the technical name.




table name

Technical name of the relation to be generated. May include wild-cards

length


transactionsOracle

Number of transactions for which a simultaneous block ac-cess is guaranteed. For Oracle use only

foreignKey name

Technical name of the foreign key to be generated. May in-clude wildcards

length


foreignKeyIndex

name

Technical name of foreign key index to be generated. May in-clude wildcards

primaryKey name

Technical name of the primary key to be generated. May in-clude wildcards

length


index name

Technical name of the index to be generated. May include wild-cards

length


uniqueIndex name

Technical name of the generat-ed unique index to be generat-ed. May include wildcards




sqlParms sqlDelimiter

separator between 2 SQL statements

stringDelimiter

separator used to enclose strings

decimalPoint

decimal point used (a point or a comma)

attribute name

Technical name of the attribute to be generated. May include wildcards

length


tablespace length


trigger name

Technical name of the trigger to be generated. May include wild-cards

length


triggerDelimiter

Delimiter of the trigger (last sign of the command to create a trig-ger)




constraint name

Technical name of a relation constraint (enter in the section

constraints of a relation)

May include wildcards

nameCheckConstraint

Technical name of an attribute constraints (enter for a data el-ement or attribute after the key-

word check )

May include wildcards

length


Note: If the technical name of an attribute constraint (keyword

check ) exceeds the maximum

length for a of the name is built as:

CHECK_<hash value of the

technical name>

project For project-specific output lan-guages you can define any

number of pairs name<->value . This can be used by

project-specific generators.

mappings - Mapping of the technical data types (defined in the project) to the data types of the target da-tabase or project-specific lan-guage. This is necessary for all of the defined technical data types.

transformations

- Functions used to convert en-tered values into the correct database format (e.g. to_date(%value%,'YYYY-MM-DD') )

May include wildcards.

Specifying these values is op-tional

Table 8: List of all Convention parameters for default.dbconv



In addition of conventions for the database languages supported by the UDG also project-specific output languages can be defined here. For example, it is possible to

define a Java language and to configure how technical data types can be mapped

to Java classes with the help of mappings. A project-specific generator can deter-mine the correct Java class for each attribute using simple calls to methods provided by the UDG. The generator does not need to implement this itself.

During validation all placeholders %additionalTable% (see property

additionalFields in the generation files described in the User Guide) are re-

placed by an empty string. If you are planning to use additional tables it is your task, to guarantee, that the technical name including the replaced placeholders

%additionalTable% is not too long. It is recommended to set the convention

length smaller than allowed by the database.

example:

You are using the name convention %name%%additionalTable%. All

your additional tables have a technical name with 3 characters. You

should define the length convention for oracle as length = "27" . In

this case you get an error generated by validation if the technical name of the “normal” relation exceeds 27 characters. The technical name of the relation including the additional fields can’t exceed 30 charac-ters.(maximum length allowed in an Oracle database)

8.1.2 Capture of free text

For certain database objects freely programmable code is required. The code syntax can differ significantly in the different databases.

This applies to:

� Program code in check conditions of check constraints (both relations and at-tribute-related constraints)

� Program code in trigger bodies

� Program code in function-based indexes

In order to intercept these syntactical differences free texts were created.

For each type of program code with certain functionality a free text is created repre-senting this functionality. The free text has a code window for each language used in the project. Here you can enter the database-specific code for the implementation of this functionality.

When using free texts always a list of attributes is transferred. The technical names of these attributes can be referenced in the code window with the wildcards

%field1% %field2% ... .

One possible scenario for free text is, for example, the definition of function-based index for Oracle.

The free texts are defined in the file default.dbconv . Following free texts are al-

ways required:

� default free text with the name default



� free text with the following inputs for scope

• index

• constraint

• trigger

Properties of free text


freeTexts Defines an area for free text entries

name - Name of the free text

scope Specify the type of object for which the text is to be used. Possible values are index, triggers, and

constraint .

dbms - Database language, for which the pro-gram code is entered

This tag repeats for each defined lan-guage

{} properties to be defined for each data-base language are enclosed in curly brackets

inactive If this keyword is specified for a data-base language, the free text for that language is not used. This can be use-ful when individual databases do not offer the functionality.

“Text“ The actual database-specific code of the free text with wildcards

Table 9: List of all the properties of free text

8.1.3 Default data elements

All technical data types (defined in default.dbconv ) have to be assigned to func-

tional default data elements. Usually this is done in a file default.dbdata . You

have to start with a general default data element with the name default . All other

default data elements are arranged hierarchically under this general default data el-ement. You have to define such a sub data element for each defined technical data type (see conventions).

The exact list of all properties of functional data elements is included in the Univer-sal Data Modelling Generator User Manual [1].

For default data elements all properties are mandatory. The only optional inputs are

the property autoID (whether or not it is automatically generated ID) as well as the

property def ( sets the default value for an attribute).



If the property autoID is specified all sub-properties are mandatory.

8.1.4 Tablespace parameters / default tablespace

You have to define at least one default tablespace with the name default .

This is usually done in the file default.dbphysic.

Further tablespaces you can define in any file with the file extension dbphysic.

The following items are mandatory for each tablespace:

� a definition for each database language defined in the conventions

� the properties technicalNameData and technicalNameIndex

All other properties can be inherited from the default tablespace. You can of course overwrite the properties.

The default tablespace has additional mandatory properties. Which properties are mandatory depends on the database language. Especially for DB2 almost all prop-erties are mandatory.

Tablespace parameters

Parameter Tag Tag value Mandatory property in database

Description

tablespaces

- - Parameters defining the tablespaces sec-tion

name - Name of the defined Xtext tablespace

dbms - all defined databases

Database language

You have to define the properties for each database lan-guage defined in

default.dbconv .

technicalNameData DB2 LUW

DB2 z/OS

Oracle

Post-GreSQL

Technical name of the data tablespace

May include wildcard %table%

technicalNameIndex

DB2 LUW

DB2 z/OS

Oracle

Post-GreSQL

Technical name of the index tablespace





Description

technicalNameLob DB2 LUW

DB2 z/OS

Oracle

Technical name of the Lob tablespace (large objects).


db2PageSize DB2 LUW

DB2 z/OS

Pagesize of the ta-blespace

db2LuwTsManagement

DB2 LUW An indication how the tablespace is man-aged by the database

(automaticstorage, database or

system )

TsPathData DB2 LUW

Post-GreSQL

Path to the data ta-blespace

TsPathIndex DB2 LUW

Post-GreSQL

Path for the index tablespace

TsPathLob DB2 LUW Path for the Lob ta-blespace

db2NumberTsFiles DB2 LUW Number of tablespace container for SMS tablespace

db2TsInitialSize DB2 LUW Initial size of the ta-blespace container in MB

db2TsIncreaseSize DB2 LUW Increase of the table-space container in MB when using db2AutoResize

db2TsMaxSize DB2 LUW Maximum size of the tablespace container in MB

0 = unlimited




Description

db2AutoResize DB2 LUW

DB2 z/OS

Tablespace contain-ers increase automat-ically.

For DB2 z/OS a parti-tion by Growth UTS Tablespace is gener-ated.

db2NoAutoResize DB2 LUW

DB2 z/OS

Tablespace contain-ers do not increase automatically.

db2BufferpoolData DB2 LUW

DB2 z/OS

Bufferpool for data

db2BufferpoolIndex

DB2 LUW

DB2 z/OS

Bufferpool for indexes

db2BufferpoolLob DB2 LUW

DB2 z/OS

Bufferpool for lobs.

db2StoragegroupData

DB2 LUW

DB2 z/OS

Storage group for data

For DB2 LUW only as of version 10

db2StoragegroupIndex

DB2 LUW

DB2 z/OS

Storage group for indexes

For DB2 LUW only as of version 10

db2PctFree DB2 LUW

DB2 z/OS

Percentage Free space within a page

db2ZosMaxpartitions

DB2 z/OS Number of partitions the tablespace can grow.

db2ZosDssize DB2 z/OS Specifies the maxi-mum size (in giga-bytes) for each parti-tion

db2ZosFreePage DB2 z/OS Specifies how often a blank page is gener-ated.

db2ZosLockmax DB2 z/OS Defines the limits a transaction for a lock escalation




Description

db2ZosLocksize DB2 z/OS Specifies in which level locking is done

db2ZosCcsid DB2 z/OS Defines the Character Set of the tablespace

db2ZosClose DB2 z/OS Determines whether files are closed when the access is no longer

db2ZosDBName DB2 z/OS Name of the data-base

db2ZosMaxRows DB2 z/OS Maximum number of lines in a page

db2Compress DB2 z/OS Determines whether the contents of the tablespace is com-pressed

mssqlFillFactor MS SQL Percentage free space of each leaf page

mssqlIndexPad MS SQL Percentage free space of each non leaf page

mssqlDatabase MS SQL Name of the data-base

partitions - - - Is not used yet

name - -

dbms - -

Table 10: List of all tablespace parameters

Pay attention to the difference between an Xtext tablespace and a technical table-space in the database.

An Xtext tablespace represents a tablespace definition. If you are using the wildcard

%table% as technical tablespace name different tablespaces in the database are

generated. Especially in DB2 it is common to create a separate tablespace for each relation.

8.1.5 Default relation and sequence

You have to define the default properties for all the relation objects and sequences.



Usually this is done in a file default.dbrel .

The following default objects are required:

Object Recognizable by

Sequence Name of the sequence is default

Relation Name of the relation is default

Index General The first index of the default relation

All indexes inherit their properties from this index

Primary Key

Unique Index

Non-unique index

Primary key of the default relation or first unique or first non-unique index of the default relation

Is only used to inherit the comment property

Foreign Key First foreign key default relation

Constraint First constraint default relation

Trigger The first trigger default relation

The exact list of all properties of relations and sequences is included in the Univer-sal Data Modelling Generator User Manual [1].

For default objects all properties are mandatory.

Attributes of the default relation have no impact on the inheritance. The only reason to define some attributes is that you cannot define indexes, foreign keys, etc. without some references to attributes.



Bibliographical reference

[1] Universal Data Modelling Generator User Manual Version 3.3.0 PPI AG Informationstechnologie



List of figures

Figure 1: Wizard to create an initial data model project ............................................ 9

Figure 2: Properties of the Xtext project ................................................................. 10

Figure 3: Example of a documentation definition .................................................... 13

Figure 4: Xtend compiler settings ........................................................................... 20

Figure 5: New XText Project ................................................................................... 21

Figure 6: Wizard to create a project-specific extension ........................................... 22

Figure 7: Dependencies ......................................................................................... 23

Figure 8: Workspace properties.............................................................................. 28

Figure 9: Extensions ............................................................................................... 32

Figure 10: Adding packages to the manifest ............................................................. 33

Figure 11: Wizard to test project-specific extensions ................................................ 34

Figure 12: Providing features for Eclipse .................................................................. 35



List of tables

Table 1: All tags for module information ................................................................ 13

Table 2: All tags for relation information ................................................................ 14

Table 3: All tags for attribute information ............................................................... 15

Table 4: All tags for index information ................................................................... 15

Table 5: All tags for foreign key information........................................................... 16

Table 6: All tags for constraint information ............................................................ 16

Table 7: All possible hooks .................................................................................... 30

Table 8: List of all Convention parameters for default.dbconv ......................... 51

Table 9: List of all the properties of free text .......................................................... 53

Table 10: List of all tablespace parameters ............................................................. 57

Universal Data Modelling Generator · PDF file4.1.1 Check for correct Java version in Xtext...

Documents

Transcript of Universal Data Modelling Generator · PDF file4.1.1 Check for correct Java version in Xtext...