Author: fdesbois Date: 2009-11-05 11:34:15 +0100 (Thu, 05 Nov 2009) New Revision: 693 Added: branches/eugene-2.0/eugene/doc/3-v2.0/sources/DiagClasses_Generators.png Modified: branches/eugene-2.0/eugene/doc/3-v2.0/eugene2.0.pdf branches/eugene-2.0/eugene/doc/3-v2.0/sources/eugene2.0 Log: complete doc for eugene 2.0 Modified: branches/eugene-2.0/eugene/doc/3-v2.0/eugene2.0.pdf =================================================================== (Binary files differ) Added: branches/eugene-2.0/eugene/doc/3-v2.0/sources/DiagClasses_Generators.png =================================================================== (Binary files differ) Property changes on: branches/eugene-2.0/eugene/doc/3-v2.0/sources/DiagClasses_Generators.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: branches/eugene-2.0/eugene/doc/3-v2.0/sources/eugene2.0 =================================================================== --- branches/eugene-2.0/eugene/doc/3-v2.0/sources/eugene2.0 2009-11-04 17:41:32 UTC (rev 692) +++ branches/eugene-2.0/eugene/doc/3-v2.0/sources/eugene2.0 2009-11-05 10:34:15 UTC (rev 693) @@ -7,6 +7,15 @@ .. contents:: Contenu +Avant-propos +------------ + +Ce document regroupe les nouvelles évolutions apportés à EUGene pour sa version 2.0. Certaines évolutions pourront potentiellement changés lors de leurs développements. Suivre la `RoadMap`_ . Le développement est en cours sur la branche `eugene-2.0`_ . + +.. _eugene-2.0: http://nuiton.org/repositories/browse/eugene/branches/eugene-2.0 + +.. _RoadMap: http://nuiton.org/versions/show/38 + Contexte de départ ------------------ @@ -22,7 +31,7 @@ ----------------------------- - La config du plugin maven ne doit quasimment pas changer : Les transformations seront considérés comme des templates de générations -- L'ObjectModel ne doit pas prendre en compte des spécificités Java (pas d'importsManager, pas d'attributs "synchronized", ...), le comportement doit rester identique. +- L'ObjectModel ne doit pas prendre en compte des spécificités Java (pas d'importsManager, pas d'attributs "synchronized", ...), le comportement doit rester identique (et indépendant du langage). - Les templates de génération existantes doivent fonctionner toujours de la même manière : même résultat à la génération @@ -77,7 +86,7 @@ 2 - `Evol #114`_ : Ajout d'extensions à l'ObjectModel -3 - `Evol #115`_ : Remplissage de l'ObjectModel directement a partir du code pour génération Java : JavaBuilder +3 - `Evol #115`_ : Remplissage de l'ObjectModel directement a partir du code : Builder 4 - `Evol #113`_ : Possibilité de faire du Model To Model : Transformer @@ -102,16 +111,22 @@ Besoin/Contexte ~~~~~~~~~~~~~~~ +Les types de fichier en entrée du processus de génération sont limités : .xmi, .objectmodel, .statemodel, .zargo ou .uml sont les différentes possibilités. Il serait intéressant de pouvoir modifier le point d'entrée pour pouvoir par exemple gérer un autre type de fichier (un autre fichier xml que du objectmodel par exemple). De plus cela permettra de simplifier les goal maven en créant des Reader en entrée pour chaque type de fichier supporté (zargo, xmi, uml, ...). + Mise en place ~~~~~~~~~~~~~ -Conversion existant -~~~~~~~~~~~~~~~~~~~ +Extraction de la lecture des fichiers d'entrée depuis les Generator. Un Reader est créé pour prendre en entrée une liste de fichiers et obtenir en sortie un Model qui sera par la suite interprété par un Generator. Un Reader par type de model supporté dans EUGene sera créé : ObjectModelReader et StateModelReader. Extension ~~~~~~~~~ +Il est possible d'étendre un Reader pour pouvoir gérer soit un autre format d'entrée de fichiers, soit un autre modèle de sortie (ou potentiellement les deux). +- extension d'ObjectModelReader pour gérer d'autres fichiers d'entrée (xmi, zargo, uml, ...) +- extension du Reader<M extends Model> pour gérer un autre modèle de sortie. + + Evolution #114 : Extensions ObjectModel --------------------------------------- @@ -126,15 +141,14 @@ Mise en place ~~~~~~~~~~~~~ -Une *Map<String, Object> extensions* est ajoutée dans l'ObjectModel racine. Une méthode addExtension est disponible dans ObjectModelImpl pour ajouter une nouvelle extension au modèle. La méthode -getExtension(String reference, Class extensionClass) permettra de récupérer l'extension souhaité (avec son type) et sera disponible dans l'interface ObjectModel. +Une *Map<String, Object> extensions* est ajoutée dans l'ObjectModel racine. La méthode +getExtension(String reference, Class extensionClass) permettra de récupérer l'extension souhaité (avec son type) et sera disponible dans l'interface ObjectModel. Cette méthode créera automatiquement l'extension si elle n'est pas encore définie dans l'ObjectModel. - Cas des ImportsManager ~~~~~~~~~~~~~~~~~~~~~~ Pour les ImportsManager, il est nécessaire d'avoir une Map<String, ImportsManager>, la clé étant le nom complet (full qualified name) d'un classifier, et la valeur l'ImportsManager associé à ce classifier. -Pour simplifier l'utilisation des ImportsManager (et éviter les problèmes de cast sur l'extension), une classe ImportsManagerExtension est créé comprenant la map des managers et des méthodes accesseurs : +Pour simplifier l'utilisation des ImportsManager, une classe ImportsManagerExtension est créé comprenant la map des managers et des méthodes accesseurs : - **ImportsManager getManager(ObjectModelClassifier classifier)** : Permet de récupérer (ou créer s'il n'existe pas) l'ImportsManager lié à un classifier. Méthode utilisée pour les transformations du modèle (ObjectModelTransformer, JavaBuilder) @@ -157,21 +171,22 @@ Il est désormais possible d'utiliser les extensions comme moyen d'enrichir l'ObjectModel lors des transformations et des générations. -Evolution #115 : JavaBuilder ----------------------------- +Evolution #115 : Builder +------------------------ Besoin/Contexte ~~~~~~~~~~~~~~~ -Il est intéressant de pouvoir, dans certains cas, remplir un ObjectModel vide pour générer directement du Java. L'utilisation se fait directement à partir du code d'une autre application qui souhaite utiliser l'ObjectModel pour générer directement du Java. Cependant la version 1.0.1 ne permet pas de faire cela car les interfaces des classes de l'ObjectModel ne comprennent pas de setter. Il est donc -nécessaire de créer une nouvelle classe permettant de remplir un ObjectModel vide tout en ayant une finesse d'interprétation spécifique à Java (gestion des imports, doublon sur les méthodes, ...). -De plus le JavaBuilder servira aux transformations pour de la génération Java. +Il est intéressant de pouvoir, dans certains cas, remplir un ObjectModel vide. L'utilisation se fait directement à partir du code d'une autre application qui souhaite utiliser l'ObjectModel ou à partir d'un Reader pour remplir l'ObjectModel. Cependant la version 1.0.1 ne permet pas de faire cela car les interfaces des classes de l'ObjectModel ne comprennent pas de setter. Il est donc nécessaire de créer une nouvelle classe permettant de remplir un ObjectModel vide avec potentiellement une finesse d'interprétation spécifique à Java (gestion des imports, doublon sur les méthodes, ...). Mise en place ~~~~~~~~~~~~~ -Création d'une classe JavaBuilder qui initialise à l'instanciation un ObjectModel vide (A noter que le nom du modèle est indispensable à la génération). Le JavaBuilder propose un panel de méthodes permettant : +Création d'une classe ObjectModelBuilder qui initialise à l'instanciation un ObjectModel vide (A noter que le nom du modèle est indispensable à la génération). Ce builder permet de remplir complètement l'ObjectModel (stéréotypes, multiplicités, ...) + +Création d'une classe JavaBuilder qui initialise à l'instanciation un ObjectModel vide. Le JavaBuilder propose un panel de méthodes permettant : + - Ajout de classes/interfaces au modèle - Ajout d'une superclass - Ajout d'interface à une classe @@ -190,57 +205,118 @@ Besoin/Contexte ~~~~~~~~~~~~~~~ -L'écriture des templates de génération actuelles (v1.0.1) peuvent être fastidieuses et difficiles à maintenir. Il est donc préférable d'utiliser une tranformation du modèle ObjectModel source (provenant d'un diagramme UML) en un ObjectModel représentant basiquement le Java qui sera généré. +Dans le cas d'une génération java, l'écriture des templates de génération actuelles (v1.0.1) peut être fastidieuse et difficile à maintenir. Il est donc préférable d'utiliser une tranformation du modèle ObjectModel source (provenant d'un diagramme UML) en un ObjectModel représentant basiquement le Java qui sera généré. Ce qui implique pour ce cas, la suppression des éléments spécifiques à UML (mutliplicités, stéréotypes, ...) pour un ObjectModel épuré spécifique à une génération Java. Mise en place ~~~~~~~~~~~~~ -Un Transformer est considéré comme un Generator pour être intégré plus facilement dans le processus de génération (templates). Cependant il possède un modèle en entrée et un en sortie, donc pas de sortie fichiers. Pour ce faire, il est obligatoirement associé à un Generator. Ainsi un Transformer prendra en entrée un modèle, le transformera en un nouveau (potentiellement de type différent) et utilisera le generator de sortie pour générer ce nouveau modèle. Il est donc nécessaire d'instancier un Transformer en lui fournissant son Generator de sortie. Le modèle de sortie doit donc être obligatoirement compatible avec ce Generator de sortie. +Un Transformer est considéré comme un *Generator* pour être intégré plus facilement dans le processus de génération (templates). Cependant il possède un modèle en entrée et un en sortie, donc **aucune sortie fichiers**. Pour ce faire, il est obligatoirement associé à un *Generator*. Ainsi un *Transformer* prendra en entrée un modèle, le transformera en un nouveau (potentiellement de type différent) et utilisera le generator de sortie pour générer ce nouveau modèle. Il est donc nécessaire d'instancier un *Transformer* en lui fournissant son *Generator* de sortie compatible avec le modèle de sortie. Conversion existant ~~~~~~~~~~~~~~~~~~~ +Pour une génération Java, il est nécessaire d'étendre l'ObjectModelTransformerToJava qui utilise un JavaBuilder pour la construction d'un ObjectModel spécifique à Java. + +Ex : BeanGenerator permet la génération de bean (stéréotype <<bean>>) en leurs ajoutants les getter/setter adéquat et des listeners. Cette template de génération existe dans ToPIA. Elle sera remplacée par un BeanTransformer qui étend ObjectModelTransformerToJava. Au lieu d'écrire la template du fichier généré, le transformer remplira un nouveau modèle avec les classes, opérations, attributs à générer. + +Note + Les noms complets des éléments ajoutés au modèle devront être impérativement utilisés pour la gestion des imports. + (ex : java.io.Serializable, org.chorem.bonzoms.Role, java.util.List<java.lang.String>, ...) + Extension ~~~~~~~~~ +Les Transformer sont étendables pour transformer un modèle en un autre comme on le souhaite. Plusieurs transformer sont disponibles dans EUGene : +- abstract Transformer<Input extends Model, Output extends Model> +- abstract ObjectModelTransformer<Output extends Model> extends Transformer<ObjectModel, Output> +- abstract ObjectModelTransformerToJava extends ObjectModelTransformer<ObjectModel> + +Il est nécessaire d'étendre l'un de ces Transformer pour créer une transformation spécifique à son modèle métier. + Evolution #116 : Generator -------------------------- Besoin/Contexte ~~~~~~~~~~~~~~~ +Des modifications sont nécessaires sur les Generator racines (abstraits) pour permettre les autres évolutions. Les générateurs de la version 1.0.1, ne permettent pas la modification du modèle d'entrée. De plus les générateurs sont spécifiques à un type de fichier d'entrée (.objectmodel pour ObjectModelGenerator, .statemodel pour StateModelGenerator). + Mise en place ~~~~~~~~~~~~~ +Extraction de la lecture en entrée des générateurs. Les générateurs ne prennent désormais qu'un modèle en entrée (qui peut potentiellement provenir de plusieurs fichiers sources à la charge du Reader). Le type du modèle est également connu à l'instanciation : *ObjectModelGenerator extends AbstractGenerator<ObjectModel>*. Un générateur est donc obligatoirement associé à un Model d'entrée. Voir diagramme en annexe pour plus de précision sur les modifications d'héritage. + Extension ~~~~~~~~~ +Un Generator est associé à un modèle. La création d'un nouveau modèle implique la création d'un Generator abstrait associé. +- super parent : Generator<M extends Model> +- classe abstraite commune aux templates actuelles : AbstractGenerator<M extends Model> extends Generator<M> +- cas du ObjectModel en entrée : ObjectModelGenerator extends AbstractGenerator<ObjectModel> +- idem pour un autre modèle MonModel : MonModelGenerator extends AbstractGenerator<MonModel> + + Evolution #117 : JavaGenerator ------------------------------ Besoin/Contexte ~~~~~~~~~~~~~~~ +Les templates de génération (Generator) doivent être écrites pour générer des fichiers. Il est possible grâce à l'ajout de Transformer de pouvoir désormais remplir un modèle spécifique au langage Java (utilisation d'ObjectModel). Cependant il n'existe aucune template de base permettant d'interpréter un ObjectModel simplement sans prise en compte de spécificités du au métier de l'application (entités, daos, ...) qui seront interprétés dans les Transformer. + Mise en place ~~~~~~~~~~~~~ +Création d'une template JavaGenerator toute simple qui parcourt l'ObjectModel, génère les classes, méthodes interfaces sans prise en compte des spécificités UML (stéréotypes, multiplicités, ...). +Note + JavaGenerator extends ObjectModelGenerator + + Evolution #107 : ObjectModelModifier ------------------------------------ Besoin/Contexte ~~~~~~~~~~~~~~~ +En java, les modifier concernent certains paramètres pouvant être mis sur les attributs, méthodes comme "static", "abstract", "public", ... Dans l'ObjectModel de la version 1.0.1, ces modifier sont représentés par des attributs ce qui implique un attribut par modifier : static, visibility, ... Pour simplifier la génération et la manipulation de ces modifiers, il serait intéressant d'avoir simplement une liste d'ObjectModelModifier. De plus cela permettra d'ajouter plus facilement certains modifier comme "synchronized". Cela permettra également de simplifier l'écriture de certaines méthodes des builder :: + + public ObjectModelOperation addOperation(String operationName, String returnType, + ObjectModelModifier... modifiers) { + ... + } + +exemple :: + + ObjectModelOperation setter = addOperation("setName", "void", ObjectModelModifier.PUBLIC); + // correspond a : public void setName(...) + + +Contraintes +~~~~~~~~~~~ + +- Les méthodes isStatic, isAbstract, etc... seront maintenus pour connaitre précisemment les modifier associés à la classe, méthode, attribut ou autre. +- Les nouveaux modifiers auront un nom générique indépendant du langage. + Mise en place ~~~~~~~~~~~~~ +Création d'une enumération ObjectModelModifier comprenant les différents modifiers existants (STATIC, ABSTRACT, PUBLIC, PRIVATE, ...). Il sera possible de récupérer la valeur chaîné (String) de chaque ObjectModelModifier possible. + Conversion existant ~~~~~~~~~~~~~~~~~~~ -Extension -~~~~~~~~~ +Les attributs correspondant aux modifiers seront supprimés pour mettre en place une List<ObjectModelModifier> sur les objets qui le nécessitent (classifier, classe, interface, attribute, operation, ...). +Annexe : Hiérarchie des Generator/Transformer +--------------------------------------------- +.. figure:: DiagClasses_Generators.png + + Hiérarchie des Generator/Transformer + + +