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

Texo/Design Concepts

< Texo
Revision as of 07:26, 31 January 2010 by Mtaal.springsite.com (Talk | contribs) (Annotated Models, Annotation generation with manual overrides)

Introduction

This page gives an overview of the main design ideas which are the basis for the Texo project.

Annotated Models, Annotation generation with manual overrides

Generating and working with model annotations is the core concept of Texo development.

A model annotation is very similar to a Java source code annotation. So just as you can annotate a java class or field it is possible to annotate a model also (its EClass and EStructuralFeature). A very good example of a project making use of annotated models is the Teneo project which makes use of JPA annotations in the model to drive the relational persistence for EMF objects.

Model annotations are used in different ways:

  • as input for the artifact generation: implementation of templates (used to generate code and files) is much easier if it can work with a complete fully-annotated model
  • as output to be placed in generated artifacts: model annotations can be converted into annotations in the java code or can be used to generate a separate file (for example an orm.xml)
  • at runtime to control runtime behavior

Software artifact generation often consists of two steps:

  • read the model and enrich it with additional information
  • call a template to generate the artifact using the enriched model

It is important to enrich the model in step 1 because it is far easier to implement a template if all the main generation choices have been made up-front. The template then just has to follow the decisions reflected in the enriched model.

Texo makes model-enrichment more explicit: an enriched model corresponds to an annotated model.


Basic Flow: Annotations and Annotators

Difference with GenModel approaches

Annotation Models

Initially Texo will support two annotation models (annotation sets):

  1. annotations for model generation itself (to set the name of java class for example)
  2. JPA annotations: to support

In a next phase new annotation models are planned to be added, for example for EJB3 (Seam) or Hibernate Search.

Runtime Model

Texo differs from other code generation approaches (except for EMF itself) in that specific attention is paid to support of a runtime representation of the domain model.

The domain model is expressed in ecore or XSD and with the model annotations drives the code generation. At runtime it is important to also have the possibility to work with this domain model and to access the generated code using model constructs.

Model-driven functionality (at runtime)

Many applications have functions which make sense to implement at model level instead of at specific instance/type level. Some examples:

  • archiving: implement a generic archiving model which uses the runtime model to interrogate objects and retrieve changed and new property values.
  • security: define security using entities from the domain model. To support security definition changes at runtime it must be possible to address the model at runtime. To check security at runtime one needs access to the runtime model also (for specific instances).
  • export/import: export and import functions in an application can benefit from generic model-based logic. Implementing export/import using the runtime model is very efficient compared to writing a specific export/import per type in a system.

Another usage scenario for having the model available at runtime is that the model elements can be used to define other system components. An example of this is a system which allows users/consultants to define the user interface themselves through a user interface. To support the user/consultant in defining a user interface he/she must be able to select elements from the runtime model to define fields in a form or columns in a grid.

Runtime Model in Texo

The Texo runtime model functionality makes it possible to:

  • access the available EPackages which have been loaded/initialized and iterate over its EClassifiers and EFeatures.
  • (at runtime) determine the domain type (the EClass) represented by a pojo.
  • access (get/set) the values of EFeatures in a pojo at runtime
Texo.library model.png

Texo takes a different approach than EMF in making the runtime model available. In EMF each object always implements the EMF EObject interface or extends the EMF BasicEObjectImpl. Texo implements the runtime model outside of the pojo in a separate generated class which acts as a wrapper of the pojo to give it a 'Model-Face'.

The Texo runtime model is an ecore model (EPackage, EClass, etc.). The runtime model is accessible using the following classes:

  • The ecore model can be reached through the generated ModelPackage class (see image on the right). The ModelPackage provides access to the EClassifiers (EClass, EEnum) and EStructuralFeatures of a model.
  • The ModelFactory provides access to String converters and the generated Model wrappers.
  • The ModelResolver class (provided by the org.eclipse.emf.texo plugin) acts as a Model registry and manages all initialized and loaded ModelPackages.

For more information see this separate page on the Runtime Model.

Different approaches for linking pojo's and the runtime model

While designing and developing Texo different approaches have been tried to integrate pojo's and the runtime model. The current approach (generating separate wrapper classes which a Model interface) is chosen because:

  • best performance (compared to other approaches): all model access method calls are direct method calls which are compiled together with the rest of the code (so the java compiler can optimize).
  • manually changable: all the model access code is generated and can be changed by the developer. Texo will maintain/keep manual changes when re-generating the code.
  • simple/easy: adds no complexities at runtime (no special class handling) and requires no special setup when building (the generated code is just simple java classes).

Here is a description of the other approaches which have been tried or considered (and an argumentation why they were not used):

  • generate model annotations in the pojo: this fits very nicely in the Java annotation concept (use an annotation to attach metadata to a class). The reasons for not choosing this solution:
    • will add compile time dependency of the pojo to Texo annotations.
    • to call the correct getter/setter at runtime java reflection needs to be used. Method calls using Java reflection are about 100 times slower than non-reflection calls.
  • use class enhancement at runtime: so at runtime add the implementation of a Model interface to each pojo. The reason that this approach was not chosen:
    • this means that also a different classloader has to be used for Texo generated classes. Many frameworks (OSGI, Seam, ORM-solutions) also make use of class enhancement and their own classloading specifics. The feel is that there is too much risk in trying to integrate Texo runtime class enhancement with possibly unknown frameworks that want to make use of Texo.
    • when developing against the Model api you need to cast to the Model interface (as there is no , so you loose a bit of compile time checking.
    • possibly loose optimizations done by the java compiler when building
    • the implementation of the model interface can not be changed by the user (currently the Model wrapper is also generated and can be adapted by a user, the manual changes are maintained when re-generating).
  • enhance classes at build time: (see the very interesting Lombok project), the reason that this approach was not chosen:
    • we would force the user to change the build setup. Although Lombok and Java makes comparatively easy, build setup is a topic which should not be underestimated, so any change there is avoided as much as possible.
    • the class file is not insync with the source code, so debugging is more difficult

Work with generated code

There are roughly two schools of thought regarding how to handle and work with generated code.

One school of thought states that generated code should never be changed manually. Generated code should not be committed to a CVS. It should be possible to remove all the generated code, regenerate and then have the same situation as before. In this approach any manual/custom logic should be implemented in subclasses of the generated code. These subclasses can also be generated. This school of thought is what is propagated by developers from the XPand project.

The other school of thought states that it should be possible to change generated code. manual changes in the code should remain even if the code is re-generated. Generated code should be checked in to a CVS. This approach is followed by the EMF project.

Both groups consist of very experienced and very knowledgeable experts on the field of model-to-text transformation and code generation.

Texo follows the EMF approach (the second school of thought) because:

  • it feels more natural to change/add behavior to the generated class than to a 'dummy' subclass.
  • less classes are generated and the generated classes are kept in sync with the model.
  • manual code can easily be identified inside of generated classes.
  • the code generation does not update the file on the file system if it has not changed by code generation. This results in minimal changesets in a CVS, and much better, if something changes it is directly visible in CVS diffs etc.
  • by checking in the generated code to cvs it is much easier for others to work with the development project as no generation step is needed after getting the project or updates from a CVS. The same applies to re-distribution of regenerated code, by checking in the generated code (and the changes) it is much clearer what has changed and when people update from the CVS they will receive a consistent state directly.
  • Texo will re-organize imports and remove files which related to model elements which have been removed. As the code is checked in these removal actions are tracked in a CVS.

Back to the top