GeneSEZ Handbook for JavaEnterprise Development

Draft Draft

GeneSEZ Handbook for Java Enterprise DevelopmentCopyright © 2006 - 2011 GeneSEZ Research Group

Draft Draft

iii

Table of Contents1. Java Enterprise Development ................................................................................................................... 1

1.1. Java Persistence API (JPA) ........................................................................................................... 11.1.1. Persistent Entities ............................................................................................................... 11.1.2. Entity Identity with Primary Keys ......................................................................................... 21.1.3. Optimistic Locking and Concurrent Access ........................................................................... 21.1.4. Entity Manager and Entity Manager Factory References ....................................................... 21.1.5. Inheritance ......................................................................................................................... 21.1.6. Associations and References between Entities ..................................................................... 21.1.7. Naming of Table and Columns ............................................................................................ 21.1.8. Get and Set Methods (Accessors) ....................................................................................... 31.1.9. Example domain model ...................................................................................................... 3

2. GeneSEZ Core ........................................................................................................................................ 42.1. Generators .................................................................................................................................... 4

2.1.1. Generator Hierarchy ........................................................................................................... 42.1.2. Generator ........................................................................................................................... 52.1.3. DefaultGenerator ................................................................................................................ 62.1.4. Platform specific generators ................................................................................................ 8

2.2. StatisiticComponent ....................................................................................................................... 82.2.1. Results ............................................................................................................................... 82.2.2. Configuration of the StatisticComponent ............................................................................... 92.2.3. Configuration of the StatisticObserver .................................................................................. 92.2.4. Overview of the Defaults ................................................................................................... 112.2.5. Information for the graphical visualization ........................................................................... 11

2.3. FileTreeWalkerFeature ................................................................................................................. 112.4. DeletionFeature ........................................................................................................................... 11

2.4.1. Configuration for File- and FolderDeletionFeature ............................................................... 122.4.2. Additional configuration only for FileDeletionFeature ........................................................... 12

2.5. ImportBeautifier ........................................................................................................................... 122.6. How to use features .................................................................................................................... 132.7. Explanation of already implemented and used Features ................................................................ 14

2.7.1. FileTreeWalkerFeature (short: FTW) .................................................................................. 142.7.2. DeletionFeature ................................................................................................................ 152.7.3. ImportBeautifier ................................................................................................................ 18

2.8. Preconfigured generators ............................................................................................................. 192.9. Creating your own features .......................................................................................................... 19

3. How To Guides ...................................................................................................................................... 203.1. Map a Problem Domain to an UML Domain Model ........................................................................ 20

3.1.1. Example Problem Domain ................................................................................................. 203.1.2. Examine the Problem Domain ........................................................................................... 203.1.3. Modeling with UML ........................................................................................................... 213.1.4. Transformability of the UML Domain Model ........................................................................ 22

3.2. Transform an UML Domain Model into JPA annotated Java Source Code ....................................... 223.2.1. The UML Domain Model ................................................................................................... 223.2.2. Mandatory UML Stereotypes ............................................................................................. 233.2.3. GeneSEZ Typemapping .................................................................................................... 233.2.4. Generated JPA annotated Java Source Code .................................................................... 243.2.5. Adjusting the Persistence Mapping .................................................................................... 25

4. UML Profile Reference ........................................................................................................................... 284.1. The GeneSEZ UML Profile .......................................................................................................... 28

4.1.1. Stereotype external ....................................................................................................... 284.1.2. Stereotype accessor ....................................................................................................... 284.1.3. Stereotype exclude ......................................................................................................... 284.1.4. Stereotype di ................................................................................................................... 284.1.5. Stereotype volatile ....................................................................................................... 284.1.6. Stereotype primitive ..................................................................................................... 29

4.2. The GeneSEZ JPA UML Profile ................................................................................................... 294.2.1. Enumeration jpaDatatype .............................................................................................. 30

Draft GeneSEZ Handbook for JavaEnterprise Development

Draft

iv

4.2.2. Enumeration jpaInheritanceType ................................................................................ 314.2.3. Enumeration jpaCascadeType ........................................................................................ 314.2.4. Enumeration jpaDescriminatorType ............................................................................ 314.2.5. Enumeration jpaContextType ........................................................................................ 324.2.6. Enumeration jpaEnumType .............................................................................................. 324.2.7. Enumeration jpaFetchType ............................................................................................ 324.2.8. Enumeration jpaGenerationType .................................................................................. 324.2.9. Enumeration jpaTemporalType ...................................................................................... 324.2.10. Enumeration jpaAssociationType .............................................................................. 334.2.11. Stereotype jpaJoinColumn ........................................................................................... 334.2.12. Stereotype jpaInheritance ......................................................................................... 334.2.13. Stereotype jpaColumn ................................................................................................... 334.2.14. Stereotype jpaPersistenceContext ........................................................................... 334.2.15. Stereotype jpaCallback ............................................................................................... 344.2.16. Stereotype jpaPersistentEntity ............................................................................... 344.2.17. Stereotype jpaAssociation ......................................................................................... 344.2.18. Stereotype jpaDatatypeMapping ................................................................................. 354.2.19. Stereotype jpaDiscriminatorValue ........................................................................... 354.2.20. Stereotype jpaPrimaryKeyJoinColumn ....................................................................... 354.2.21. Stereotype jpaDescriminatorColumn ......................................................................... 354.2.22. Stereotype jpaPrimaryKey ........................................................................................... 354.2.23. Stereotype jpaEntityListener ................................................................................... 364.2.24. Stereotype jpaJoinTable ............................................................................................. 364.2.25. Stereotype jpaPersistenceUnit ................................................................................. 364.2.26. Stereotype jpaIJoinColumn ......................................................................................... 364.2.27. Stereotype jpaPrimaryKeyClass ................................................................................. 364.2.28. Stereotype jpaTableGenerator ................................................................................... 374.2.29. Stereotype jpaSequenceGenerator ............................................................................. 37

Draft Draft

v

List of Figures1.1. Minimal annotated UML domain model ................................................................................................... 11.2. A simple bank domain model transformable into a persistent Java model ................................................. 32.1. Model-snippet of the generator hierarchy ................................................................................................ 42.2. Model of the feature structure .............................................................................................................. 132.3. Activity diagram of the generation process in correlation with the features ............................................... 132.4. Model of the FileTreeWalkerFeature ..................................................................................................... 142.5. Model of the DeletionFeature ............................................................................................................... 152.6. Model of the implemented structure for revision control systems ............................................................ 162.7. Model of the ImportBeautifier ............................................................................................................... 183.1. UML Domain Model of the simplified Bank Application .......................................................................... 213.2. ............................................................................................................................................................ 223.3. ............................................................................................................................................................ 233.4. Transformable UML domain model ....................................................................................................... 233.5. UML domain model with adjusted persistence mapping ......................................................................... 274.1. GeneSEZ UML Profile ......................................................................................................................... 284.2. GeneSEZ UML Profile for the Java Persistence API (JPA) ..................................................................... 30

Draft Draft

1

Chapter 1. Java Enterprise DevelopmentThis section is dedicated to the development of enterprise java applications.

GoalBasic understanding of developing enterprise Java applications with GeneSEZ.

Prerequisites

• As usual we will use UML as modeling language, so a basic understanding is preferable

• We will use the common Java terminology. If you are new to Java you might better jump in using an how toguide. But don't panic it's not that tough.

In particular we will focus on the following JavaEE technologies:

Java Persistence API (JPA)Persisting a domain model using the Java Persistence API

1.1. Java Persistence API (JPA)This section will cover the GeneSEZ JPA Profile to model persitent domain models for Java. You will learn what youhave to do, to get your Java code annotated with the JPA annotations. You will also learn, which optional steps youcan do to adjust the default transformation behaviour.

1.1.1. Persistent EntitiesThe only necessary thing you have to do to get a persistent domain model is to assign the stereotypejpaPersistentEntity to your classes. All other needed JPA relevant information is automatically added usingthe information of the uml model or JPA defaults.

A UML domain model with a minimal set of assinged stereotypes for transformation into a persistent Javadomain model is shown In figure Figure 1.1, “Minimal annotated UML domain model” . It just uses the stereotypejpaPersistentEntity on each class to enable persistence using JPA.

Figure 1.1. Minimal annotated UML domain model

1.1.1.1. Standard Constructor

According to the JPA specification each entity needs a default constructor, i.e. a constructor with no parameters. Ifyour entity class does not specify one, one is automatically created.

1.1.1.2. Persistent and Transient Attributes

