Difference between revisions of "Texo/Code Generation Patterns"

Latest revision as of 10:25, 5 April 2011

Introduction

The code generation of Texo can be controlled in detail using annotations. This document describes some possible code generation patterns which can be implemented using annotations. In addition this document describes some other specific code generation patterns implemented by Texo.

Let a non-generated class be used for an EClass

Say that you already have a class which implements an EClass, the java class has getters and setters for the EStructuralFeatures of the EClass. Texo makes it possible to use this custom java class in place of the generated class. So Texo won't generate an entity class but will instead use the custom java class. This means that references to the EClass are generated as references to the custom java class.

For example say you have a model with two EClasses: Car and Owner and there is an EReference Car.owner which references the Owner EClass. Then if the Owner is represented by a custom java class: CustomOwner, Texo will make sure that the getter, setter and java member for Car.owner refers to the CustomOwner class.

To tell Texo to use the custom java class for an EClass, the following has to be done:

• specify a Model Gen Annotation on the EClass, see here for information on how to this.
• set the 'Generate Code' property to false, this makes sure that Texo won't generate an entity class for this EClass
• set the 'Qualified Class Name' property to the fully qualified of the custom java class

Handling Feature Maps

EMF uses feature maps for flexible structures present in XML Schema (for example the xsd:choice). For more information on EMF feature maps see the following links:

• EMF FeatureMap
• Binding XML to Java

Texo fully supports the EMF feature map by generating a separate class for a feature map element. The feature map itself then becomes a List which contains the generated feature map entry class.

See this example model, the Library EClass has a feature map people. The people feature is a list of three different types: Writers, Employees, Borrowers. Java can't support a List/Set of different types (other than the very type-unsafe and unexpressive List<Object>). Texo solves this differently it creates a separate class for the element in the feature map list, in this example a LibraryPeopleFeatureGroup class is generated. This class has several utility methods and methods to set/get a writer, borrower or employees.

The advantage of creating a separate class to represent the feature map element is that it fairly straight forward to map this class to a database using an ORM or to other external tools while still maintaining an expressive api.

Generation of a safe bi-directional association API (or not)

Texo supports automatic handling of bi-directional associations by setting the other side of a bi-directional association when one side is set. For many ereferences the generated api changes if this option is set (see below). Bi-directional association support is enabled by default. To control it there are two properties in the epackage model gen annotation and on the ereference model gen annotation:

• Generate save many access
• Generate bi-directional association support

For more information see the wiki document on the EPackage Model Gen annotation.

Texo can generate two types of api's for many EReferences (EReferences which can hold multiple values):

• a normal getter/setter:

public void setBooks(List<Book> newBooks);
public List<Book> getBooks();

• an extended api for safe access and bi-directional association support:

public void setBooks(List<Book> newBooks);
public List<Book> getBooks(); // returns an unmodifiable list
public void addToBooks(Book book);
public void removeFromBooks(Book book);

The first api is simple to use but in case of a bi-directional association a programmer has to explicitly set both sides of the association.

The second api is a bit more complex but Texo internally takes care of handling bi-directional associations. So the developer only needs to set one side of the association, Texo automatically sets the other side.

To tell Texo which type of api to create there is the 'Generate save many access' property on the EPackage Model Gen annotation. Set it to true to generate the more extensive (but safer) api, or to false to get the more simple api.

Use List or Set for an isMany EStructuralFeature

Texo makes it possible to choose between java.util.List or java.util.Set when generating code for an isMany EStructuralFeature. Texo uses two control parameters:

• if there is a Model Gen annotation on the EStructuralFeature and its property useList is set, then that is used to choose between List or Set
• the ordered feature of the EStructuralFeature is checked, if ordered==false then a Set is used, otherwise java.util.List is used.

Only Generate Entities - No EMF dependencies

As a default Texo will generate 2 classes: ModelPackage and ModelFactory, which have dependencies on EMF. These two classes are needed for the following runtime functionality:

• Runtime model access
• XML/XMI conversion
• Convert from/to EMF

If this functionality is not important for your specific case and you want to prevent any compile time dependency on EMF you can direct Texo to not generate the 2 Model* classes. Do this by setting the 'Add model runtime behavior' property of the EPackage Model Gen annotation to false.

To use Texo with EMF dependencies in a standalone Java application, see:

• Texo/Download and Install#Using Texo at runtime outside of Eclipse/OSGI
• EMF/FAQ#I want to use EMF, SDO, or XSD in my standalone project, or include only a working subset of the code. What libraries (jar files) do I need in my CLASSPATH?
• EMF/FAQ#How do I use EMF in standalone applications (such as an ordinary main)?

Generate EMF dependencies in a separate package

Texo's model code generation generates two types of classes:

• Java entity classes for EClasses and EEnums
• Model related classes, the ModelFactory and ModelPackage classes

As a default both types are placed in the same java package. If you don't want this, so you want to have a clean java package without any EMF dependencies then you can tell Texo to generate the Model* classes in a separate java package. You can do this by setting the 'Model Classes Package Path' of the EPackage Model Gen annotation to a different java package than the one used/generated by Texo.