Author: jcouteau Date: 2010-01-28 12:40:21 +0100 (Thu, 28 Jan 2010) New Revision: 807 Added: trunk/maven-eugene-plugin/src/site/fr/rst/example.rst trunk/maven-eugene-plugin/src/site/rst/example.rst Modified: trunk/maven-eugene-plugin/src/site/fr/rst/usage.rst trunk/maven-eugene-plugin/src/site/rst/usage.rst trunk/maven-eugene-plugin/src/site/site_en.xml trunk/maven-eugene-plugin/src/site/site_fr.xml Log: Translate usage doc from english to french Add an examples page with a simple and a complex configuration Added: trunk/maven-eugene-plugin/src/site/fr/rst/example.rst =================================================================== --- trunk/maven-eugene-plugin/src/site/fr/rst/example.rst (rev 0) +++ trunk/maven-eugene-plugin/src/site/fr/rst/example.rst 2010-01-28 11:40:21 UTC (rev 807) @@ -0,0 +1,143 @@ +Examples +======== + + +:Authors: Jean Couteau +:Contact: couteau@codelutin.com +:Revision: $Revision: 649 $ +:Date: $Date: 2009-10-21 14:21:03 +0200 (Wed, 21 Oct 2009) $ + + +.. contents:: + +Cette page regroupe deux examples de configuration/utilisation du plugin +dans un pom. Le premier example est très simple, le second est plus complexe +et est censé ammener une complète compréhension du plugin combiné à la +documentation des usages_ . + +.. _usages: usage.html + +Example simple +-------------- + +Cet example va générer les entitées du package org.nuiton.eugene.demopackage à +partir des fichiers zargo présents dans le répertoire src/main/xmi. + +:: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>maven-eugene-plugin</artifactId> + + <executions> + + <execution> + <phase>generate-sources</phase> + <!-- By default, generation from ObjectModel --> + <configuration> + <!-- Corresponding to extracted package from zargo file --> + <fullPackagePath>org.nuiton.eugene.demopackage</fullPackagePath> + <!-- DefaultPackage used for DAOHelper generation --> + <defaultPackage>org.nuiton.eugene.demopackage</defaultPackage> + <!-- Use topia templates --> + <templates> + org.nuiton.topia.generator.TopiaMetaTransformer, + org.nuiton.topia.generator.InterfaceTransformer, + org.nuiton.topia.generator.BeanTransformer + </templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + </executions> + <-- dependency to topia to use their template --> + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + </dependency> + </dependencies> + </plugin> + +Example complexe +---------------- + +Cet example utilise deux fichiers zargo en entrée et va les générer différemment. + +Les deux premières phases sont communes, ensuite on distingues deux executions, +une par fichier spécifiant les différents templates à utiliser pour chaque +fichier model. + +:: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>maven-eugene-plugin</artifactId> + <configuration> + <defaultPackage>org.nuiton.eugene.demopackage</defaultPackage> + <fullPackagePath>org.nuiton.eugene.demopackage</fullPackagePath> + </configuration> + + <executions> + + <!-- Execution that transforms zargo files to objectmodel by using + the full run without the model phase --> + <execution> + <phase>generate-sources</phase> + <id>toModel</id> + <configuration> + <inputs>zargo</inputs> + <resolver>org.nuiton.util.FasterCachedResourceResolver</resolver> + <skipInputs>model</skipInputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + <-- Execution that transforms the entities.objectmodel file using + specific templates from topia --> + <execution> + <phase>generate-sources</phase> + <id>model-to-entities</id> + <configuration> + <inputs>model:target/generated-sources/models:entities.objectmodel</inputs> + <templates> + org.nuiton.topia.generator.TopiaMetaTransformer, + org.nuiton.topia.generator.InterfaceTransformer + </templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + <-- Execution that transforms the beans.objectmodel file using + other specific templates from topia --> + <execution> + <phase>generate-sources</phase> + <id>model-to-bean</id> + <configuration> + <inputs> + <input>model:target/generated-sources/models:beans.objectmodel</input> + </inputs> + <templates>org.nuiton.topia.generator.BeanTransformer</templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + </executions> + + <!-- dependency to use topia templates --> + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>${topia.version}</version> + <scope>compile</scope> + </dependency> + </dependencies> + </plugin> \ No newline at end of file Modified: trunk/maven-eugene-plugin/src/site/fr/rst/usage.rst =================================================================== --- trunk/maven-eugene-plugin/src/site/fr/rst/usage.rst 2010-01-26 21:06:43 UTC (rev 806) +++ trunk/maven-eugene-plugin/src/site/fr/rst/usage.rst 2010-01-28 11:40:21 UTC (rev 807) @@ -14,4 +14,313 @@ smart-generate -------------- -*TODO translate me in french from the english version* +Ce 'goal' permet de lancer une génération intelligente, en chaînant les +différentes phases de génération. + +En suivant les conventions de maven (et la configuration par défaut), il est +conseillé de respecter au maximum les cnventions de plugin afin d'éviter de gros +mals de crâne... + +modelType +********* + +Propriété invariante du 'goal', *modelType* est le type de modèle à traiter. + +Il y a actuellement deux types de modèles : + +- objectmmodel +- statemodel + +inputs +****** + +Pour définir ce qu'il faut générer, vous devez remplir la configuration des +*inputs*. + +Chaque entrée des 'inputs' est associée à une phase de génération (référez-vous +à la section suivante pour en savoir plus sur les phases). + +Une entrée des 'inputs' est définie par : + +- une phase (zargo, xmi ou model) +- un répertoire contenant les fichiers à inclure +- un 'pattern' d'inclusion + +Example: + +:: + + <execution> + <configuration> + <inputs>zargo</inputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + +Si vous souhaitez utiliser plusieurs entrées, vous pouvez aussi écrire : + +:: + + <execution> + <configuration> + <inputs> + <input>zargo</input> + <input>xmi</input> + </inputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + +Une entrée peut avoir trois formes : + +- <input>XXX</input> : utilise la phase XXX avec sa configuration par défaut. +- <input>dir:includes</input> : utilise le répertoire donné et utilise le 'pattern' d'exclusion pour définir la phase à utiliser. +- <input>XXX:dir:includes</input> : utilise la phase XXX avec le répertoire et le 'pattern d'inclusion' donnés. + +Example: + +:: + + <execution> + <configuration> + <inputs>zargo</inputs> + <inputs>src/main/myzargo:**/*.zargo</inputs> + <inputs>zargo:src/main/myzargo2:**/*.zargo2</inputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + +phases +****** + +Une phase (aussi appellée un 'writer' a pour but de générer quelque chose avec +la possibilité de déclencher la phase chaînée *suivante*. + +Pour le moment, nous avons défini quelques phases de génération : + +- zargo +- xmi +- model + +Chaque phase a un protocole d'entrée et un protocole de sortie : + +:: + + zargo --> xmi + xmi --> model + model --> no output protocol (at the moment) + +Donc si vous donnez la phase zargo, le plugin essaiera de chaîner zargo --> xmi --> model. + +Il est possible de ne pas effectuer une phase en utilisant la propriété *skipInputs*. + +Example: + +:: + + <execution> + <configuration> + <inputs>zargo</inputs> + <skipInputs>model</skipInputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + +lancera les phases zargo et xmi mais pas la phase model. + +Il y a aussi quelques propriété spécifiques à chaque phase. + +Phase zargo +~~~~~~~~~~~ + +This phase permits to take some zargo files to extract form them the xmi files. + +Example: + +:: + + <execution> + <configuration> + <inputs>zargo</inputs> + <skipInputs>xmi,model</skipInputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + +détectera tous les fichiers zargo (en utilisant la configuration par défaut de +la phase zargo) et extraira les fichiers xmi. + +La configuration par défaut de la phase zargo est : + +- répertoire source : src/main/xmi +- 'pattern' d'inclusion : **/*.zargo +- répertoire de sortie : target/generated-sources/xmi + +Cette phase n'a pas de configuration spécifique. + +Phase xmi +~~~~~~~~~ + +Cette phase permet de prendre des fichiers xmi pour construire des fichiers +objectmodel (ou statemodel). + +Example: + +:: + + <execution> + <configuration> + <inputs>xmi</inputs> + <resolver>org.nuiton.util.FasterCachedResourceResolver</resolver> + <skipInputs>model</skipInputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + +détectera tous les fichiers xmi (en utilisant la configuration par défaut de la +phase xmi) et créera des fichiers model. + +La configuration pour la phase xmi est : + +- répertoire source : src/main/xmi +- 'pattern' d'inclusion : **/*.xmi +- répertoire de sortie : target/generated-sources/modles + +Cette phase défini quelques propriétés spécifiques : + +- *fullPackagePath* : le package généré. +- *resolver* : le resolver de ressource à utiliser. + +Phase model +~~~~~~~~~~~ + +Cette phase permet de prendre des fichiers model pour générer des fichiers (java +ou autre) en utilisant des templates. + +Example: + +:: + + <execution> + <configuration> + <inputs>model:target/generated-sources/models:observe.objectmodel</inputs> + <templates> + org.nuiton.topia.generator.TopiaMetaTransformer, + org.nuiton.topia.generator.InterfaceTransformer + </templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + +La configuration par défaut pour la phase model est : + +- répertoire source : src/main/models +- 'pattern' d'inclusion : **/*.objectmodel +- répertoire de sortie : target/generated-sources/java + +Cette phase défini des propriétés spécifiques : + +- *defaultPackage* : package par défaut +- *templates* : templates à utiliser +- *excludeTemplates* : templates à exclure +- *generatedPackages* : packages à générer + +available-data +-------------- + +Ce 'goal' aide les utilisateurs à déterminer quel type de donnée peut-être +utilisé avec la configuration actuelle du plugin. + +Ce 'goal' ne peut être utilisé que par invocation directe en console et non dans +votre pom car son objectif est d'afficher des informations dans la console. + +Lancez seulement + +::xmi + + mvn eugene:available-data + +pour obtenir toutes les informations disponibles. + +Example: + +:: + + [INFO] [eugene:available-data {execution: default-cli}] + [INFO] Get datas for data types : [modeltype, writer, modelreader, modeltemplate] + Found 2 modeltypes : + [statemodel] with implementation 'org.nuiton.eugene.models.state.xml.StateModelImpl' + [objectmodel] with implementation 'org.nuiton.eugene.models.object.xml.ObjectModelImpl' + Found 3 writers : + [xmi] with implementation 'org.nuiton.eugene.plugin.writer.XmiChainedFileWriter + inputProtocol : xmi + outputProtocol : model + defaultIncludes : **/*.xmi + defaultInputDirectory : src/main/xmi + defaultTestInputDirectory : src/test/xmi' + [model2Java] with implementation 'org.nuiton.eugene.plugin.writer.ModelChainedFileWriter + inputProtocol : model + outputProtocol : null + defaultIncludes : **/*.*model + defaultInputDirectory : src/main/models + defaultTestInputDirectory : src/test/models' + [zargo2xmi] with implementation 'org.nuiton.eugene.plugin.writer.ZargoChainedFileWriter + inputProtocol : zargo + outputProtocol : xmi + defaultIncludes : **/*.zargo + defaultInputDirectory : src/main/xmi + defaultTestInputDirectory : src/test/xmi' + Found 2 modelreaders : + [statemodel] with implementation 'org.nuiton.eugene.models.state.StateModelReader' + [objectmodel] with implementation 'org.nuiton.eugene.models.object.ObjectModelReader' + Found one modeltemplate : + [org.nuiton.eugene.java.JavaGenerator] with implementation 'org.nuiton.eugene.java.JavaGenerator' + +copyVersionFiles +---------------- + +Ce 'goal' permet de garder les mappings hibernate intacts pour chaque version du +model. + +zargo2xmi +--------- + +Génération 'stupide' de zargo vers xmi sans chaînage des générations. + +Utilisez plutôt le 'goal' *smart-generate*. + +xmi2objectmodel +--------------- + +Génération 'stupide' de xmi vers objectmodel sans chaînage des générations. + +Utilisez plutôt le 'goal' *smart-generate*. + +xmi2statemodel +-------------- + +Génération 'stupide' de xmi vers statemodel sans chaînage des générations. + +Utilisez plutôt le 'goal' *smart-generate*. + +generate +-------- + +Génération 'stupide' de model vers java et autres sans chaînage des générations. + +Utilisez plutôt le 'goal' *smart-generate*. Added: trunk/maven-eugene-plugin/src/site/rst/example.rst =================================================================== --- trunk/maven-eugene-plugin/src/site/rst/example.rst (rev 0) +++ trunk/maven-eugene-plugin/src/site/rst/example.rst 2010-01-28 11:40:21 UTC (rev 807) @@ -0,0 +1,147 @@ +Examples +======== + + +:Authors: Jean Couteau +:Contact: couteau@codelutin.com +:Revision: $Revision: 649 $ +:Date: $Date: 2009-10-21 14:21:03 +0200 (Wed, 21 Oct 2009) $ + + +.. contents:: + +This page groups two plugin configuration/usage examples in a pom. The first +example is very simple, the second is more complex and aimed to bring a better +understanding of the plugin combined with the usages_ documentation. + +Cette page regroupe deux examples de configuration/utilisation du plugin +dans un pom. Le premier example est très simple, le second est plus complexe +et est censé ammener une complète compréhension du plugin combiné à la +documentation des usages_ . + +.. _usages: usage.html + +Simple example +-------------- + +This example will generate the entities and interfaces from the package +org.nuiton.eugene.demopackage from the zargo files present in the src/main/xmi +directory. + +:: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>maven-eugene-plugin</artifactId> + + <executions> + + <execution> + <phase>generate-sources</phase> + <!-- By default, generation from ObjectModel --> + <configuration> + <!-- Corresponding to extracted package from zargo file --> + <fullPackagePath>org.nuiton.eugene.demopackage</fullPackagePath> + <!-- DefaultPackage used for DAOHelper generation --> + <defaultPackage>org.nuiton.eugene.demopackage</defaultPackage> + <!-- Use topia templates --> + <templates> + org.nuiton.topia.generator.TopiaMetaTransformer, + org.nuiton.topia.generator.InterfaceTransformer, + org.nuiton.topia.generator.BeanTransformer + </templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + </executions> + <-- dependency to topia to use their template --> + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + </dependency> + </dependencies> + </plugin> + +Complex example +--------------- + +This example uses two zargo files as input and will generate them separately. + +The two first phases are common, then two executions are configured, one per +file, specificating the different templates to use for each model file. + +:: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>maven-eugene-plugin</artifactId> + <configuration> + <defaultPackage>org.nuiton.eugene.demopackage</defaultPackage> + <fullPackagePath>org.nuiton.eugene.demopackage</fullPackagePath> + </configuration> + + <executions> + + <!-- Execution that transforms zargo files to objectmodel by using + the full run without the model phase --> + <execution> + <phase>generate-sources</phase> + <id>toModel</id> + <configuration> + <inputs>zargo</inputs> + <resolver>org.nuiton.util.FasterCachedResourceResolver</resolver> + <skipInputs>model</skipInputs> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + <-- Execution that transforms the entities.objectmodel file using + specific templates from topia --> + <execution> + <phase>generate-sources</phase> + <id>model-to-entities</id> + <configuration> + <inputs>model:target/generated-sources/models:entities.objectmodel</inputs> + <templates> + org.nuiton.topia.generator.TopiaMetaTransformer, + org.nuiton.topia.generator.InterfaceTransformer + </templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + <-- Execution that transforms the beans.objectmodel file using + other specific templates from topia --> + <execution> + <phase>generate-sources</phase> + <id>model-to-bean</id> + <configuration> + <inputs> + <input>model:target/generated-sources/models:beans.objectmodel</input> + </inputs> + <templates>org.nuiton.topia.generator.BeanTransformer</templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + + </executions> + + <!-- dependency to use topia templates --> + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>${topia.version}</version> + <scope>compile</scope> + </dependency> + </dependencies> + </plugin> \ No newline at end of file Modified: trunk/maven-eugene-plugin/src/site/rst/usage.rst =================================================================== --- trunk/maven-eugene-plugin/src/site/rst/usage.rst 2010-01-26 21:06:43 UTC (rev 806) +++ trunk/maven-eugene-plugin/src/site/rst/usage.rst 2010-01-28 11:40:21 UTC (rev 807) @@ -15,17 +15,19 @@ smart-generate -------------- -This goal permits to launch a smart (understood as intelligent) generation, chaining different generation phases. +This goal permits to launch a smart (understood as intelligent) generation, +chaining different generation phases. -Following the maven spirit of using convention (and then default configuration) you should always try to respect the -plugin convention to avoid big headaches... +Following the maven spirit of using convention (and then default configuration) +you should always try to respect the plugin convention to avoid big headaches... modelType ********* -An invariant of the goal is the type of model to treate given by the configuration property *modelType*. +An invariant of the goal is the type of model to treate given by the +configuration property *modelType*. -actually there is two types of model : +At the moment there is two types of model : - objectmodel - statemodel @@ -35,9 +37,10 @@ To define what to generate, you must fill the *inputs* configuration. -Each inputs entry is bind to a phase of generation (see next section to learn more about phases). +Each inputs entry is bind to a phase of generation (see next section to learn +more about phases). -an input entry is defined by : +An input entry is defined by : - a phase (zargo, xmi or model) - a input directory @@ -56,7 +59,7 @@ </goals> </execution> -If you wants to use more than one entry, you can also write : +If you want to use more than one entry, you can also write : :: @@ -75,7 +78,7 @@ An input can have three forms : -- <input>XXX</input> : use the XXX phase with his default configuration +- <input>XXX</input> : use the XXX phase with its default configuration - <input>dir:includes</input> : use the given directory with the given phase and detects from the includes pattern the phase to use - <input>XXX:dir:includes</input> : use the XXX phase with the given directory and includes pattern @@ -98,7 +101,8 @@ phases ****** -A phase (also called a writer) aims to generate something with possibility to fire a *next* chained phase. +A phase (also called a writer) aims to generate something with possibility to +fire a *next* chained phase. At the moment we have defined several phases of generation : @@ -139,7 +143,7 @@ zargo phase ~~~~~~~~~~~ -This phase permits to take some zargo files to extract form them the xmi files. +This phase permits to take some zargo files to extract the xmi files from them. Example: @@ -155,7 +159,8 @@ </goals> </execution> -will detects all zargo files (using the default configuration for zargo phase) and extract xmi files. +will detect all zargo files (using the default configuration for zargo phase) +and extract their xmi files. The default configuration for the zargo phase is : @@ -168,7 +173,8 @@ xmi phase ~~~~~~~~~ -This phase permits to take some xmi files to build some objectmoldel (or staemodel) files. +This phase permits to take some xmi files to build some objectmoldel (or +statemodel) files. Example: @@ -185,7 +191,8 @@ </goals> </execution> -will detects all xmi files (using the default configuration for xmi phase) and create model files. +will detect all xmi files (using the default configuration for xmi phase) and +create model files from them. The default configuration for the xmi phase is : @@ -201,7 +208,8 @@ model phase ~~~~~~~~~~~ -This phase permits to take some model files to generate some files (java and others) using the given templates +This phase permits to take some model files to generate some files (java and +others) using the given templates. Example: @@ -237,10 +245,11 @@ available-data -------------- -This goals help users to determine all type of data that can be used with your current configuration of plugin. +This goal help users to determine all types of data that can be used with their +current configuration of plugin. -The goal can only be used by direct invocation in console and not in your pom as his purpose is only to display some -stuff in your console. +The goal can only be used by direct invocation in console and not in the pom as +its purpose is only to display some stuff in the console. Just type @@ -248,7 +257,7 @@ mvn eugene:available-data -to obtain all datas available. +to obtain all data available. Example: @@ -287,32 +296,32 @@ copyVersionFiles ---------------- -This goals permits to keep hibernate mappings for each version of model version. +This goal permits to keep hibernate mappings for each version of model version. zargo2xmi --------- 'Stupid' generation from zargo to xmi files with no chained stuff. -Prefer use now the *smart-generate* goal. +Prefer using the *smart-generate* goal. xmi2objectmodel --------------- 'Stupid' generation from xmi files to object model files with no chained stuff. -Prefer use now the *smart-generate* goal. +Prefer using the *smart-generate* goal. xmi2statemodel -------------- 'Stupid' generation from xmi files to state model files with no chained stuff. -Prefer use now the *smart-generate* goal. +Prefer using the *smart-generate* goal. generate -------- 'Stupid' generation from model files to java and other files with no chained stuff. -Prefer use now the *smart-generate* goal. +Prefer using the *smart-generate* goal. Modified: trunk/maven-eugene-plugin/src/site/site_en.xml =================================================================== --- trunk/maven-eugene-plugin/src/site/site_en.xml 2010-01-26 21:06:43 UTC (rev 806) +++ trunk/maven-eugene-plugin/src/site/site_en.xml 2010-01-28 11:40:21 UTC (rev 807) @@ -20,6 +20,7 @@ <menu name="User"> <item href="index.html" name="Index"/> <item href="usage.html" name="Usage"/> + <item href="example.html" name="Examples"/> <item name="Goals" href="plugin-info.html"> <item name="smart-generate" href="smart-generate-mojo.html"/> <item name="available-data" href="available-data-mojo.html"/> Modified: trunk/maven-eugene-plugin/src/site/site_fr.xml =================================================================== --- trunk/maven-eugene-plugin/src/site/site_fr.xml 2010-01-26 21:06:43 UTC (rev 806) +++ trunk/maven-eugene-plugin/src/site/site_fr.xml 2010-01-28 11:40:21 UTC (rev 807) @@ -24,6 +24,7 @@ <menu name="Utilisateur"> <item href="index.html" name="Accueil"/> <item href="usage.html" name="Utilisation"/> + <item href="example.html" name="Examples"/> <item name="Goals" href="plugin-info.html"> <item name="smart-generate" href="smart-generate-mojo.html"/> <item name="available-data" href="available-data-mojo.html"/>