Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Texo/Code Generation Details"

(EPackage Model Gen Features)
(Introduction)
 
(10 intermediate revisions by one other user not shown)
Line 7: Line 7:
 
This document describes how the annotations model works and how you can generate/define the annotations model.
 
This document describes how the annotations model works and how you can generate/define the annotations model.
  
'''Note: annotations model can only be created for ecore models stored in .ecore files so not for xsd's. You can easily create an ecore model from an xsd by right-clicking a xsd and then do Texo > Generate Ecore Model.'''
+
'''Notes:'''
 +
* Dao generation: Texo supports generation of Dao classes, certain model annotation properties are focused on Dao generation, this is described in the [[Texo/Dao|Texo Dao]] section.
 +
* annotations model can only be created for ecore models stored in .ecore files so not for xsd's. You can easily create an ecore model from an xsd by right-clicking a xsd and then do Texo > Generate Ecore Model.
 +
 
 +
 
 +
[[Image:texo.annotated_model_runtime.png|center|600px]]
  
 
== What is an Annotations Model ==
 
== What is an Annotations Model ==
Line 14: Line 19:
  
  
[[Image:org.eclipse.emf.texo.annotations.model.png|center|700px]]
+
[[Image:org.eclipse.emf.texo.annotations.model.png|center]]
  
  
Line 29: Line 34:
  
  
[[Image:org.eclipse.emf.texo.initial.annotations.model.png|center|400px]]
+
[[Image:org.eclipse.emf.texo.initial.annotations.model.png|center|450px]]
  
  
Line 35: Line 40:
  
  
[[Image:org.eclipse.emf.texo.complete.structure.annotations.model.png|center|400px]]
+
[[Image:org.eclipse.emf.texo.complete.structure.annotations.model.png|center|450px]]
  
  
Line 41: Line 46:
  
  
[[Image:org.eclipse.emf.texo.fully.annotated.annotations.model.png|center|400px]]
+
[[Image:org.eclipse.emf.texo.fully.annotated.annotations.model.png|center|450px]]
  
 
== Manually adding annotations, Editing annotations ==
 
== Manually adding annotations, Editing annotations ==
Line 48: Line 53:
  
  
[[Image:org.eclipse.emf.texo.complete.manually.adding.annotation.png|center|600px]]
+
[[Image:org.eclipse.emf.texo.complete.manually.adding.annotation.png|center|650px]]
  
  
Line 54: Line 59:
  
  
[[Image:org.eclipse.emf.texo.annotation.properties.png|center|600px]]
+
[[Image:org.eclipse.emf.texo.annotation.properties.png|center|650px]]
 +
 
 +
 
 +
'''NOTE: the editor supports copy/paste, however copy/pasting of nodes should not be done as the copied nodes will still refer to the original model element they were copied from. This is a bug/missing feature which will be solved in the short future.'''
  
 
== How Texo uses the Annotations Model ==
 
== How Texo uses the Annotations Model ==
Line 77: Line 85:
 
* '''Documentation''': is added to the javadoc of the generated ModelPackage/ModelFactory classes.
 
* '''Documentation''': is added to the javadoc of the generated ModelPackage/ModelFactory classes.
 