All non static attributes the class defines are assumed as persistent attributes unless the Javamodifier transient or the annotation @Transient [http://download.oracle.com/javaee/5/api/javax/persistence/Transient.html] is specified. To mark an attribute as transient you can use the stereotype jpaDatatypeMappingand set the tagged value transient to true.

You can further adjust the mapping of persistent attributes using the stereotype jpaColumn, e.g. if they are uniqueor nullable.

1.1.1.3. Serializable

The interface java.io.Serializable [http://download.oracle.com/javase/1.5.0/docs/api/java/io/Serializable.html] is, if not already present, automatically added to each jpaPersistentEntity or embeddablejpaPrimaryKeyClass.

Draft Java Enterprise Development Draft

2

1.1.2. Entity Identity with Primary KeysAll entity objects must be uniquely identifiable by a primary key. One is automatically added, if you don't specify oneusing the stereotype jpaPrimaryKey.

If your entity class is part of an inheritance hierachy it depends on the inheritance strategy if it needs a primary keyor not. The transformations will automatically take care of this.

1.1.3. Optimistic Locking and Concurrent AccessMany enterprise applications have to deal with concurrent data access through users. To prevent data loss undersome circumstances you can apply optimistic locking to your entity objects. Optimistic locking is enabled by defaultresulting in an additional attribute on each entity class storing the version number of the persistent objects totracking changes. You can adjust this by modifying the tagged value optimisticLocking on the stereotypejpaPersistentEntity.

If your entity class is part of an inheritance hierarchy it depends on the inheritance strategy if it needs an additionalattribute for optimistic locking or not. The transformations will automatically take care of this.

1.1.4. Entity Manager and Entity Manager Factory ReferencesSometimes you need to reference the entity manager or entity manager factory. All attributes are automaticallychecked if they need an @PersistenceContext [http://download.oracle.com/javaee/5/api/javax/persistence/PersistenceContext.html] or @PersistenceUnit [http://download.oracle.com/javaee/5/api/javax/persistence/PersistenceUnit.html] annotation. It is automatically added if the type of the attribute is EntityManager [http://download.oracle.com/javaee/5/api/javax/persistence/EntityManager.html] or EntityManagerFactory [http://download.oracle.com/javaee/5/api/javax/persistence/EntityManagerFactory.html] respectively. If you need to adjustthe default values for these annotations you can use the stereotypes jpaPersistenceContext andjpaPersistenceUnit on your attribute respectively.

1.1.5. InheritanceIf your entity class is part of an inheritance hierarchy the JPA default mapping strategy SINGLE_TABLE is used. Youcan adjust this default behaviour by using the stereotype jpaInheritance. The jpa transformations will ensureif @Table [http://download.oracle.com/javaee/5/api/javax/persistence/Table.html] annotations on entity classes areallowed to prevent potential table naming conflicts.

Each inheritance path from a leaf class to the root class must have a primary key and version attribute if optimisticlocking is enabled. The transformations take care of this automatically. If you specified more than one primarykey, additional checks may result in adding a @Column [http://download.oracle.com/javaee/5/api/javax/persistence/Column.html] annotation setting insertable and updateable to false.

1.1.6. Associations and References between EntitiesThere is a couple of meta data you can specify for mapping entity references. The transformations willtake automatically care of it, if possible. The multiplicity of the reference is taken from the multiplicityproperty of the UML association end. Based on it one of @OneToOne [http://download.oracle.com/javaee/5/api/javax/persistence/OneToOne.html], @OneToMany [http://download.oracle.com/javaee/5/api/javax/persistence/OneToMany.html], @ManyToOne [http://download.oracle.com/javaee/5/api/javax/persistence/ManyToOne.html] or@ManyToMany [http://download.oracle.com/javaee/5/api/javax/persistence/ManyToMany.html] is generated. For allother things the JPA defaults are used. You can adjust the defaults by specifying the stereotype jpaAssociationto the association end. It allows you to adjust the mappedBy and optional values as well as theCascadeType [http://download.oracle.com/javaee/5/api/javax/persistence/CascadeType.html] and FetchType[http://download.oracle.com/javaee/5/api/javax/persistence/FetchType.html].

1.1.7. Naming of Table and ColumnsThe database systems usually have a set of names which are not allowed to appear as table or columnnames resulting in potential naming conflicts. For prevention a prefix is added to table names (see stereotypejpaPersistentEntity) and table columns. Table columns are prefixed with the class name in lowercase.

Draft Java Enterprise Development Draft

3

1.1.8. Get and Set Methods (Accessors)According to the Java Beans convention a get and set method is automatically added for each attribute. Thisis achieved by adding the stereotype accessor to the entity class. Note that you can adjust this behaviour byspecifying the stereotype accessor on attribute level, see evaluation of the stereotype accessor.

1.1.9. Example domain modelWe use a simple bank domain model to demonstrate the use of the JPA profile. It is shown in Figure 1.2, “A simplebank domain model transformable into a persistent Java model” as a UML class chart. A Bank has (hopefully)many Customers which in turn can be customer from many banks. Each Customer can have many Accounts andis reachable by one Contact. A Bank provides different kinds of accounts modeled each as a separate subclass ofAccount. Over time each account produces several Statements.

Figure 1.2. A simple bank domain model transformable into a persistent Java model

The stereotype jpaPersistentEntity is assigned to all classes. It is the only mandatory stereotype you haveto use to get a persistent Java model. Our banks should be identifyable by its name. To specify the name asbusiness / domain key we use the stereotype jpaColumn and set the tagged value unique to true. With thestereotype jpaInheritance on class Account we changed the inheritance mapping strategy from the JPAdefault SINGLE_TABLE to TABLE_PER_CLASS . Every instance of any subclass of Account is stored in a separatetable. On the association to class Statement we assigned the stereotype jpaAssociation with the taggedvalue cascade set to jpaCascadeType REMOVE on the association end to class Statement. This means if anaccount is removed, all its statements are removed too.

On class Customer we used the stereotype jpaDatatypeMapping with its tagged value transient set totrue. It marks the attribute retypedPassword as transient and is therefore not stored within the database. Itis just used to validate the specified password. On both password attributes we used the stereotype accessor tosuppress the generation of set methods. Instead we specified our own set methods as operations. Doing this, wecan implement the set methods so, that not the plain text password is stored as attribute value but an encoded valueusing a hash function on the specified password. So we prevent a long time storage of the password in plain text.

Draft Draft

4

Chapter 2. GeneSEZ CoreThis section provides a set of GeneSEZ core concepts and features needed or useful when developing JavaEnterprise Applications.

2.1. GeneratorsThe generators execute the model-to-text transformation. There are three main types of generators (seeGenerator Hierarchy ). The configuration of the three types is described below.

2.1.1. Generator HierarchyIn this section the hierarchy of the generators will be described.

Figure 2.1. Model-snippet of the generator hierarchy

As you can see in Figure 2.1, “Model-snippet of the generator hierarchy” there are three hierarchical levels for theGenerator. First there is the normal Generator , if you use this you must configure nearly everything, but you canadjust it to your needs. There are only some default values, besides the ones that are set for every component, set:

- fileEncoding = "utf-8"- prDefaultExcludes = false- prExcludes = ".svn"- singleValuedSlot = true

Because in most cases some standard configuration is well enough, we implemented a DefaultGenerator .There the file and folder deletion features are already inserted and activated, of course you can deactivate thiswith setting deleteEmptyFolders and/or deleteOldFiles to false in the workflow. Furthermore a defaultImportBeautifier is set, which should be configured with the properties importStrings or importRegex andfileExtensions or setting importTakeOver to false (see Section 2.5, “ImportBeautifier” ). Also the followingproperties are set by default in the DefaultGenerator:

- excludePackages = ""

Draft GeneSEZ Core Draft

5

- basePackage = ""- useModelNameAsBasePackage = false- generateSectionComments = true- accessorForStereotypes = "entity"- accessorStereotype = "accessor"- usePropertyVisibilityForAccessors = false- deleteOldFiles = true- deleteEmptyFolders = true- importTakeOver = true

You should not forget to set following properties if you want to use this Generator:

- template- typeMappingFile- importStrings or importRegex- fileExtensions- maybe another beautifier as postProcessor if you wish.(- newAssociationHandling )(- fieldAccess )

For specific purposes we have implemented platform or language dependent generators. These generators are pre-configured and should work with only a slight adjustment to your needs. Currently implemented specific generatorsare:

- JavaGenerator- PHPGenerator- CSharpGenerator- TYPO3Generator

Note

The outputDir parameter must be set in every Generator.

2.1.2. GeneratorThe generator executes the model-to-text transformation. Therefore following parameters are available, but itdepends on the value of template which parameters are used for the transformation. Usually the generator shouldbe the basic class for model-to-text transformations. It can be added to the workflow with

<component id="model2text" class="org.genesez.platforms.common.workflow.Generator">

template , single-valueis used to indicate the XPand Template and the name of the define-block, which is called at the model-to-texttransformation.

outputDir , single-valueis used to indicate the directory, where the generated source code is stored or should be stored. If the directorydoes not exist it will be created.

proRegDir , single-value , default: value of outputDiris used to indicate the directory, where source code with protected regions, which should be saved during thetransformation, will be stored.

aspectTemplate, multi-valueuse to indicate XPand templates with Around statements. With this Advices for template- define -statementscould be defined.

aspectTemplates, multi-valuesame as aspectTemplate with the difference, that one can give a comma or semicolon separated list of XPand-templates.

aspectScript, multi-valueuse to indicate XTend scripts with around statements. With this Advices for XTend functions could be defined.

Draft GeneSEZ Core Draft

6

aspectScripts, multi-valuesame as aspectScript with the difference, that one can give a comma or semicolon separated list of XTend-scripts.

singleValuedSlot, single-value , default: trueSets if the slot has only one root element for which the template is executed or more.

slot, single-value , default: genesezModelindicates the name of the slot, which contains the GeneSEZ model that is used for the model-to-texttransformation.

prExcludes, single-value , default: .svnindicates files and directories, that are excluded in the search for protected regions.

prDefaultExcludes, single-value , default: falseindicates whether the default file-exclusions should be used. These are named in the openArchitectureWaredocumentation. All files with these extensions won't be checked for protected regions.

fileEncoding, single-value , default: utf-8use to indicate the coding of the templates

excludedDirectoryNames, single-valueOnly useful when a FileTreeObserver is added. Excludes all directories under the output directory with thegiven names (separated by "," or ";") from the evaluation in the added features. Used as global value for everyfeature. Useful if you want folders with special names not evaluated.

excludedRelativePaths, single-valueOnly useful when a FileTreeObserver is added. Excludes given paths (separated by "," or ";") relative tothe output directory from the evaluation in the added features. Used as global value for every feature. Useful ifyou want only some specific directories not evaluated.

excludedFileExtensions, single-valueOnly useful when a FileTreeObserver is added. Excludes files (not directories) with given suffixes(separated by "," or ";") from the evaluation in the added features. You can even exclude complete files. Usedas global value for every feature.

Example value=".svn, class" will exclude every file with the suffix ".svn" or "class".

Binds stronger than includedFileExtensions .

includedFileExtensions, single-valueOnly useful when a FileTreeObserver is added. Includes files (not directories) with the given suffixes(seperated by "," or ";") into the evaluation in the added features. Only this files are included. It is weaker thanexclusions, especially its weaker than excludedFiles . If it's not set everything will be included. Used asglobal value for every feature.

For Example <excludedFiles value="a" /> <includedFiles value="java, .php" /> will exclude every file with thesuffix "a", which means also all files with the suffix "java". Therefore only files with the suffix ".php" will beevaluated.

Furthermore the generator contains all parameters from the XPand-generator component of openArchitectureWare.

2.1.3. DefaultGeneratorThe DefaultGenerator is a pre-configured Generator, that sets some values already and also provides some moreconfiguration details for easier use. Currently the DefaultGenerator provides Typemapping, File- and FolderDeletionand ImportTakeOver, which are all activated by default. It can be added to the workflow with

<component id="model2text" class="org.genesez.platforms.common.workflow.DefaultGenerator">

Following parameters are available.

typeMappingFile, multi-valueis used to indicate the type-mapping files, which should be used during the model-to-text transformation.

Draft GeneSEZ Core Draft

7

typeMappingFiles, multi-valuesame as typeMappingFile with the difference, that one can give a comma or semicolon separated list of type-mapping files.

basePackage, single-valueis used to indicate a package, which should be used as basis for the model-to-text transformation. Everythingwill be generated in this package.

useModelNameAsBasePackage, single-value , default: falsethis indicates whether the name of the model-element (root-element of the GeneSEZ model) should be usedas base package .

generateSectionComments, single-value , default: trueindicates if single lined commentaries should be created, which will subdivide the source code.

accessorForStereotypes, optional, single-value, default: entityspecificates a through commata seperated list with names of stereotypes which implicates the generation ofget - and set -methods.

accessorStereotype, optional, single-value, default: accessorindicates the name of the stereotype accessor . Default is the name of the stereotype in the GeneSEZ UMLprofile. If another name is used it must have at least the the same tags, as the stereotype accessor fromthe GeneSEZ UML profile (if the interpratetion logic for accessors is not replaced or extended).

usePropertyVisibilityForAccessors, single-value , default: falsethis indicates if the visibility of the attributes are generated always private and the given visibilities to theattributes are used for the accessors (getter and setter).

For example there is a protected attribute in your model, then if this parameter is set to true the attribute will beprivate and the accessors will be protected in the generated code.

excludePackage, multi-valueuse to indicate GeneSEZ packages via the qualified name, to be excluded during the model-to-texttransformation.

excludePackages, multi-value , default: UML Standard Profilesame as exclude package with the difference, that one can give a commata seperated list with qualified namesof GeneSEZ packages.

deleteOldFiles, single-value , default: trueIf true old files will be deleted. This is useful if you renamed something in your model. Therefore the files inthe output directory will be read recursively and saved with their last modification date (LMD). After the codegeneration the LMDs will be compared with the new LMDs and if they are the same the file will be deleted. Ifthe files are under a known revision control system, the files will be marked as deleted in the repository andafter that deleted from the file system (if possible). You can configure more with excludedDirectoryNames, excludedRelativePaths , excludedFiles and includedFiles .

deleteEmptyFolders, single-value , default: trueIf true empty folders will be deleted. Therefore it searchs again through the output directory. If the empty foldersare under a known revision control system, they will be first marked as deleted in the repository and afterthat, if possible, deleted in the file system. You can configure more with excludedDirectoryNames andexcludedRelativePaths .

importTakeOver , single-value , default: trueIf true and importStrings or importRegex is set, then imports will be carried over from the old to thenew file. You can configure files that should be checked for imports with fileExtensions . Passes the valueto the ImportBeautifier

importRegex , single-valueNeeded for the configuration of the ImportBeautifier, only useful when importTakeOver is true. Must bea regular expression which expresses every import statement in the files to check. For java this looks like:"import .*;$" If not set or expression is defective, imports will not be carried over. Passes the value to theImportBeautifier

Draft GeneSEZ Core Draft

8

importStrings , single-valueNeeded for easy configuration of the ImportBeautifier, only useful when importTakeOver is true.Creates a regular expression of the given import strings separated by comma or semicolon. The regularexpression looks like "(importExpression1|ImportExpression2|...) .*$" . Passes the value to theImportBeautifier

fileExtensions , single-valueNeeded to configure the ImportBeautifier, only files with this extensions will be checked for imports. Onlyuseful when importTakeOver is true. Creates a regular expression from the comma or semicolonseparated list, which looks like ".*(\\.extension1|\\.extension2|...)$" . Passes the value toImportBeautifier

Furthermore the DefaultGenerator contains all parameters from the Generator and the XPand-generator componentof openArchitectureWare.

2.1.4. Platform specific generatorsThese are pre-configured generators for special platforms or languages. Use these if the default values are ok foryou and/or you don't want to configure everything all by yourself. These generators should satisfy most needs. Butof course you can also change the configuration of these generators if you want to. They are all subclasses from theDefaultGenerator and therefore inherit also all of its parameters and setting most of them by default. Especiallytemplate , typeMappingFile , importRegex and fileExtensions are set by default. In fact to run thesegenerators you only need to set the outputDir .

2.1.4.1. JavaGenerator

The JavaGenerator generates Java 5 source code from a GeneSEZ model by default. It can be added to the workflowwith

<component id="model2java" class="org.genesez.platforms.java.workflow.JavaGenerator">

template , single-value , default: de::genesez::platforms::java::java5::templates::Root::RootXPand-Template for model-to-java transformation.

typeMappingFile , multi-value , default: de/genesez/platforms/java/typemapping/typemapping.xmlDefault java type-mapping file.

formatterConfig, single-value , default: de/genesez/platforms/java/workflow/eclipse.java.formatter.settings.xml

specification file for configuration of the JavaBeautifier. Currently the integrated formatter from eclipse is used.

newAssociationHandling, single-value , default: trueIf true the GeneSEZ specific association handling will be used, else the one from the JavaBean pattern.

fieldAccess, single-value , default: trueIf true annotations will be placed onto the attributes, else onto the methods.

2.2. StatisiticComponentThe StatisticComponent can give an overview of the source-code's structure. These information can be used todecide whether the usage of MDSD pays off or not. If you want to add the component into the workflow this couldlook like:

<component id="stats" class="org.genesez.platforms.common.workflow.StatisticComponent" >

2.2.1. ResultsThe component copies the htmlTemplateDirectory to the outputDir and generates the files:

• overview.html for the overview

Draft GeneSEZ Core Draft

9

• [optional] details.html for the details

into outputDir/html . You can look at the statistics through outputDir/index.html .

The component shows the lines of all files in the given outputDir in the following categories:

• generated code lines

• manual implemented code lines

• comment lines (consists of generated and not generated lines. Also protected region lines count to this)

• documentation lines (consists of generated and not generated documentation lines)

Blank lines stay neglected. In the overview page the information are given for the whole project. There are also2 pie charts, that visualizes the composition of the whole source code. In the details page the information aregiven for every file and folder in a table.

2.2.2. Configuration of the StatisticComponentThe configuration of the StatisticComponent can be done by following parameters.

outputDir , single-valuepasses the value to its contained generator. It is used to indicate the directory, where the generated files arestored or should be stored. If the directory does not exist it will be created.

Caution

Before generation the given directory will be cleaned, that means that all files and folders will firstbe deleted. Therefore this should be at least a separate subfolder or a complete separate folder todirToCheck .

htmlTemplateDirectory , single-value , default: (location of StatisticComponent.class)/../html_template

The directory which contains the used YAML-css files, the javaScript and the index.html, which will be copiedto the outputDir .

Even there is a default value this should better be set because the default depends on the pathwere the StatisticComponent.class file lay. The needed folder is called html_template and is stored inorg.genesez.platforms.common , you may also copy the folder into your generator project.

template , single-value , default: de::genesez::platforms::common::statistic::Evaluation::Rootvalue is passed to the contained generator. It is used to indicate the XPand Template and the name of thedefine-block, which is called at the model-to-text transformation.

statisticObserver, single-value , default: if not set a standard observer with default values will be used. SeeSection 2.2.4, “Overview of the Defaults” .

The FileTreeObserver that counts the lines in the different categories . It holds the model for thetransformation. For configuration see Section 2.2.3, “Configuration of the StatisticObserver” .

dirToCheck, single-value , default: parent of the outputDirpasses the value to searchedDir of the contained FileTreeWalkerFeature . Sets the directory wherethe lines of the files should be counted.

withDetails, single-value , default: falseIndicates whether the details page should be generated or not.

Furthermore the statistic component contains every parameter of the CompositeComponent fromopenArchitectureWare.

2.2.3. Configuration of the StatisticObserverTo add the observer to your StatisticComponent you must place

<statisticObserver class="org.genesez.platforms.common.statistic.StatisticObserver">

Draft GeneSEZ Core Draft

10

into the Component's configuration part. You can also give it an ID if you want to. As mentioned in parameterstatisticObserver this has also some configuration parameters.

commentStrings, single-value , default: //, /*, */, /**Sets the comment strings to indicate comments in the following order (separated by "," or ";")

- singleLineCommentString- multiLineCommentStartString- multiLineCommentEndString- docuCommentStartString [optional]

If only 3 strings are given it won't check for documentation lines, due to not all programming languages supportdocumentation comments.

Note

If a comment starts with comma or semicolon you have to specify it one by one with the correspondingparameters.

singleLineCommentString, single-value , default: //is used to indicate whether a checked line is a single-line comment, can be set with others together incommentStrings on position 1.

multiLineCommentStartString, single-value , default: /*is used to indicate whether a checked line is a multi-line comment, if found the lines untilmultiLineCommentEnd will be counted to the comments. Can be set with others together incommentStrings on position 2.

multiLineCommentEndString, single-value , default: */is used to indicate whether a checked line is a multi-line comment end. Can be set with others together incommentStrings on position 3.

docuCommentStartString, single-value , default: /**is used to indicate whether a checked line is a documentation comment, if found the lines untilmultiLineCommentEnd will be counted to the documentation. Can be set with others together incommentStrings on position 4.

If this is empty the observer will not check for documentation lines due to programming languages that don'tsupport documentation comments.

generate, multi-value , default: ( dirToCheck or searchedDir )/src-genOverrides default and adds the given directory or file to generated and resolves it to dirToCheck . In the givenfolder(s) or file(s) the observer counts the lines, that are not in protected regions, as generated.

generates, multi-value , default: See generatesame as generate with the difference, that one can give a comma or semicolon separated list of generateddirectories or files.

manual, multi-valueAdds the given directory or file to manual and resolves it to dirToCheck . In the given folder(s) or file(s) theobserver does not count lines as generated.

manuals, multi-valuesame as manual with the difference, that one can give a comma or semicolon separated list of manualdirectories or files.

exclude, multi-value , default: .svn, .cvs, .hg, .git and outputDir from StatisticComponentOverrides defaults and adds the given file or directory to excludes. These directories or files won't be evaluated.

Note

If the exclude is not given as absolute path, every file or folder that contains the exclude in its path willbe excluded.

Draft GeneSEZ Core Draft

11

excludes, multi-value, default: See excludesame as exclude with the difference, that one can give a comma or semicolon separated list of excludes.

statisticName, single-value , default: last element of dirToCheck path from StatisticComponent.The name that is given for the statistics. This is placed in the headline of the generated files.

2.2.4. Overview of the DefaultsIf you don't want to configure anything but the outputDir by yourself, you can just use the StatisticComponentas is. Therefore following defaults are set:

• dirToCheck = the parent directory of the outputDir

• template = de::genesez::platforms::common::statistic::Evaluation::Root

• htmlTemplateDirecotory = (location of StatisticComponent.class)\..\html_template

• withDetails = false

• The default StatisticObserver with:

• commentStrings = //, /*, */, /**

• statisticName = the last part of the outputDir path

• generates = src-gen

• excludes = .svn, .cvs, .hg, .git and the outputDir of the StatisticComponent

If you add your own StatisticObserver, all defaults will be set and can be overwritten.

2.2.5. Information for the graphical visualizationThe diagrams are generated by JFreeChart [http://www.jfree.org/jfreechart/] . This is a powerful API for chartcreation. With this two png files will be generated and stored into outputDir /charts . These charts can beseen in the overview page.

2.3. FileTreeWalkerFeatureThe FileTreeWalkerFeature is needed to walk the file tree on the given searchedDir .

observer, multi-valueSets an FileTreeObserver for one file tree walk. This must be a class that implements the FileTreeObserverinterface. The observers will be unregistered after the file tree walk is completed.

searchedDir, single-value , default: the outputDir from the generator to which its added.Sets the entry point of the file tree walk. The file tree walk starts at the given directory. E. g. it is used if you wantto use a StatisticObserver within a generator and want the statistics of the whole project.

Caution

For most cases the default value should be good enough. If you use the FileDeletionFeature asan observer of this particular FileTreeWalkerFeature you should be extra careful with this parameter.Because the FileDeletionFeature deletes all files that are not changed after the generation.

2.4. DeletionFeatureThe DeletionFeature is parted into two features. The FileDeletionFeature handles the deletion of not generated filesand the FolderDeletionFeature handles the deletion of empty folders. The DeletionFeature cannot be configured,but it provides 2 parameters that both File- and FolderDeletionFeature use.

Draft GeneSEZ Core Draft

12

2.4.1. Configuration for File- and FolderDeletionFeature

excludedRelativePaths, multi-valueExcludes given paths (separated by "," or ";") relative to the output directory from the search for files and folders.Useful if you want only some specific directories not in the search. Overrides the global value, given in theGenerator, excludedRelativePaths for this feature.

excludedDirectoryNames, multi-value , default: metadata folder(s) of found and supported revision controlsystem(s)

Excludes all directories under the output directory with the given names (separated by "," or ";") from the searchfor files and folders. Useful if you want folders with special names not searched. Overrides the global value,given in the Generator, excludedDirectoryNames for this feature.

2.4.2. Additional configuration only for FileDeletionFeature

excludedFileExtensions, multi-valueExcludes files (not directories) with given suffixes (separated by "," or ";") from the search for files. You caneven exclude complete files. Overrides the global value, given in the Generator, excludedFileExtensionsfor this feature.

Example value=".svn, class" will exclude every file with the suffix ".svn" or "class".

Binds stronger than includedFileExtensions

includedFileExtensions, multi-valueOnly files with these extensions will be put into the search for files. You can also include only special files.Overrides the global value, given in the Generator, includedFileExtensions for this feature. Its weakerthan the exclusion, especially weaker than excludedFileExtensions

For Example <excludedFiles value="a" /> <includedFiles value="java, .php" /> will exclude every file with thesuffix "a", which means also all files with the suffix "java". Therefore only files with the suffix ".php" will beevaluated.

2.5. ImportBeautifierThe ImportBeautifier handles the take over of imports from old to newly generated files and the removal of doubleimports. To configure the ImportBeautifier there are only some operations needed.

fileExtensions, multi-valueThe extensions of the files separated by "," or ";" that should be scanned for imports. If not set every file will bescanned. Therefore imports may not be carried over correct. It's not recommended to not set these property butits not forbidden and not especially needed to work.

importRegex , single-valueIf importTakeOver is true, either this or importStrings must be set for ImportBeautifier to work, if both setonly the last in the workflow file will be used. The import regular expression is used to indicate if a line containsan import. E. g. for Java the regular expression looks like "import .*;$" .

Note

This should follow regular expression syntax in Java.

importStrings , singleValueIf importTakeOver is true, either this or importRegex must be set for ImportBeautifier to work, if both setonly the last in the workflow file will be used. Needed to indicate lines with import. If there are more importStringsneeded separate them with "," or ";". It creates a regular expression which looks like: "(importString1|importString2|...) .*$" and passes them to importRegex .

Draft GeneSEZ Core Draft

13

importTakeOver, single-value , default: trueIf false the imports won't be taken over, but double imports will be removed properly.

2.6. How to use featuresTo use different features we have implemented following structure: see Figure 2.2, “Model of the feature structure” .

Figure 2.2. Model of the feature structure

In fact features are divided into 2 to 3 groups. The main groups are PreFeature and PostFeature . PreFeaturesdo something before the generation, so for example they prepare the PostFeatures. PostFeatures do somethingafter the generation, but maybe they need preparation before they can do something.

The 3rd group is the PostProcessor . PostProcessors are doing stuff after generation of one file and before thefile is written and closed (they can also do stuff with the file after the file is written). Maybe they also need preparation.The difference between PostFeatures and PostProcessors is that PostFeatures are used after all files are writtenand PostProcessors are used after one file is generated instead.

In Figure 2.3, “Activity diagram of the generation process in correlation with the features ” you can see how thefeatures are invoked during the generation process.

Figure 2.3. Activity diagram of the generation process in correlation with the features

Draft GeneSEZ Core Draft

14

All features from the 3 groups can be added to the generator through the workflow file. The order of the groups isindifferent, but the order in the groups is important in the workflow file.

Note

- PreFeatures can be added with the beginning phrase preFeature .- PostFeatures can be added with the beginning phrase postFeature .- PostProcessors can be added with the beginning phrase postProcessor .

Every feature can be added with one of the following 3 structures:

• Complete with feature specific properties [and an optional ID (to identify the same instance in anotherstatement)].

<preFeature class="QualifiedClassName" id="optionalID" > <aProperty value="propertyValue" /></preFeature>

• Without properties (standard values will be used) [and an optional ID].

<postFeature class="QualifiedClassName" id="optionalID" />

• Only with a reference of a previously used feature, so the previously used instance is used again. Please notethat, when using references, it's not possible to set properties for the feature in this section.

<postProcessor idRef="optionalID" />

2.7. Explanation of already implemented and usedFeatures

2.7.1. FileTreeWalkerFeature (short: FTW)

Figure 2.4. Model of the FileTreeWalkerFeature

Draft GeneSEZ Core Draft

15

The FTW (see Figure 2.4, “Model of the FileTreeWalkerFeature” ) is a Pre- and a PostFeature, so it can run beforeand after the generation. It is useful to prepare other features that implement the FileTreeObserver (short: FTO)interface. FTOs can be registered on an FTW as observers. An FTW walks through the file tree and calls differentupdate methods (depending on the status) on its observers. Observers can be added in the workflow file as follows:

<preFeature class="org.genesez.platforms.common.workflow.feature.FileTreeWalkerFeature"> <observer class="org.genesez.platforms.common.workflow.feature.aObserver" /></preFeature>

Note

After one file tree walk all observers will be unregistered.

For implementation details see ??? .

2.7.2. DeletionFeature

Figure 2.5. Model of the DeletionFeature

Draft GeneSEZ Core Draft

16

The DeletionFeature manages the deletion of old files or empty packages, also in different revision systems (seeSection 2.7.2.1, “Support of different revision control systems (RCS)” for more information about revision systems). Itis divided into two separate features the File- and FolderDeletionFeature to allow different configurations.See Figure 2.5, “Model of the DeletionFeature”

It provides the two subfeatures with some basic functionality see ??? for implementation details.

2.7.2.1. Support of different revision control systems (RCS)

Figure 2.6. Model of the implemented structure for revision control systems

To prevent missing files in repositories a structure that allows deletion of files in different RCS was needed, thereforewe implemented the structure seen in Figure 2.6, “Model of the implemented structure for revision control systems ”

Some short description of used methods is given below:

getMetadataFolderNamegets the name of the directory where the repository dependent metadata is stored (e. g. for Subversion theseare ".svn" folders)

This is used to check what revision control system(s) is/are used.

setRepositoryRootSets the place where the metadata folder was found. For some revision systems (e. g. Git) this must be knownto do deletion or other stuff.

toStringThis returns just the String representation of the RCS for the Log.

markForDeleteThis is the main method, the given file will be marked for deletion in the concrete repository. Therefore therepositoryRoot maybe needed.

Note

The file is only marked for deletion in the repository and will not be deleted from the file system duringthis operation.

Currently there are implementations for following RCS:

- Subversion , metadataFolderName=.svn- Git , metadataFolderName=.git, needs repositoryRoot- also all RCS where its no problem to delete the metadataFolders (like CVS)

Draft GeneSEZ Core Draft

17

2.7.2.2. FileDeletionFeature

The FileDeletionFeature is used to delete old files. It is a PostFeature and an FTO and needs to be an observerof an FTW in the PRE section. Because as observer it checks all files for their last modification dates. As feature itlooks after the generation if the last modification dates have changed. The files were the dates didn't change will bedeleted. For more information and further configuration see FileDeletionFeature

Caution

Use this feature ONLY with the right configuration order to prevent loss of information:

1st: Register an FTW as a PreFeature2nd: Register the FileDeletionFeature as an observer to the FTWbefore 1st or 3rd: Register the same FileDeletionFeature as PostFeature

In the workflow file this looks like this:

<preFeature class="org.genesez.platforms.common.workflow.feature.FileTreeWalkerFeature"> <observer class="org.genesez.platforms.common.workflow.feature.FileDeletionFeature" id="fileDeletion" /></preFeature>

<postFeature idRef="fileDeletion" />

For implementation details see ??? .

2.7.2.3. FolderDeletionFeature

The FolderDeletionFeature is used to delete empty folders. It is a PostFeature and an FTO and needs to be anobserver of an FTW in the POST section. While its an observer it checks which folders are empty and as feature itdeletes the empty folders if possible. For more information and further configuration see FolderDeletionFeature

The configuration order of this feature is not so vital but the feature makes only sense if configured right. Thereforefollowing steps make sense:

1st: Register an FTW as a PostFeature2nd: Register the FolderDeletionFeature as an observer to the FTW3rd: Register the same FolderDeletionFeature as PostFeature

In the workflow file this looks like this:

<postFeature class="org.genesez.platforms.common.workflow.feature.FileTreeWalkerFeature"> <observer class="org.genesez.platforms.common.workflow.feature.FolderDeletionFeature" id="folderDeletion" /></postFeature>

<postFeature idRef="folderDeletion" />

For implementation details see ??? .

Draft GeneSEZ Core Draft

18

2.7.3. ImportBeautifier

Figure 2.7. Model of the ImportBeautifier

The ImportBeautifier (see Figure 2.7, “Model of the ImportBeautifier” ) is used to carry over own imports from the oldfiles to the new generated files and to remove double imports. It is a PostProcessor and an FTO and needs to bean observer of an FTW in the PRE section. While its an observer it checks the File-ID for each file and stores them,together with the imports in that file, in a map. During postprocessing of a file, the File-ID will be searched and thecorresponding imports will be placed into the next free space of the file. After that double imports will be removed.

The ImportBeautifier needs a little extra configuration to work properly, so you must give them the used file extensionsand the used import strings or a import regular expression, for more information see ImportBeautifier.

The configuration order is not vital, but it will only work if its configured right. Therefore following steps make sense:

1st: Register FTW as a PreFeature2nd: Register ImportBeautifier as observer to the FTW3rd: set file extensions and import strings or import regular expression.before 1st or 4th: Register same ImportBeautifier as postprocessor.

in the workflow file this looks like this:

<preFeature class="org.genesez.platforms.common.workflow.feature.FileTreeWalkerFeature"> <observer class="org.genesez.platforms.common.m2t.ImportBeautifier" id="import" /> <fileExtensions value=".extension1, .extension2, ..." /> <importStrings value="importString1, importString2, ..." /></preFeature>

<postProcessor idRef="import" />

For implementation details see ??? .

Draft GeneSEZ Core Draft

19

2.8. Preconfigured generatorsIf you don't want to set the File-, FolderDeletionFeature and the ImportBeautifier all by yourself you can also use theDefaultGenerator or a platform specific generator. These generators set the features in the right order already.

2.9. Creating your own featuresYou can easily implement your own features by just implementing Pre- or/and PostFeature or even PostProcessorand, if information from the file tree are needed, implementing FTO or extend FileTreeObserverAdapter. These owncreated features can be added just like above into the generator and even into preconfigured generators.

Draft Draft

20

Chapter 3. How To GuidesThis section provides a set of How-To guides related to the development of Java Enterprise Applications.

3.1. Map a Problem Domain to an UML DomainModelIn this section we will cover the question: How to create a domain model using UML?. First we will focus on ourproblem domain and then we will create a uml class model.

GoalCreation of an UML domain model for a problem domain.

Prerequisites

• some basic knowledge about banking institutions

• some basic understanding of UML class models

3.1.1. Example Problem DomainWe will use a simplified banking application as example. If we dive into this problem, the first entity that arises is abank. Each bank has a name. So what next? The most important thing: banks care about our money! If a bank hasyour money, you're a customer of that bank. Your money is managed by so called accounts. If you are lucky thebank will pay interest for your money. Changes of the accounts balance are recorded within statements.

For the sake of simplicity we will care about three types of accounts: savings account, flexible savings account andchecking account. We will not care about credits or negative balances. Last but not least, we need a way to contactthe bank and the bank needs a way to contact us. This can be by phone call, email or snail mail.

This should be enougth for our little example. We already emphasized the important words.

3.1.2. Examine the Problem DomainLets consider the concepts of the problem domain in more detail and map it to object oriented concepts:

BankA bank is an institution working with money. There exist several banks and each bank has a name. Sometimesnew banks are founded and sometimes they end in liquidation. Banks have a lifecycle and are therefore entities.So a bank represents a class.

MoneyMoney is somethings you may have or not. It is something like a unit. Money has no lifecycle and is a domaindata type.

CustomerA customer is a person who lets manage his money by the bank. At some point in time a person may be customerof a bank. At some other point in time may be not. Customer represents a class.

AccountAn account is a domain concept to manage money. Each account has a balance indicating how much money isavailable. The balance change over time. Accounts have a lifecycle and therefore account represents a class.

InterestInterest is something you get from your bank in return for providing your money. Interest is a value usuallycalculated using an interest rate. The interest rate is a domain data type like money.

StatementStatements record all changes of the accounts balance. Statements are created regularly at a certain point intime. A statement represents a class.

Draft How To Guides Draft

21

Savings Account, Flexible Savings Account, Checking AccountThese represents three possible kinds of accounts. They differ in the provided interest rate and in the periodafter the interest is payed. We will represent these accounts as separate classes.

ContactA contact is a concept providing information how to contact a bank or a customer. It provides the phone number,the number of the mobile and email. For snail mail is must provide a valid address. A contact represents a class.

PhoneNumberAs we know not every number is a phone number. A phone number has special format and is therefore a domaintype.

EmailEmail is a domain data type too.

AddressAn address specifies a valid location for postal delivery. It represents a class.

3.1.3. Modeling with UMLNow we want to create a UML class model for our problem domain. First we create a new class Bankand add an attribute name to it. The type of the attribute is simply String so we choose the Stringtype defined by the UML specification (and therefore contained in the UML metamodel within the packageAuxiliaryConstructs::PrimitiveTypes). We don't want a bank without a name and so we create aconstructor with a name parameter. Note that the UML defines a constructor as an operation with the stereotypecreate. We leave the name of the operation empty.

Next we create the class Account. To create the balance attribute we need our domain type Money first. So wecreate a new UML DataType and give it the name Money. A UML datatype differs from a class and is representedas a rectangle like a class but with the keyword «datatype». We marked the class Account as abstract toprevent the creation of instances of it.

Now you know the basics and can go on. You should end up with an UML class chart looking similar like Figure 3.1,“UML Domain Model of the simplified Bank Application” .

Figure 3.1. UML Domain Model of the simplified Bank Application

Some UML tool vendors support you with a lot of datatypes and primitive types. Keep in mind that most of them arevendor specific and the UML itself defines just four primitive types:

BooleanLogical type for the values true and false.

Draft How To Guides Draft

22

IntegerType for positive and negative integer numbers in the infinite range.

StringType for a bunch of characters used for text.

UnlimitedNaturalType for natural values, i.e. positive integer values in the infinite range.

We think its always a good decision to focus on the domain needs. Furthermore, UML tool vendors support you witha wide range of stereotypes. Keep in mind that the UML standard defines just a few, including the following two:

«create»Can be used on operations to specify that the operation creates instances of the classifier, i.e. a constructor.

«destroy»Can be used on operations to specify that the operation destroys instances of the classifier, i.e. a destructor.

3.1.4. Transformability of the UML Domain ModelOne problem arises with such a domain model. Usually we don't want to implement all domain data types with ownclasses. Sometimes a library provides useful datatypes, e.g. for dates or we just use provided primitive types of ourprogramming language, e.g. String or Integer.

Unfortunately the UML lacks a construct to specify if a class or datatype is to be defined or already exists and istherefore usable from a library. To fill this gap the GeneSEZ UML profile contains the stereotype external tomark already existing types in an UML model.

For code generation purpose GeneSEZ provides a type mapping facility to map domain data types to already existingtypes.

3.2. Transform an UML Domain Model into JPAannotated Java Source CodeThis section focuses on the generation of JPA annotated Java source code from an UML domain model.

GoalGenerate Java classes from an UML class model which instances can be persisted using a JPA compliantpersistence provider.

Prerequisites

• The ability to create an UML domain model. If you are unsure check Section 3.1, “Map a Problem Domainto an UML Domain Model”.

• If you want to reproduce the guide, you will may want to checkout the example project from our source coderepository or you should be able to create the necessary project structure, typemapping file and transformationworkflow yourself. See ??? for more information about our source code repository, ??? for more informationabout the recommended project structure, ??? for more information about typemapping files or ??? for moreinformation about transformation workflow files.

3.2.1. The UML Domain ModelWe start with the domain model shown in Figure 3.2, “” and created in Section 3.1, “Map a Problem Domain to anUML Domain Model”.

Figure 3.2.

<xi:include></xi:include>

Draft How To Guides Draft

23

We want to extend the domain model a bit so that a Customer has the ability to obtain some information ofits accounts electronically. We add a login attribute to identify the customer. Then we add a password and aretypedPassword attribute for authentication. The retypedPassword is just there to verify a correct enteredpassword when changing it. We will use the type String for login and a domain type Password for both passwordattributes. (But feel free to specify a domain type Login for the login.)

3.2.2. Mandatory UML StereotypesTo transform an UML class model into JPA annotated Java source code you just have to mark all persistent classes.Simply assign the stereotype jpaPersistentEntity to any class which instances you want to store in a database.You should end up with an UML model similar to Figure 3.3, “”.

Figure 3.3.

<xi:include></xi:include>

3.2.3. GeneSEZ TypemappingBefore you transform an UML domain model you have to consider the implementation of your domain data types.In our example it is Money, InterestRate, Period, Date, Email and PhoneNumber. In Java we have accessto a major standard programming library. We do not need to implement the domain data types itself. Instead, wegoing to use already existing types of the Java library.

To advise the Generator that we don't want to implement the domain data types ourself, we assign the stereotypeexternal of the GeneSEZ UML profile to our domain data types. See the External Types in GeneSEZ for moreinformation. Then our UML model should look similar to Figure 3.4, “Transformable UML domain model” .

Figure 3.4. Transformable UML domain model

Now we advised our Generator that we don't want to implement our domain data types. But we did not specifyyet which existing types we want to use for our domain data types. We do this by configuring the GeneSEZ TypeMapping in our application generator project. For each domain data type we add a mapping to an existing java type:

MoneyWe want to use the Java class java.math.BigDecimal [http://download.oracle.com/javase/6/docs/api/index.html?java/math/BigDecimal.html] for our type Money:

<tns:type from="Money"> <!-- the default mapping should return the type name --> <tns:to>BigDecimal</tns:to>

Draft How To Guides Draft

24

<!-- to use the type, we need an import statement --> <tns:context name="Import">javax.math.BigDecimal</tns:context></tns:type>

DateFor our dates, we want to use the Java class java.util.Date [http://download.oracle.com/javase/6/docs/api/index.html?java/util/Date.html].

<tns:type from="Date"> <tns:to>Date</tns:to> <tns:context name="Import">java.util.Date</tns:context></tns:type>

InterestRateThe rate of our interests should be the primitive type double. You can also use the wrapper typejava.lang.Double [http://download.oracle.com/javase/6/docs/api/index.html?java/lang/Double.html] if youwant.

<tns:type from="InterestRate"> <tns:to>double</tns:to> <!-- suppress the generation of the import statement because double is a primitive type --> <tns:context name="Import"></tns:context></tns:type>

Period, Email, PhoneNumber, PasswordThe remaining mappings are similar to the mapping of InterestRate. For Period we can use the primitivetype long and for Email, PhoneNumber and Password simply the class java.lang.String [http://download.oracle.com/javase/6/docs/api/index.html?java/lang/String.html].

Your UML domain model is now transformable into JPA annotated Java source code using GeneSEZ.

3.2.4. Generated JPA annotated Java Source CodeNow you can transform your UML domain model into Java source code by using a workflow. If you take a closerlook to the generated Java source code, you will recognize that a lot of things happened automatically. We will usethe class Bank.

Type DefinitionAs expected our persistent class has the @Entity [http://download.oracle.com/javaee/5/api/javax/persistence/Entity.html] annotation. It also implements the interface java.io.Serializable [http://download.oracle.com/javase/1.5.0/docs/api/java/io/Serializable.html]. In addition, it has the @Table [http://download.oracle.com/javaee/5/api/javax/persistence/Table.html] annotation present to prevent potentialnaming conflicts with database names. See persistent entities for more information.

@Entity@Table(name = "tbl_Bank")public class Bank implements Serializable { // ...}

Persistent AttributesAll attributes of the class are considert as persistent attributes. References to other entities are automaticallyannotated using the multiplicity information of the UML domain model. The default cascade operations areadded as well as a standard mappedBy value. See persistent and transient attributes for more information.

@ManyToMany(cascade = {}, mappedBy = "bank")private java.util.List<Customer> customer = new java.util.LinkedList<Customer>();

@OneToMany(cascade = {}, mappedBy = "bank")private java.util.List<AbstractAccount> account = new java.util.LinkedList<AbstractAccount>();

Draft How To Guides Draft

25

// ...

private String name;

Additional AttributesYou will notice that two additional attributes are generated. One to uniquely identify your objects using a primiarykey and one for optimistic locking.

@Id@GeneratedValue(strategy = GenerationType.AUTO)private int id;

@Versionprivate int version;

Standard ConstructorYou may wonder why we have just one constructor in our UML model and the source code contains a secondone. The standard constructor is automatically added due to the JPA specification.

public Bank() {}

Get- and Set-Methods (Accessors)For every attribute and single-value association (toOne) you will find a corresponding get and set-methodaccording to the Java Beans convention. See JPA accessor methods for more information.

public String getName() { return name;}

public void setName(String name) { this.name = name;}

Get-, InsertIn- and RemoveFrom-Methods (Accessors)For every multi-value association (toMany) you will find a corresponding get- and instead of a set-method aninsertIn- and removeFrom-method. The insertIn- and removeFrom-method automatically take careabout the inverse link of bidirectional associations to keep a valid object model. See the GeneSEZ AssociationHandling for more information.

Your generated Java source code is JPA compliant and you are already able to persist your domain objects.

3.2.5. Adjusting the Persistence MappingIn most cases there is no need to further adjust the generated JPA annotated Java source code. But sometimes youmay want to adjust the persistence mapping. This is no problem and we will look at some typical cases:

Unique Bank NamesIn our example each Bank has a name. We want that each bank has a different name. We need to apply aunique constraint to the name attribute. We do this by assigning the stereotype jpaColumn to the nameattribute and set the tagged value unique to true.

@Column(name = "name", unique = true, nullable = false)private String name;

Transient AttributesThe attribute retypedPassword on class Customer is just to validate the entered password. We don't wantto have it in our database. We achiev this by assigning the stereotype jpaDatatypeMapping to the attributeand set the tagged value transient to true.

@Basic(optional = true)

Draft How To Guides Draft

26

@Transientprivate String retypedPassword;

Providing customized set methodsWhat our security awareness already detected: We don't want to store passwords in plain text in the databasenor keeping them a long time in memory! To prevent this we have to override the set methods for the attributespassword and retypedPassword on class Customer. We assign the stereotype accessor to bothattributes and set the tagged value setter on both to false. Then we add two set operations for bothpassword attributes to our class.

public void setPassword(String password) { /* PROTECTED REGION ID(java.implementation._17_0_1_b6f02e1_1298714296495_444774_2036) ENABLED START */ // TODO: implementation of method 'Customer.setPassword(...)' throw new UnsupportedOperationException("The implementation of this generated method stub is missing!"); /* PROTECTED REGION END */}

public void setRetypedPassword(String password) { /* PROTECTED REGION ID(java.implementation._17_0_1_b6f02e1_1298714309173_856487_2039) ENABLED START */ // TODO: implementation of method 'Customer.setRetypedPassword(...)' throw new UnsupportedOperationException("The implementation of this generated method stub is missing!"); /* PROTECTED REGION END */}

So we get two operations in which we create a hash from the given password parameter and store the hashon the respective attribute.

Note

In future releases of GeneSEZ you do not need to acessor stereotype any longer to override a setmethod. The transformations will notice that there are two duplicate operations to be generated and willgive your operation precedence instead of the automatically added set method.

Moreover there will be a special treatment for password attributes and you will get set methods usinghash algorithms.

Cascading Entity OperationsLets assume that if you want to remove an Account you want to remove all its Statements. To achiev this,you simply assign the stereotype jpaAssociation to the association end on the Statement side and setthe tagged value cascade to jpaCascadeType REMOVE .

@OneToMany(cascade = {CascadeType.REMOVE})private java.util.List<Statement> statement = new java.util.LinkedList<Statement>();

Inheritance MappingLets assume you don't want the JPA default inheritance mapping SINGLE_TABLE but instead theTABLE_PER_CLASS mapping. All you have to do is to assign the stereotype jpaInheritance to the classAccount and set the tagged value strategy to jpaInheritanceType TABLE_PER_CLASS . Then you getthe inheritance stragegy and the @Table annotations on all subclasses to prevent potential naming conflicts.

@Entity @Table(name = "tbl_Account") @Inheritance(strategy = InheritanceType.TABLE_PER_CLASS) public abstract class AbstractAccount implements Serializable { //... }

Draft How To Guides Draft

27

@Entity @Table(name = "tbl_CheckingAccount") public class CheckingAccount extends AbstractAccount implements Serializable { //... }

@Entity @Table(name = "tbl_FlexibleSavingsAccount") public class FlexibleSavingsAccount extends AbstractAccount implements Serializable { //... }

@Entity @Table(name = "tbl_SavingsAccount") public class SavingsAccount extends AbstractAccount implements Serializable { //... }

By performing these adjustments your UML class model should now look similar to Figure 3.5, “UML domain modelwith adjusted persistence mapping” .

Figure 3.5. UML domain model with adjusted persistence mapping

<xi:include></xi:include>

This should conclude our persistence mapping adjustment tour. Now you should have a basic idea about howto adjust the persistence mapping. For a concise description of the JPA transformation see Section 1.1, “JavaPersistence API (JPA)”. See Section 4.2, “ The GeneSEZ JPA UML Profile ” for the reference of the GeneSEZ JPAUML profile. Overall, don't forget it is GeneSEZ and see the GeneSEZ Customization Guide for more sophisticatedadjustments.

Draft Draft

28

Chapter 4. UML Profile ReferenceThis section contains a detailed description of UML profiles useful to develop Java Enterprise Applications. You cansee this section as a kind of API documentation for the UML profiles.

4.1. The GeneSEZ UML Profile

Figure 4.1. GeneSEZ UML Profile

4.1.1. Stereotype externalA stereotype which is used to mark classifiers as external types or packages as container for external types

4.1.2. Stereotype accessorA stereotype which is used to control the generation of getter + setter methods more precise

getter : Boolean = true

setter : Boolean = false

4.1.3. Stereotype excludeA stereotype used to exclude model elements from tranformation into GeneSEZ models.

4.1.4. Stereotype diA stereotype used to annotate attributes to indicate the need for an appropriate set method for a dependencyinjection framework or inversion of control container.

setter : Boolean = true

constructor : Boolean = false

4.1.5. Stereotype volatileA Stereotype which is used to mark a property to prevent their values from any caching mechanism.

Draft UML Profile Reference Draft

29

4.1.6. Stereotype primitive

is used to mark a property, operation or parameter to advise the generator to use a primitive type for a multiplicity-many feature

4.2. The GeneSEZ JPA UML ProfileThis profile contains stereotypes, tagged values and data types to model persistent java domain models using theJava Persistence API (JPA).

Draft UML Profile Reference Draft

30

Figure 4.2. GeneSEZ UML Profile for the Java Persistence API (JPA)

4.2.1. Enumeration jpaDatatypeAllows to further describes the mapping of the datatype of a property to the database. It is an aggregation of severalJPA annotations.

BasicThis annotation is the simplest type of mapping to a database column. It can be applied to aproperty of vaious types, including primitives, wrapper types, temporal types and any type implementing

Draft UML Profile Reference Draft

31

java.io.Serializable [http://download.oracle.com/javase/1.5.0/docs/api/java/io/Serializable.html]. Seethe annotation Basic [http://download.oracle.com/javaee/5/api/javax/persistence/Basic.html] of the JPAspecification.

EmbeddableDefines a class whose instances are stored as an intrinsic part of an owning entity and share the identity ofthe entity. Each of the persistent properties or fields of the embedded object is mapped to the database tablefor the entity. See the annotation Embeddable [http://download.oracle.com/javaee/5/api/javax/persistence/Embeddable.html] of the JPA specification.

LobSpecifies that a persistent property or field should be persisted as a large object to a database-supported largeobject type. It can be a binary or character type. See the annotation Lob [http://download.oracle.com/javaee/5/api/javax/persistence/Lob.html] of the JPA specification.

TemporalThis annotation must be specified for persistent fields or properties of type java.util.Date[http://download.oracle.com/javase/1.5.0/docs/api/java/util/Date.html] and java.util.Calendar [http://download.oracle.com/javase/1.5.0/docs/api/java/util/Calendar.html]. See the annotation Temporal [http://download.oracle.com/javaee/5/api/javax/persistence/Temporal.html] of the JPA specification.

EnumeratedSpecifies that a persistent property or field should be persisted as a enumerated type. See theannotation Enumerated [http://download.oracle.com/javaee/5/api/javax/persistence/Enumerated.html] of theJPA specification.

4.2.2. Enumeration jpaInheritanceTypeDefines the possible inheritance mapping strategies for JPA. It is the UML counterpart of the enumerationInheritanceType [http://download.oracle.com/javaee/5/api/javax/persistence/InheritanceType.html] of the JPAspecification.

SINGLE_TABLEIndicates that a single table per class hierarchy is used to store entity objects. It is the JPA default.

TABLE_PER_CLASSA table per concrete entity class.

JOINEDA strategy in which fields that are specific to a subclass are mapped to a separate table than the fields that arecommon to the parent class, and a join is performed to instantiate the subclass.

4.2.3. Enumeration jpaCascadeType

ALL

PERSIST

MERGE

REMOVE

REFRESH

4.2.4. Enumeration jpaDescriminatorType

STRING

CHAR

Draft UML Profile Reference Draft

32

INTEGER

4.2.5. Enumeration jpaContextType

TRANSACTION

EXTENDED

4.2.6. Enumeration jpaEnumTypeSpecifies how enumeration literals are stored in the database. It is the UML counterpart of the enumerationEnumType [http://download.oracle.com/javaee/5/api/javax/persistence/EnumType.html] of the JPA specification.

ORDINALPersist enumerated type property or field as an integer, i.e. the ordinal value of the enumeration literal.

STRINGPersist enumerated type property or field as a string, i.e. the string representation of the enumeration literal.

4.2.7. Enumeration jpaFetchTypeSpecifies how data is fetched from the database. It is the UML counterpart of the enumeration FetchType [http://download.oracle.com/javaee/5/api/javax/persistence/FetchType.html] of the JPA specification.

DEFAULT

EAGERDefines that data must be fetched eagerly, i.e. when an entity object is fetched from the database.

LAZYDefines that data can be fetched lazily, i.e. when the data is needed and not necessarily when the entity objectis fetched from the database.

4.2.8. Enumeration jpaGenerationType

AUTO

TABLE

SEQUENCE

IDENTITY

4.2.9. Enumeration jpaTemporalTypeSpecifies how temporal types (time and date) specifically java.util.Date [http://download.oracle.com/javase/1.5.0/docs/api/java/util/Date.html] and java.util.Calendar [http://download.oracle.com/javase/1.5.0/docs/api/java/util/Calendar.html] are stored within the database. It is the UML counterpart of theenumeration TemporalType [http://download.oracle.com/javaee/5/api/javax/persistence/TemporalType.html] ofthe JPA specification.

DATEMap as java.sql.Date [http://download.oracle.com/javase/1.5.0/docs/api/java/sql/Date.html].

TIMEMap as java.sql.Time [http://download.oracle.com/javase/1.5.0/docs/api/java/sql/Time.html].

TIMESTAMPMap as java.sql.Timestamp [http://download.oracle.com/javase/1.5.0/docs/api/java/sql/Timestamp.html].

Draft UML Profile Reference Draft

33

4.2.10. Enumeration jpaAssociationType

AutoDetect

OneToOne

OneToMany

ManyToOne

ManyToMany

4.2.11. Stereotype jpaJoinColumn

columnDefinition : String

insertable : Boolean = true

name : String

nullable : Boolean = true

referencedName : String

table : String

unique : Boolean = false

updatable : Boolean = true

4.2.12. Stereotype jpaInheritance

strategy : jpaInheritanceType

4.2.13. Stereotype jpaColumn

name : String

unique : Boolean = false

nullable : Boolean = true

insertable : Boolean = true

updatable : Boolean = true

columnDefinition : String

table : String

length : int = 255

precision : int = 0

scale : int = 0

4.2.14. Stereotype jpaPersistenceContext

name : String

Draft UML Profile Reference Draft

34

type : jpaContextType

unitName : String

4.2.15. Stereotype jpaCallback

postConstruct : Boolean = false

preDestroy : Boolean = false

postActivate : Boolean = false

prePassivate : Boolean = false

prePersist : Boolean = false

postPersist : Boolean = false

preUpdate : Boolean = false

postUpdate : Boolean = false

preRemove : Boolean = false

postRemove : Boolean = false

postLoad : Boolean = false

external : Boolean = false

4.2.16. Stereotype jpaPersistentEntitySpecifies a UML class as a persistent entity. It triggers the generation of the @Entity [http://download.oracle.com/javaee/5/api/javax/persistence/Entity.html] annotation. The tagged values tableName,tableCatalog and tableSchema are properties of the @Table [http://download.oracle.com/javaee/5/api/javax/persistence/Table.html] annotation. This annotation is automatically added due to potential naming conflictsbetween domain model and database names. Last but not least this stereotype triggers the implementation of theinterface java.io.Serializable [http://download.oracle.com/javase/1.5.0/docs/api/java/io/Serializable.html] forthe entity class.

name : StringName of the reference in the environment naming context (ENC). Defaults to the class name. You can find thereference by using a Java naming and directory interface (JNDI) lookup.

optimisticLocking : Boolean = trueEnables or disables optimistic locking support for entities. Default is enabled.

tableName : StringIs a property of the annotation @Table and specifies the name of the table for the persistent entity. To preventnaming conflicts with reserved names in the database (e.g. group) the prefix tbl_ is automatically added.

tableCatalog : StringSpecifies the table catalog.

tableSchema : StringSpecifies the table schema.

4.2.17. Stereotype jpaAssociation

cascade : jpaCascadeType

Draft UML Profile Reference Draft

35

fetch : jpaFetchType

mappedBy : Boolean

optional : Boolean = true

targetEntity : String

type : jpaAssociationType = AutoDetect

4.2.18. Stereotype jpaDatatypeMappingAllows to adjust the persistence mapping of an attribute.

type : jpaDatatypeAllows to further specify the datatype, see the enumeration jpaDatatype.

temporalType : jpaTemporalTypeIs used in conjunction with the tagged value type = jpaDatatype.TEMPORAL to specify how the values oftemporal types (time and date) are stored in the database.

optional : Boolean = trueSpecifies if the property is mandatory or optional. The value false implies that each entity instance must havea value to this property assigned.

fetch : jpaFetchTypeSpecifies how data is fetched from the database.

enumType : jpaEnumType = ORDINALSpecifies how enumerations are stored in the database.

transient : Boolean = falseDefines a property as transient, i.e. not persistent.

4.2.19. Stereotype jpaDiscriminatorValue

value : String

4.2.20. Stereotype jpaPrimaryKeyJoinColumn

name : String

referencedName : String

columnDefinition : String

4.2.21. Stereotype jpaDescriminatorColumn

name : String = "DTYPE"

discriminatorType : jpaDescriminatorType

columnDefinition : String

length : int = 31

4.2.22. Stereotype jpaPrimaryKey

Draft UML Profile Reference Draft

36

embeddedId : Boolean = false

generatorName : String

generatedValue : Boolean = false

strategy : jpaGenerationType = AUTO

4.2.23. Stereotype jpaEntityListener

excludeDefaultListeners : Boolean

excludeSuperclassListeners : Boolean

generateDefault : Boolean = true

listeners : String

4.2.24. Stereotype jpaJoinTable

catalog : String

name : String

schema : String

uniqueConstraints : String

4.2.25. Stereotype jpaPersistenceUnit

name : String

unitName : String

4.2.26. Stereotype jpaIJoinColumn

columnDefinition : String

insertable : Boolean = true

name : String

nullable : Boolean = true

referencedName : String

table : String

unique : Boolean = false

updatable : Boolean = true

4.2.27. Stereotype jpaPrimaryKeyClass

embeddable : Boolean = false

name : String

Draft UML Profile Reference Draft

37

4.2.28. Stereotype jpaTableGenerator

allocationSize : int

initialValue : int

name : String

pkColumnName : String

pkColumnValue : String

table : String

valueColumnName : String

4.2.29. Stereotype jpaSequenceGenerator

allocationSize : int

initialValue : int

name : String

sequenceName : String