* '''Feature Map Class Name Postfix''': to support [http://www.eclipse.org/modeling/emf/docs/overviews/FeatureMap.pdf EMF FeatureMaps] Texo [[Texo/Code_Generation_Patterns#Handling_Feature_Maps|generates]] extra classes, the value of this property is used as the post fix of the class name.
 
* '''Feature Map Class Name Postfix''': to support [http://www.eclipse.org/modeling/emf/docs/overviews/FeatureMap.pdf EMF FeatureMaps] Texo [[Texo/Code_Generation_Patterns#Handling_Feature_Maps|generates]] extra classes, the value of this property is used as the post fix of the class name.
 +
* '''Generate bi-directional association support''': if set to true will support automatically setting the other side of a bi-directional association. To also support bi-directional support for many associations the '''Generate safe many access''' also has to be set to true. For more information see [[Texo/Code_Generation_Patterns#Generation_of_a_safe_bi-directional_association_API_.28or_not.29|this page]].
 
* '''Generate safe many access''': if set to true will generate additional methods for adding/removing elements from an EReference which has many==true. For more information see [[Texo/Code_Generation_Patterns#Generation_of_a_safe_bi-directional_association_API_.28or_not.29|this page]].
 
* '''Generate safe many access''': if set to true will generate additional methods for adding/removing elements from an EReference which has many==true. For more information see [[Texo/Code_Generation_Patterns#Generation_of_a_safe_bi-directional_association_API_.28or_not.29|this page]].
 
* '''Java File Header''': is placed in the header of each generated java file, can be used for copyright statements.
 
* '''Java File Header''': is placed in the header of each generated java file, can be used for copyright statements.
Line 85: Line 94:
 
* '''Root Class Extends''': sets the super class for generated java entity class which do not have a super class, must be a fully qualified class name.
 
* '''Root Class Extends''': sets the super class for generated java entity class which do not have a super class, must be a fully qualified class name.
 
* '''Root Interface Extends''': sets the super interface(s) for generated java interfaces which do not have a super class, can be a list of comma-delimited fully qualified class names.
 
* '''Root Interface Extends''': sets the super interface(s) for generated java interfaces which do not have a super class, can be a list of comma-delimited fully qualified class names.
 +
* '''Feature Map Class Extends''': Texo generates a class for each feature map, Texo can be directed to let these classes extend another class through this feature.
  
 
=== EClass Model Gen Features ===
 
=== EClass Model Gen Features ===
Line 102: Line 112:
 
* '''Use List''': for many EStructuralFeatures, if true then java.util.List/java.util.ArrayList is used, if false then java.util.Set/java.util.HashSet is used for the generated api and implementation. Note if this property is not specified then the ordered feature of the EStructuralFeature is used to determine if java.util.List or java.util.Set should be used.
 
* '''Use List''': for many EStructuralFeatures, if true then java.util.List/java.util.ArrayList is used, if false then java.util.Set/java.util.HashSet is used for the generated api and implementation. Note if this property is not specified then the ordered feature of the EStructuralFeature is used to determine if java.util.List or java.util.Set should be used.
 
* '''Valid Java Member Name''': the name of the java member used to store the value of the EStructuralFeature.
 
* '''Valid Java Member Name''': the name of the java member used to store the value of the EStructuralFeature.
* '''Generate safe many access''': defaulted from the same property set in the EPackage Model Gen annotation, if set to true will generate additional methods for adding/removing elements from an EReference which has many==true. For more information see [[Texo/Code_Generation_Patterns#Generation_of_a_safe_bi-directional_association_API_.28or_not.29|this page]].
+
* '''Generate safe many access''' (for ereferences): defaulted from the same property set in the EPackage Model Gen annotation, if set to true will generate additional methods for adding/removing elements from an EReference which has many==true. For more information see [[Texo/Code_Generation_Patterns#Generation_of_a_safe_bi-directional_association_API_.28or_not.29|this page]].
 +
* '''Generate bi-directional association support''' (for ereferences): defaulted from the same property set in the EPackage Model Gen annotation, if set to true will support automatically setting the other side of a bi-directional association. To also support bi-directional support for many associations the '''Generate safe many access''' also has to be set to true. For more information see [[Texo/Code_Generation_Patterns#Generation_of_a_safe_bi-directional_association_API_.28or_not.29|this page]].
  
 
An EAttribute Model Gen has the following additional feature:
 
An EAttribute Model Gen has the following additional feature:
Line 118: Line 129:
 
* '''Generate code''': if true then Texo will generate a java representation for this data type.
 
* '''Generate code''': if true then Texo will generate a java representation for this data type.
 
* '''Instance Class Name''': the instance class of the enum, corresponds to the generated enum class file.
 
* '''Instance Class Name''': the instance class of the enum, corresponds to the generated enum class file.
 +
 +
=== Dao Generation Annotations ===
 +
 +
There are several annotation properties which control the generation of Dao's. These properties are described [[Texo/Dao#Annotation_properties_to_control_Dao_Generation|here]].

Latest revision as of 16:08, 1 April 2012

Introduction

The Texo code generation is controlled by annotations on the model. These annotations control the class names, names of methods and java package names. When Teneo generates code it will automatically create these annotations (in-memory) for each model element (EClass, EStructuralFeature). However, it is also possible to define these annotations in a so-called Annotations Model. This gives you the possibility to override the choices made by the Texo code generator. Texo will use these manual annotations and add its own annotations to have a complete annotated model.

This document describes how the annotations model works and how you can generate/define the annotations model.

Notes:

  • Dao generation: Texo supports generation of Dao classes, certain model annotation properties are focused on Dao generation, this is described in the Texo Dao section.
  • annotations model can only be created for ecore models stored in .ecore files so not for xsd's. You can easily create an ecore model from an xsd by right-clicking a xsd and then do Texo > Generate Ecore Model.


Texo.annotated model runtime.png

What is an Annotations Model

An annotations model is very similar to the ecore model. An annotations model has references to the original ecore model and adds extra information to store directives for code generation. The screenshot below shows an example of an annotations model.


Org.eclipse.emf.texo.annotations.model.png


The above screenshot shows an annotations model. The model follows the same structure as the original ecore model (the rental.ecore in this example). So there is a node for the EPackage, there are nodes for each EClass/EDataType and for each EStructuralFeature.

Within each node you can see the annotation: the nodes starting with 'Model Gen'. In this case the annotations are for generating model code (the entities). For example the node 'Annotated EPackage: org.eclipse.emf.texo.test.model.samples.rental' has a child node 'Model Gen Annotation rental' which contains the properties used to generate java entities.

The screenshot selects a model gen annotation for the EAttribute RentalBicycle.type. In the properties view you can see the properties which are used by the code generation. For example the name of the generated getter and setter java methods.

How to create an Annotations Model

The first step is creating an annotations model. You can create a first annotations model by right clicking an ecore file and selecting the menu option 'Texo', then several menu options are shown to you (menu titles may vary slightly, depending on the Texo version):

  • Create Initial Empty Annotations Model: this will create an annotations model with only nodes for the EPackages, the annotations model does not contain any annotations. These can be added individually (see below).


Org.eclipse.emf.texo.initial.annotations.model.png


  • Create/Update Annotations Model Structure: this will create an annotations model with nodes for all model elements of the original model. This means that there are nodes created for all EPackages, EClasses, EDataTypes and EStructuralFeatures. But no annotations are created, these can be added manually (see below).


Org.eclipse.emf.texo.complete.structure.annotations.model.png


  • Create/Update Completely Annotated Model: this will create a fully annotated model with an annotation for all model elements and all model elements of the original model are present.


Org.eclipse.emf.texo.fully.annotated.annotations.model.png

Manually adding annotations, Editing annotations

Annotations can be added manually by right clicking on a model node in the Annotations Model and then choose New Child. The available annotations which can be added are listed as children. In the screenshot below a Model Gen Annotation can be added. This type of annotation is used to control the generation of java entities.


Org.eclipse.emf.texo.complete.manually.adding.annotation.png


After adding an annotation you can edit the annotation properties in the properties view:


Org.eclipse.emf.texo.annotation.properties.png


NOTE: the editor supports copy/paste, however copy/pasting of nodes should not be done as the copied nodes will still refer to the original model element they were copied from. This is a bug/missing feature which will be solved in the short future.

How Texo uses the Annotations Model

The annotations model needs to be located in the same folder as the ecore model it applies to. The name of the file should be equal to the ecore model file name, only the file extension is different, instead of .ecore it should end on .annotationsmodel.

When code is generated for an EPackage or when an EPackage is referenced then Texo will automatically read the annotations model file. Texo will preserve all the annotations in the file and only add annotations or set features which have not been set manually.

Partially Annotating a Model

You only need to specify annotations for the parts of the code generation you want to override. So an annotations model with only a few annotations is fine. Texo will automatically add/generate annotations without overriding the manually created annotations. Even the properties/features of an annotation only need to be partially specified, Texo will automatically set the non-set properties/features of a manual annotation.

Code Generation Properties (annotations)

This section gives a detailed description of the properties/features in the annotations model used for code generation.

Note: when editing Model Gen annotations a short description of the property is shown in the status bar in the bottom of the Eclipse window.

EPackage Model Gen Features

  • Add Runtime Model Behavior: Texo will generate 2 classes (the ModelFactory/ModelPackage) for integrating the java entities with a runtime Model. These 2 classes have dependencies on EMF. Set this property to false if you don't want any EMF compile time dependency, the consequence is that there is no runtime model and no XML/XMI serialization support. If set to true then the ModelFactory/ModelPackage are generated and the model is then available at runtime (with XML/XMI serialization support).
  • Documentation: is added to the javadoc of the generated ModelPackage/ModelFactory classes.
  • Feature Map Class Name Postfix: to support EMF FeatureMaps Texo generates extra classes, the value of this property is used as the post fix of the class name.
  • Generate bi-directional association support: if set to true will support automatically setting the other side of a bi-directional association. To also support bi-directional support for many associations the Generate safe many access also has to be set to true. For more information see this page.
  • Generate safe many access: if set to true will generate additional methods for adding/removing elements from an EReference which has many==true. For more information see this page.
  • Java File Header: is placed in the header of each generated java file, can be used for copyright statements.
  • Model Classes Package Path: makes it possible to generate the ModelFactory/ModelPackage classes in a separate package from the entity classes themselves. As a default is the same as the 'Package Path'. See here for more information.
  • Package Path: the java package in which the java entities are generated. Is created on the basis of the name space uri of the EPackage (the same logic as used by EMF).
  • Simple Class Name: the class name used for the Model Package, as a default the EPackage name followed by the post fix 'ModelPackage' is used.
  • Simple Model Factory Class Name: the class name used for the Model Factory, as a default the EPackage name followed by the post fix 'ModelFactory' is used.
  • Root Class Extends: sets the super class for generated java entity class which do not have a super class, must be a fully qualified class name.
  • Root Interface Extends: sets the super interface(s) for generated java interfaces which do not have a super class, can be a list of comma-delimited fully qualified class names.
  • Feature Map Class Extends: Texo generates a class for each feature map, Texo can be directed to let these classes extend another class through this feature.

EClass Model Gen Features

  • Class Extends: the fully qualified class name of the super class.
  • Class Implements: a list of fully qualified names of interfaces implemented by this class.
  • Generate Code: if false then no code is generated for this EClass, the qualified class name is used for references to this EClass. See here for a description of the usecase.
  • Qualified Class Name: the fully qualified java class name used for this EClass. If not set then the package path of the EPackage Model Gen annotation is used together with the EClass name.
  • Serializable: if true then the java class will extend java.io.Serializable.

EAttribute/EReference Model Gen Features

  • Documentation: is added as javadoc in the field, getter and setter.
  • Generate Code: if false then no java member, getter/setter is generated for this EStructuralFeature.
  • Getter: the name of the getter method used in the java code.
  • Setter: the name of the setter method used in the java code.
  • Use List: for many EStructuralFeatures, if true then java.util.List/java.util.ArrayList is used, if false then java.util.Set/java.util.HashSet is used for the generated api and implementation. Note if this property is not specified then the ordered feature of the EStructuralFeature is used to determine if java.util.List or java.util.Set should be used.
  • Valid Java Member Name: the name of the java member used to store the value of the EStructuralFeature.
  • Generate safe many access (for ereferences): defaulted from the same property set in the EPackage Model Gen annotation, if set to true will generate additional methods for adding/removing elements from an EReference which has many==true. For more information see this page.
  • Generate bi-directional association support (for ereferences): defaulted from the same property set in the EPackage Model Gen annotation, if set to true will support automatically setting the other side of a bi-directional association. To also support bi-directional support for many associations the Generate safe many access also has to be set to true. For more information see this page.

An EAttribute Model Gen has the following additional feature:

  • Feature Map Qualified Class Name: if this EAttribute is a Feature Map, is the name of the feature map class generated by Texo, see this page for more information.

EDataType Model Gen Features

  • Automatic String Conversion: set to true if the java type has a constructor with a single String argument and a toString method which work symmetrically with this constructor. Then the ModelFactory will make use of this. Set to false in otherwise.
  • Instance Class Name: the instance class name to use for this type.

EEnum Model Gen Features

  • Automatic String Conversion: set to true if the java type has a constructor with a single String argument and a toString method which work symmetrically with this constructor. Then the ModelFactory will make use of this. Set to false in otherwise.
  • Documentation: added as javadoc to the generated java enum class.
  • Generate code: if true then Texo will generate a java representation for this data type.
  • Instance Class Name: the instance class of the enum, corresponds to the generated enum class file.

Dao Generation Annotations

There are several annotation properties which control the generation of Dao's. These properties are described here.

Back to the top