Author: athimel Date: 2014-05-15 18:25:44 +0200 (Thu, 15 May 2014) New Revision: 3108 Url: http://forge.nuiton.org/projects/topia/repository/revisions/3108 Log: Start refactoring maven-site Added: trunk/src/site/resources/library.png trunk/src/site/resources/library.zargo trunk/src/site/resources/lutinorange-codelutin.png trunk/src/site/resources/site.css trunk/src/site/resources/topia_224_75.png trunk/src/site/resources/topia_60_20.png trunk/src/site/rst/docs/ trunk/src/site/rst/docs/devel.rst trunk/src/site/rst/docs/event.rst trunk/src/site/rst/docs/hibernate_mapping.rst trunk/src/site/rst/docs/isolation.rst trunk/src/site/rst/docs/project.rst trunk/src/site/rst/docs/schema_migration.rst trunk/src/site/rst/docs/security.rst trunk/src/site/rst/docs/todo.rst trunk/src/site/rst/docs/y_cycle.rst trunk/src/site/rst/tutos/ trunk/src/site/rst/tutos/from_scratch.rst.vm trunk/src/site/rst/tutos/migrate_to_3.0.rst trunk/src/site/rst/user/faq.rst trunk/src/site/rst/user/model_generation.rst.vm Removed: trunk/src/site/rst/devel/ trunk/src/site/rst/migrate_to_3.0.rst trunk/src/site/rst/user/FAQ.rst trunk/src/site/rst/user/ModelGeneration.rst.vm trunk/src/site/rst/user/start.rst.vm Modified: trunk/src/site/rst/index.rst trunk/src/site/site_fr.xml trunk/topia-service-csv/pom.xml Added: trunk/src/site/resources/library.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/library.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/library.zargo =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/library.zargo ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/lutinorange-codelutin.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/lutinorange-codelutin.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/site.css =================================================================== --- trunk/src/site/resources/site.css (rev 0) +++ trunk/src/site/resources/site.css 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,4 @@ + +blockquote { + border-left: 0px; +} \ No newline at end of file Added: trunk/src/site/resources/topia_224_75.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/topia_224_75.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/topia_60_20.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/topia_60_20.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Copied: trunk/src/site/rst/docs/devel.rst (from rev 3106, trunk/src/site/rst/devel/Devel.rst) =================================================================== --- trunk/src/site/rst/docs/devel.rst (rev 0) +++ trunk/src/site/rst/docs/devel.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,171 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +=================== +TopiaContextFactory +=================== + +Le topia context est créé en faisant la demande sur le *TopiaContextFactory*. +On peut passer en paramètre au *TopiaContextFactory* un object *Property* qui +permet de configurer le context. Si aucun fichier est passé en paramètre, un fichier de +propriété **TopiaContextImpl.properties** est recherché dans le classpath. + +Fichier de configuration +======================== + +Le fichier de configuration est un fichier lisible par un objet *Property*. +Il contient différentes informations : +- liste des entités à gérer +- option de connexion à la base de données +- les services à activer + +Liste des entités à gérer +------------------------- + +Il est possible de définir les entités soit directement en indiquant un +répertoire contenant les mappings hibernate:: + + topia.persistence.directories=<path> + +soit en indiquant une liste de classe séparé par des virgule:: + + topia.persistence.classes=<list de classe> + +Le mieux est d'utiliser la liste de classe qui est non spécifique à une +persistence ou à une plateforme. + +Option de connexion à la base de données +---------------------------------------- + +Hibernate +~~~~~~~~~ + +Les options pour hibernate peuvent être directement dans le fichier de configuration principal ou dans un fichier de configuration secondaire. Dans ce cas il faut indiquer dans le fichier de configuration principal le chemin de ce fichier:: + + topia.persistence.properties.file=<filesystem or classpath path> + +Les options hibernates sont les options hibernate classique : + +- hibernate.connection.username +- hibernate.connection.password +- hibernate.dialect +- hibernate.connection.driver_class +- hibernate.connection.url + +Les services à activer +---------------------- + +Il est possible d'indiquer les services à activer grâce aux options:: + + topia.service.<service name>=<class> + topia.service.security=org.nuiton.topia.security.TopiaSecurityServiceImpl + topia.service.index=org.nuiton.topia.index.LuceneIndexer + topia.service.history=org.nuiton.topia.history.TopiaHistoryServiceImpl + +<service name> doit correspondre au nom de service que <class> retourne, sinon il est désactivé. + +Les services disponibles actuellement sont: + +- Service d'indexation full text +- Service d'historisation des modifications des entités +- Service de sécurité +- Service d'upgrade automatique des données hibernates + +TopiaContext +============ + +Le *TopiaContext* permet de récupérer les services, d'ouvrir des transactions +en récupérant des nouveaux *TopiaContext* fils, de s'enregistrer en tant que +listener pour recevoir les notifications de modification sur les entités. + +Sur les *TopiaContext* fils, on peut récupérer des DAO qui permettent de +créer, modifier, rechercher les entités. + +Entité +====== + +Normalement **Topia** est fait pour pouvoir générer n'importe quel type de POJO +et les rendre persistants. Mais il est plus simple d'utiliser la génération +de code fournit avec **Topia** pour générer les entités à partir d'un +diagramme UML. Dans ce cas toutes les entités héritent de *TopiaEntity* qui +contient des méthodes pour s'enregistrer sur les modifications des attributs +ou pouvoir lever un droit de veto sur une modification. Sont aussi +disponible les méthodes: + +- getTopiaId +- getTopiaVersion +- getTopiaCreationDate +- getTopiaContext +- getComposite: Retourne tous les objets qui seront effacé si cet objet est effacé +- getAggregate: Retourne les objets en lien avec celui-ci + +Lorsque l'on utilise la génération on peut implanter une classe qui hérite +du *Abstract* généré et qui se finisse par Impl. Par exemple si dans notre +modèle nous avons la classe *Toto* il sera généré une interface *Toto* et +une classe abstraite *TotoAbstract*, il faudra alors implanter *TotoImpl*:: + + extends TotoAbstract extends TopiaEntityAbstract implements Toto + extends TopiaEntityAbstract implements *TopiaEntity + +Cette classe impl permet d'ajouter des méthodes métiers à l'entité ou des +méthode d'accès différent sur les attributs. + +DAO +=== + +Il n'y a plus qu'un seul type de persistence possible pour les DAO, à savoir Hibernate (depuis la 2.2.0). Il est possible d'étendre un DAO +pour lui ajouter différentes méthodes plus complexes ou plus spécifiques que celles proposées par défaut : + +- findAll +- findAllByProperties(Map<String, Object> properties) +- findAllByProperties(String param, Object property, ...) +- findByProperty(String property) +- tous les find pour chaque property existante de l'entité +- ... + +Pour spécifier d'autres méthodes, il suffit d'utiliser directement le modèle UML qui sert à la génération des entités. +Un stéréotype <<dao>> doit être précisé sur une méthode d'entité pour indiquer qu'elle doit se situer dans un DAO. +Le fichier *DAOImpl* associé ne sera plus généré et devra être créé par le développeur en héritant du *DAOAbstract*. +(voir FAQ pour un exemple sur l'extension d'un DAO). + +Note sur les signatures de méthodes + Par commodité, les méthodes retournant une liste d'entités commencent par findAllBy tandis que celles retournant une seule entité + commencent par findBy. + +TopiaService +============ + +Pour implanter un TopiaService il faut absolument créer une interface qui +hériter de l'interface *TopiaService* et mettre dans cette interface un +attribut static qui définit le nom du service:: + + public static final String SERVICE_NAME = "monservice"; + +Un service peut avoir besoin de nouvelles entités pour fonctionner. Pour cela +il faut retourner la liste des entités grâce à la méthode +**getPersistenceClasses**. + +Après instanciation du service par le **TopiaContext** celui-ci est +initialisé grâce à la méthode **init(TopiaContextImplementor)**. Il peut +alors se mettre listener sur le context ou les DAO par exemple. Copied: trunk/src/site/rst/docs/event.rst (from rev 3106, trunk/src/site/rst/devel/event.rst) =================================================================== --- trunk/src/site/rst/docs/event.rst (rev 0) +++ trunk/src/site/rst/docs/event.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,92 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +====================== +Gestion des évènements +====================== + +On peut se mettre listener sur deux sortes d'évènements : les TopiaEntityEvent et +les TopiaVetoableEntityEvent. La difference entre les deux se situe sur le moment de +l'appel. + + +TopiaVetoableEntityEvent +------------------------ + +Les TopiaVetoableEntityEvent sont appelés avant l'action, ce qui +permet de l'interdire en levant une exception (par exemple pour gérer la +sécurité). + +Les TopiaVetoableEntityEvent contiennent la classe à laquelle se rapporte l'event +et si possible l'identifiant de l'objet qui sera impacté. Cela n'est pas +toujours le cas; par exemple lors de la creation, l'identifiant n'existe pas forcément +et donc ne peut-etre donné. + +Propagation +~~~~~~~~~~~ + +Les TopiaVetoableEntityEvent sont aussi levés pour tous les contexts pères +du context qui a produit l'event et ceci juste apres avoir prévenu les +listeners du context courant. + +TopiaEntityEvent +---------------- + +Les TopiaEntityEvent sont appelés après l'action pour prévenir du changement. + +Les TopiaEntityEvent contiennent l'entity à laquelle se rapporte l'event + +Propagation +~~~~~~~~~~~ + +Les TopiaEntityEvent sont propagé au context pere lors du commit du context. + +Si un rollback est fait, alors ce sont les listeners du context eux-même qui +sont prévenus du changement. + +Implantation +============ + +Les DAO sont responsables de l'appel des méthodes fire sur le context qui les +a créés lors de l'appel sur ceux-ci des methodes create, update, delete, find +(pour le chargement). + +Le cas Hibernate +---------------- + +Dans le DAO hibernate le context est listener des différents évènements levés +par la session. Mais ces évènements ne sont levés que lors du commit. Dans Topia +on souhaite avoir directement un évènement lors d'un create, update ou delete +sur le DAO. Le DAO hibernate lève donc des évènements lorsque l'on appelle +ces méthodes. + +On a aussi des évènements lors du commit. Il est donc possible qu'on aie, +par exemple, le même évènement Update envoyé deux fois au listener si on fait +un update sur le DAO suivi du commit sur le context. + +On conserve tout de meme le mécanisme d'évènement levé au moment du commit par +hibernate car il est beaucoup plus puissant. Il permet aussi d'être prévenu de +modifications apportées aux constituants d'une entité et non pas seulement des +évènements portants sur l'entité elle-même comme c'est le cas dans le mecanisme +implanté dans les DAO. Copied: trunk/src/site/rst/docs/hibernate_mapping.rst (from rev 3106, trunk/src/site/rst/devel/HibernateMapping.rst) =================================================================== --- trunk/src/site/rst/docs/hibernate_mapping.rst (rev 0) +++ trunk/src/site/rst/docs/hibernate_mapping.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,120 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +================= +Mapping hibernate +================= + +Ce document décrit les choix de mapping faits en fonction +du diagramme de classe UML. + +JDBC +==== + +Généralité +---------- + +- Tous les objets utilisent le versionnement dans un champs version:: + + <version name="topiaVersion" type="long" node="@topiaVersion"/> + +- On utilise les méthodes d'accès pour accêder aux propriétés + +Héritage +-------- + +- Seules les classes concrêtes ont un mapping (au travers de l'interface + impl) +- Chaque classe à un fichier de mapping séparé. + +On utilisera union-subclass + +Identifiant +----------- + +Lors de la description de la classe, on peut indiquer de ne pas générer de clé +technique. Dans ce cas, la clé métier est utilisée (tagvalue: technicalKey=false). +Par défaut une clé technique est utilisée et est de la forme uuid.hex:: + + <id name="topiaId" column="topiaId" type="string"> + <generator class="uuid.hex"/> + </id> + +La description de la clé métier est faite par un tagvalue sur la classe +(tagvalue: key=prop1,prop2,prop3). Si une clé technique est utilisée, une +contrainte d'unicité est tout de même faite sur la clé métier. + +La clé métier sert aussi pour le toString, equals, hashCode. + +Si l'id d'une entité est composé de plusieurs champs, ces champs doivent-être +rassemblés dans une classe indépendante de l'entité. Par contre le mapping +assemble l'entity et son id dans la même table:: + + <composite-id name="#field" class="#class"> + <key-property name="#field1" column="#col1"/> + <key-property name="#field2" column="#col2"/> + <key-property name="#field3" column="#col3"/> + </composite> + +Si l'id est un objet simple il peut être directement mis dans l'entité. + +Relation 1-0 +------------ + + + +Relation 1-1 +------------ + +Relation 0-N +------------ + +Relation 1-N +------------ + +Relation N-N +------------ + +Classe d'association +-------------------- + +Composition +----------- + +Le composant peut changer de propriétaire (set méthode) mais le +propriétaire perd en même temps le lien vers son composé. + +Aggregation +----------- + +Si une classe est aggrégée avec une autre, alors elle suit la vie de l'entité +à laquelle elle est aggrégée (cascade delete, update) + +Elle ne peut pas être affectée a une autre entité. Pas de set sur cette classe +vers l'autre classe. + +XML +=== + +Toutes les propriétés sont des éléments sauf la clé technique qui est un +attribut. Copied: trunk/src/site/rst/docs/isolation.rst (from rev 3106, trunk/src/site/rst/devel/Isolation.rst) =================================================================== --- trunk/src/site/rst/docs/isolation.rst (rev 0) +++ trunk/src/site/rst/docs/isolation.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,92 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +=========================== +Isolation des TopiaContexts +=========================== + + +Remarque: les requètes ne sont pas bonnes, mais sont là pour donner l'idée +générale. + +Pour mettre en place l'isolation entre les différents TopiaContexts créés par +beginTransaction, il faut ajouter un nouvelle propriété sur les +TopiaEntity: TopiaContextId. Cette propriété prend la valeur de l'id du +TopiaContext qui a créé ou chargé l'objet. On voit donc que plusieurs objets +ayant le même id peuvent exister, le TopiaContextId doit donc faire partie +de la clé de l'objet. Il faut aussi ajouter un champs TopiaDeleted pour +savoir si un objet a été effacé ou non. + +Dans le mapping hibernate pour chaque class d'entité, on a un filtre: +where TopiaContextId == :id || (TopiaContextId > 0 && TopiaContextId <= :id) + +Ce filtre n'est pas suffisant car on a toutes les versions commités de +l'objet jusqu'a :id, il faut un autre filtre apres les recherches pour +n'avoir que les dernieres versions des entites et supprimer dans ce groupe +les entitées marquées et effacées. +where TopiaContextId = max(TopiaContextId) && isDeleted=false group by topiaId + +Lors d'un beginTransaction le nouveau TopiaContext active ce filtre pour son +propre id. + +De cette manière un TopiaContext ne voit que les objets qu'il a créé et/ou +modifié, ou les objets plus ancien que lui. + +Cet Id est: - System.nanoTime() et donc toujours négatif. + +Lors d'un commit d'un TopiaContext, on passe tous les TopiaContextId de +toutes les entités qui sont égales a l'id du TopiaContext en sa version +positive: update <table> set TopiaContextId = -:id where TopiaContextId = :id +De plus le TopiaContext renouvelle son id et modifie tous les filtres pour +qu'il aie la vision d'objets créés par d'autre TopiaContext avant son commit. + +Lors d'un rollback il suffit de faire le renouvellement de l'id et la mise à +jour des filtres. + +Sous-transaction +================ + +La gestion des TopiaContextId pourrait offrir les sous-transactions, si +dans le filtre on ajoutait comme condition, au lieu de TopiaContextId == :id, +TopiaContextId in (:idList) ou idList serait la liste des ids du +TopiaContext courant ainsi que des TopiaContext parents. + +Historisation +============= + +La gestion des TopiaContextId permet d'offrir l'historisation de tous les +objets. Car tous les objets commités sont conservés avec un TopiaContextId +différent pour chaque version. + +Implantation +============ + +- Mettre en place les champs supplémentaires: TopiaContextId, TopiaDeleted +- Modifier la clé primaire pour ajouter TopiaContextId +- Ajouter les filtres dans les mappings +- Ajouter un id sur les TopiaContext +- Modifier le comportement de DAO.delete pour qu'il marque juste l'objet + comme effacé sans l'effacer TopiaDeleted=true +- Pour toutes les recherches ajouter un filtre pour ne retourner que les + derniere version non deleted Copied: trunk/src/site/rst/docs/project.rst (from rev 3106, trunk/src/site/rst/devel/project.rst) =================================================================== --- trunk/src/site/rst/docs/project.rst (rev 0) +++ trunk/src/site/rst/docs/project.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,35 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin, Chatellier Eric +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +============================================= +Liste de projets similaires ou se rapprochant +============================================= + +subPersistence +-------------- + +http://subpersistence.sourceforge.net/ + +Librairie d'abstraction de libraire de mapping O/R +Supporte Hibernate pour l'instant. Semble vouloir supporter aussi Castor. Copied: trunk/src/site/rst/docs/schema_migration.rst (from rev 3106, trunk/src/site/rst/devel/SchemaMigration.rst) =================================================================== --- trunk/src/site/rst/docs/schema_migration.rst (rev 0) +++ trunk/src/site/rst/docs/schema_migration.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,177 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin, Chatellier Eric +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +========================================================= +Comment migrer les version d'un schema de base de données +========================================================= + +Lorsque des modifications sont effectuer dans une application qui impacte +le schema de base de données, celui doit subir des migrations. +ToPIA fournit une API visant a assister le developpeur pour migrer un schema +de base de données. + +Approche +-------- + +TODO approche migration par copy +TOOD approche migration par requette sql + +Configuration +------------- + +Pour commencer, topia doit connaitre l'ensemble des versions de la base +de données, et la version actuelle de l'application. Si la version de l'application +diffère de celle de la base de données, une migration sera effectuée. +Après la migration, la version de la base de données est égale à celle de +l'application. + +Dépendances +~~~~~~~~~~~ + +La migration est effectuée par le service de migration de ToPIA. Il est +necessaire de l'ajouter explicitement. + +:: + + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-service-migration</artifactId> + <version>2.5.3</version> + <scope>compile</scope> + </dependency> + +Class de definition des migration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pour commencer, il faut créer la classe definissant les versions. + +:: + + public class DatabaseMigrationClass extends TopiaMigrationCallbackByClass { + + protected static final Version VERSION_1 = new Version("1"); + protected static final Version VERSION_2 = new Version("2"); + protected static final Version VERSION_3 = new Version("3"); + + public DatabaseMigrationClass() { + super(new MigrationResolver()); + } + + protected static class MigrationResolver implements MigrationCallBackForVersionResolver { + + @Override + public Class<? extends MigrationCallBackForVersion> getCallBack(Version version) { + Class<? extends MigrationCallBackForVersion> result = null; + + if (version.equals(VERSION_1)) { + result = MigrationV0V1.class; + } + else if (version.equals(VERSION_2)) { + result = MigrationV1V2.class; + } + else if (version.equals(VERSION_3)) { + result = MigrationV2V3.class; + } + return result; + } + + } + + @Override + public Version[] getAvailableVersions() { + Version[] result = new Version[] { VERSION_1, VERSION_2, VERSION_3 }; + return result; + } + + @Override + public Version getApplicationVersion() { + Version appVersion = new Version(MyAppDAOHelper.getModelVersion()); + return appVersion; + } + + @Override + public boolean askUser(Version dbVersion, List<Version> versions) { + return true; + } + + } + +Classes de migration de version +------------------------------- + +Ensuite, il faut créer une classe par migration. + +Par exemple, voici la classe migrant le shema de la version 0 à la version 1 : +MigrationV0V1. + +:: + + public class MigrationV0V1 extends MigrationCallBackForVersion { + + public MigrationV0V1(Version version, TopiaMigrationCallbackByClass callBack) { + super(version, callBack); + } + + @Override + protected void prepareMigrationScript(TopiaContextImplementor tx, + List<String> queries, boolean showSql, boolean showProgression) + throws TopiaException { + queries.add("alter table SETOFVESSELS add column TECHNICALEFFICIENCYEQUATION VARCHAR(255);"); + queries.add("alter table STRATEGY add column INACTIVITYEQUATIONUSED BIT default false;"); + queries.add("alter table STRATEGY add column INACTIVITYEQUATION VARCHAR(255);"); + queries.add("alter table STRATEGYMONTHINFO alter NUMBEROFTRIPS double;"); + queries.add("alter table STRATEGYMONTHINFO alter MININACTIVITYDAYS double;"); + } + } + +Configuration du topia context +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Pour finir, il faut ajouter l'utilisation de la migration par ces classe +dans le topia context. En effet, la migration est effectuée automatiquement +lors de l'ouverture d'un TopiaContext. + +Configuration: + +:: + + config.put(TopiaMigrationService.TOPIA_SERVICE_NAME, TopiaMigrationEngine.class.getName()); + config.put(TopiaMigrationService.MIGRATION_CALLBACK, DatabaseMigrationClass.getName()); + +ou dans un fichier de properties : + +:: + + topia.service.migration=org.nuiton.topia.migration.TopiaMigrationEngine + topia.service.migration.callback=org.test.myapp.DatabaseMigrationClass + + +Kettle +------ + +Une autre idee est de ne pas utiliser hibernate mais kettle pour la +migration des données. Nous aurions de la même façon dans le nom des tables +un numero de version de schéma. Un fichier kettle decrirait la migration +d'une version à une autre. Et les différents fichiers serait chaînés pour +arriver au schéma souhaité. Copied: trunk/src/site/rst/docs/security.rst (from rev 3106, trunk/src/site/rst/devel/security.rst) =================================================================== --- trunk/src/site/rst/docs/security.rst (rev 0) +++ trunk/src/site/rst/docs/security.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,52 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +======== +sécurité +======== + +Implantation de la sécurité +=========================== + +La sécurité est un simple objet java qui hérite de TopiaHelper + +Il se met alors listener sur tous les events vetoables et lève des exceptions +si la personne qui essaie de charger/créer/modifier/supprimer l'objet n'en a pas +le droit. + +Le service de sécurité vient avec son fichier de configuration. Dans ce fichier +il y a les paramètres utiles au service pour retrouver les informations sur les +droits. + +TopiaHelper est en fait une interface qui contient la méthode +init(TopiaContext, Properties) + + +package +------- + +:org.nuiton.topia.security: pour tout ce qui touche a la sécurité + (TopiaAuthenticationHelper, TopiaAuthorisationHelper, LoginModule, Filter, ...) +:org.nuiton.topia.security.entities: pour les entities utiles à la définition + de la sécurité (user, group, permission) Copied: trunk/src/site/rst/docs/todo.rst (from rev 3106, trunk/src/site/rst/devel/Todo.rst) =================================================================== --- trunk/src/site/rst/docs/todo.rst (rev 0) +++ trunk/src/site/rst/docs/todo.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,255 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +==== +TODO +==== + +Recherches à faire +------------------ + +- des persistences hibernates sur LDAP ou FlatFile +- des outils de migration/evolution de schema + +Generic DAO +----------- +http://www.hibernate.org/328.html:: + + public abstract class GenericHibernateDAO<T> { + ... + Class<T> persistentClass = (Class<T>) ((ParameterizedType) getClass() + .getGenericSuperclass()).getActualTypeArguments()[0]; + + +Regarder si TopiaContext ne pourrait pas être remplacé par un PicoContainer +http://www.hibernate.org/180.html +http://www.hibernate.org/182.html + +doc sur l'optimisation des requetes HQL +http://www.jroller.com/page/wakaleo/?anchor=hibernate_optimisation + +Generation +---------- + +- (2) import/export XML dans ToPIA, à mettre dans le mapping hibernate (en partie fait, mais très stable...) + + +Gestion des versions des POJO +----------------------------- + +mettre en place serialVersionUID sur les entités + +Gestion des droits et de la sécurité +------------------------------------ + +Le créateur de l'objet n'est pas dans l'objet lui même mais dans une table a +part. + +Owner: topiaId de l'entity, id du propriétaire + +Les droits des objets sont dans une table a part +(voir http://www.hibernate.org/140.html). + +Il serait bon que les droits s'appliquent sur un group ou un user. Et qu'un user +puisse appartenir a un group, et qu'un group puisse aussi appartenir a un group + +Il faut aussi modifier le Policy ou autre pour pouvoir lire les permissions +dans hibernate lorsqu'on nous les demandes. Mettre des méthodes statique dans +une classe contenant une session hibernate statique pour permettre l'ajout +de permission a l'execution, sans qu'on est besoin de relire toutes les +permissions a chaque fois, la session servant de cache (mais les sessions +ne sont pas multithread d'ou le synchronise) + +synchronized public void addPermission(TopiaPermission); +synchronized public List<TopiaPermission> getAllPermission(); + +Entity directement dans Topia +----------------------------- + +- User: login, password, email +- Group: name, (User|Group)* +- Permission: action(create, load, update, delete, admin permission), classname, + principal, topiaId de l'entity ou null si le droit sur toutes les entites de ce type + + +Les services +------------ + +..image: ServiceCall.png + +Les services on besoin d'avoir le context de l'appelant pour pouvoir faire +des choix: +- choix de la base de données +- droit de l'utilisateur +- ... + +Pour cela le premier argument de chaque methode generee doit etre un token +retourner par le service d'authentification. + +Le service d'authentification (LA/SSO?) permet de recuperer les informations +du TopiaClientContext qui contient des informations utiles: +- applicationId (identifiant de l'application appelant (im.codelutin.com, im.libre-entreprise.com, ...)) +- clientId (identifiant du client appelant (gaim, exodus, gabber, ...)) +- userLogin +- userPassword + +On a un TopiaServiceManager qui permet de recuperer un proxy sur le service +souhaité. Le proxy n'a pas en premier argument ce TopiaClientContext, il est +ajouté automatiquement lors de l'appel. De cette maniere cote client cela +est completement transparent. + + +# Cote client +ChoremServiceHelper csh = ChoremServiceHelper.getInstance("codelutin.chorem.com", "mentawai", "poussin", "xxxxxxxx"); +CRMService crm = csm.getCRMService(); // retourne un proxy sur le service +List<Person> persons = crm.getAllPerson(); // retourne la liste de toutes les personnes visible par poussin + +# Cote serveur dans getAllPerson(String token) +TopiaClientContext tcc = TopiaAuthenticationService.getTopiaClientContext(token); +Properties prop = ChoremUtil.getContextProperties(tcc); +ChoremContext context = ChoremContext.getContext(prop); +List<Person> result = ChoremDAOHelper.getCRMDAO(context).getAllPerson(); +return result; + +Le moyen de recuperer le TopiaAuthentificationService doit etre specifier +dans les fichiers de configuration de l'application. Il doit y avoir +plusieurs implantation pour ce service: +- class avec methode static pour les applications standalone +- EJB +- service web +- ... + +L'application doit pouvoir plugger sa propre methode d'authentification +(acces a un LDAP, a une BD, a un Liberty Alliance, ...), chaque implantation +doit utiliser cette methode d'authentification (delegation). + +De meme pour l'implantation des services, les services doivent être des +classes Java normal (sans le token en parametre) mais contenant une methode +setTopiaContext() qui permet de mettre a jour + + +Autre +----- + +- tag-value transaction sur les operations des services avec les valeurs + traditionnelles de la spec EJB (required, requiresNew, mandatory, + supports, notSupported, never ). ex auto=required +- dernier user ayant modifié une entité +- tag-value auto avec un pattern sur les attributs. ex auto=now +- tag-value mask avec un pattern sur les attributs. ex : mask=price + puis dans les fichiers de traductions : price=#+,## +- tag-value enumName avec un pattern sur les attributs. ex : + enum=projectStatus + La valeur des énumérations est conservé dans un fichier de configuration + qui peut-etre surchargé par des valeurs dans une table en base de + données : projectStatus=a faire, fait, fini +- tag-value i18n avec un pattern sur les attributs. ex : i18n=true (en partie fait :) ) +- Generation des UI par defaut (JAXX et JSP) +- prendre en compte le contenu de l'onglet doc des entités et attributs + jusqu'au -- pour les tooltips (doc tooltips/doc user/doc dev) + +A reflechir (voir si c vraiment utile) +-------------------------------------- +- pouvoir monitorer un attribut (user, date, oldValue, new Value) + Ces attributs ont une valeur tagguée versioned à vrai ou faux. + -> getHistory[Attribut]():list<History> + +Amélioration templates +---------------------- + +- préférer définir des variables plutôt que d'injecter du code dans les templates : + +Example : + +avant + +:: + + /*{table="<%=GeneratorUtil.getDBName(attr.getDeclaringElement()) + "_" + getName(attr)%>"*/ + + +après + +:: + + String dbName = GeneratorUtil.getDBName(attr.getDeclaringElement()) + "_" + getName(attr); + +ou + +:: + + String attrName = getName(attr); + String dbName = GeneratorUtil.getDBName(attr.getDeclaringElement()); + + /*{table="<%=dbName+"_"+attrName%>"}*/ + +- mettre une javadoc pour dire ce que la méthode va faire + +- incorporer des tests unitaires de génération :) + +- créer des constantes pour les stereotypes tagValues et les utiliser... + +- aller à la chasse aux constantes (exemple propertiesPattern dans DAOAbstractGenerator) + +- faire la chasse au code inutilisé + +- ajouter hasTagValue sur ObjectModelElement dans lutingenerator + +- réfléchir comment générer les imports pour ne plus utilisers les FQN + +- vérifier les javadocs générées (ajouter les exceptions,...) + +- reussir a résoudre les casts dans les DAOAbstraxct sur la méthode getEntityClass + +- réusiner les codes de génération d'attributs : + +:: + + String lazy = " lazy=\""; + if (notEmpty(attr.getTagValue(GeneratorUtil.TAG_LAZY))){ + lazy += attr.getTagValue(GeneratorUtil.TAG_LAZY); + } else { + lazy += "true"; + } + lazy += "\""; + +mais il ya d'autres cas à prévoir... : + +:: + + String fetch = ""; + if (notEmpty(attr.getTagValue(GeneratorUtil.TAG_FETCH))){ + fetch = " fetch=\"" + attr.getTagValue(GeneratorUtil.TAG_FETCH) + "\""; + } + +- Dans lutingenerator, renommer Util en GeneratorUtil et dans ToPIA, + GeneratorUtil en TopiaGeneratorUtil + +- supprimer les les boucles sur Iterator quand c'est possible et utiliser pluot des for-each + +- étudier la nécessité des GeneratorUtil.toLowerCaseFirstLetter(assocAttrName) présents dans EntityAbstractGenerator à propos des classes d'assoc + +- TODO Check wether this method could be used to generate getter and setters + +- Uniformiser et faire hériter les générateurs des interfaces et classe d'impl pour que le générateur de la classe d'impl soit capable de générer aussi l'interface Added: trunk/src/site/rst/docs/y_cycle.rst =================================================================== --- trunk/src/site/rst/docs/y_cycle.rst (rev 0) +++ trunk/src/site/rst/docs/y_cycle.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,33 @@ + +============================================= +Qu'est-ce qu'un cycle de développement en Y ? +============================================= + +Le cycle de développement en Y traditionnel peut être représenté de la manière +suivante : + +Les deux branches, la branche fonctionnelle (porteuse de la solution logique) et +la branche technique (qui définit la plateforme technique sur laquelle la +solution sera implantée) se rejoignent en amont de la conception détaillée et du +codage. Cette projection peut être accompagnée de génération de code, mais il +reste toujours une certaine quantité de code écrite à la main. + +Cette séparation des responsabilités et ce processsus donnent pleine satisfaction +lors du développement initial d'un logiciel. La vie d'un logiciel commence +toutefois au moment de sa mise en production et les évolutions qui y seront +apportées sont de deux natures : + + - Évolutions fonctionnelles : Ajout de fonctionnalités, correction de bugs, ... + - Evolutions techniques : Changement de bases de données, changement de + technologie sur les UI, nouveaux accès (SOAP ?), ... + +Si les évolutions fonctionnelles sont prises en compte par la nature itérative +des processus de développement, les évolutions techniques sont elles difficiles. + +Comment passer d'Hibernate à JDO, de Swing au client léger, des EJB aux +conteneurs légers ? En supprimant les dépendances de votre code sur les briques +techniques, en codant sur une plateforme technique abstraite, interfaces et +façades au travers desquelles vous pourrez manipuler les différentes solutions +techniques que vous retiendrez. Hibernate et JDO ne sont que deux API d'accès +aux données; Swing et client léger, des UI; les EJB et les conteneurs légers, +des logiques métiers déportées... Modified: trunk/src/site/rst/index.rst =================================================================== --- trunk/src/site/rst/index.rst 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/src/site/rst/index.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -29,24 +29,24 @@ ToPIA est un framework d'abstraction des plateformes techniques. À l'heure actuelle ToPIA se focalise sur la persistence des données. -Concrètement, lorsque vous utilisez ToPIA, vous définissez dans un premier temps votre modèle UML, puis vous codez votre -code métier sans vous soucier de la persistence. C'est ToPIA qui va s'occuper de ce qui se passe entre ces 2 étapes. +Concrètement, lorsque vous utilisez ToPIA, vous définissez votre modèle UML, puis vous codez votre code métier sans vous +soucier de la persistence. C'est ToPIA qui va s'occuper de ce qui se passe entre ces 2 étapes. Comment ça marche ? =================== -Avant tout, le développeur doit créer un modèle UML qui représente vos objets métier. +Avant tout, vous devez créer un modèle UML qui représente vos objets métier. Ici, nous avons un modèle très simple dans lequel un employé est caractérisé par son nom, son genre et sa ville de résidence. Une société est constituée d'un nom, d'un SIRET et d'une liste d'employés. |DIAGRAMME| -En amont de la compilation, ToPIA va générer les fichiers nécessaires à son bon fonctionnement. Ces fichiers générés -ajoutés au code que vous avez écrit constituent les sources de l'application. Cela signifie que vous bénéficiez de -toute la robustesse d'une compilation Java, alliée à une sérieuse économie de lignes de code. Lorsque vous packagez votre -application, vous packagez donc des sources déjà générées, rien n'est généré ultérieurement. +En amont de la compilation, ToPIA va générer (grâce à `Eugene`_)les fichiers nécessaires à son bon fonctionnement. Ces +fichiers générés ajoutés au code que vous avez écrit constituent les sources de l'application. Cela signifie que vous +bénéficiez de toute la robustesse d'une compilation Java, alliée à une sérieuse économie de lignes de code. Lorsque vous +packagez votre application, vous packagez donc des sources déjà générées, rien n'est généré ultérieurement. Les fichiers ainsi générés vous permettent de manipuler vos objets, de les charger depuis la base, les persister, les supprimer ... Pour cela, vous disposez de plusieurs API de base qui donnent accès aux opérations les plus courantes, @@ -64,146 +64,85 @@ l'heure actuelle, ToPIa se base sur `Hibernate`_, mais le framework est pensé de manière à masquer autant que possible ce choix technique afin de faciliter une éventuelle migration vers un autre framework de mapping objet-relationnel. +`Plus de détails sur les cycles en Y`_. -Avantages -========= -TODO +Les services +============ -Version 3.0 -=========== +Autour de la persistence, ToPIA propose un certain nombre de services qui peuvent être activés ou non et qui vous +permettent de bénéficier d'autres fonctionnalités ou encore de rajouter des comportements auxquels nous n'aurions pas +pensé. -La version 3.0 de ToPIA est en cours de développement. Si vous utilisiez déjà la version 2, `consultez le guide de migration`_. + - `Service de gestion des mises à jour`_ : permet de gérer les migrations de base lorsque vous déployez une nouvelle + version de votre application ; + - `Service de gestion des mises à jour (Flyway)`_ : permet également de gérer les migrations de base en se basant sur + `Flyway`_ ; + - `Service de réplication`_ : permet de répliquer des données de base à base ; + - `Service CSV`_ : service gérant les imports et expots au format CSV. +Avantages +========= + - Principales méthodes générées pour le recherche/chargement des objets ; + - Pas de mapping ORM à écrire ; + - Génération de code intelligente (basé sur l'héritage Java, compilation, ...) ; + - En dépit de la génération de code, il est toujours possible de remplacer une classe générée ; + - Déjà utilisé dans des projets à forte volumétrie ; + - Quasi-indépendance du code métier par rapport à la solution de persistence ; + - Migrations facilitées lors des livraisons de nouvelles versions ; + - Intégration transparente à l'outil de construction du projet (Maven, ...) ; + - ... +Par où commencer ? +================== +ToPIA est disponible sur Maven Central +:: + <dependency> + <groupId>org.nuiton</groupId> + <artifactId>topia-perssitence</artifactId> + <version>3.0-beta-3</version> + </dependency> +Consultez les tutos pour créer votre projet à base de ToPIA en fonction de votre besoin : + - `Créer un projet ToPIA en partant de rien`_ ; + - `Migrer de ToPIA 2.x vers ToPIA 3`_ ; + - ... -Ancienne version de la page d'accueil -===================================== +Version 3.0 +=========== -TODO À supprimer/migrer +|INFO| La version 3.0 de ToPIA est en cours de développement. Si vous utilisiez déjà la version 2, `consultez le guide de migration`_. -C'est à dire ? -~~~~~~~~~~~~~~ -Le cycle de développement en Y traditionnel peut être représenté de la manière -suivante : -Les deux branches, la branche fonctionnelle, porteuse de la solution logique, et -la branche technique, qui définit la plateforme technique sur laquelle la -solution sera implantée, se rejoignent en amont de la conception détaillée et du -codage. Cette projection peut être accompagnée de génération de code, mais il -reste toujours une certaine quantité de code écrite à la main. -Cette séparation des responsabilités et ce processsus donne pleine satisfaction -lors du développement initial d'un logiciel. La vie d'un logiciel commence -toutefois au moment de sa mise en production et les évolutions qui y seront -apportées sont de deux natures : - - Évolutions fonctionnelles : Ajout de fonctionnalités, correction de bugs, ... - - Evolutions techniques : Changement de bases de données, changement de techno - sur les UI, nouveaux accès (SOAP ?), ... -Si les évolutions fonctionnelles sont prises en compte par la nature itérative -des processus de développement, les évolutions techniques sont elles difficiles. -Comment passer d'hibernate à JDO, de Swing au client léger, des EJB aux -conteneurs légers ? En supprimant les dépendances de votre code sur les briques -techniques, en codant sur une plateforme technique abstraite, interfaces et -facades au travers desquels vous pourrez manipuler les différentes solutions -techniques que vous retiendrez. Hibernate et JDO ne sont que deux API d'accès -aux données; Swing et client léger, des UI; les EJB et les conteneurs légers, -des logiques métiers déportées... -Et ToPIA alors ? -~~~~~~~~~~~~~~~~ +.. _Service de gestion des mises à jour: ../topia-service-migration +.. _Service de gestion des mises à jour (Flyway): ../topia-service-flyway +.. _Service de réplication: ../topia-service-replication +.. _Service CSV: ../topia-service-csv -ToPIA propose une telle plateforme. Vous codez en regard d'une API qui abstrait -la distribution (1-tiers ?, 2-tiers ?, 3-tiers ?, n-tiers ? quels protocoles -d'accès ?), la persistence (quelles bases bien sûr, mais également quel -framework ?, quelle API de requètage (EJB-QL, JDO-QL, ... ?), quel méchanisme -transactionnel ?), quelle UI ? Puis vous projettez votre application sur la -palteforme de votre choix. +.. _consultez le guide de migration: ./tutos/migrate_to_3.0.html +.. _Migrer de ToPIA 2.x vers ToPIA 3: ./tutos/migrate_to_3.0.html +.. _Plus de détails sur les cycles en Y: ./docs/y_cycle.html +.. _Créer un projet ToPIA en partant de rien: ./tutos/from_scratch.html -Fonctionnement classique ------------------------- - -Le framework ToPIA permet dans un projet de générer la partie métier de l'application, -c'est à dire les classes JAVA ainsi que le mapping Hibernate pour la persistance. -Cela représente un travail considérable en moins pour le développeur et une -flexibilité importante dans les évolutions futures de la parties métier. - -L'utilisation du framework ToPIA se découpe en plusieurs phases, elles sont -itératives : - - 1. Création du diagramme de classe sur ArgoUML_ par exemple - 2. Exportation du modèle en XMI - 3. Génération des fichiers JAVA et Hibernate par Eugene_ - 4. Implentation des méthodes - -ToPIA-service -------------- - -Le framework ToPIA peut être complêté par une multitude de services. Il existe -actuellement trois : - - - `service pour la sécurité`_ : permet la gestion des authentification et des - autorisations. Il repose sur le mécanisme de JAAS. - - `service pour la gestion des mises à jour`_ : permet de mettre à jour une version - de base à partir d'un modèle versionné. - - `service de réplication`_ : permet de répliquer des données de base à base. - - ``service pour la gestion d'un historique`` : permet de conserver l'ensemble des - actions réalisées sur la base de données (**plus maintenu depuis la 2.3.3**). - - ``service pour la recherche`` : permet de rechercher un mot clé parmis les entités - de l'application. Il repose sur la librairie lucene d'apache (**plus maintenu depuis la 2.3.3**). - -.. _service pour la sécurité: ../topia-service-security -.. _service pour la gestion des mises à jour: ../topia-service-migration -.. _service de réplication: ../topia-service-replication +.. _Hibernate: http://hibernate.org/ .. _Eugene: http://doc.nuiton.org/eugene/ +.. _Flyway: http://flywaydb.org/ .. _ArgoUML: http://argouml.tigris.org/ - -Constitution ------------- - -Il est actuellement composé d'un module principal : - - * `ToPIA-persistence`_ : pour la gestion de la persistance sur Hibernate - -Depuis la version 2.3.3, le module **ToPIA-soa** n'est plus maintenu. - -Services --------- - -Depuis la version 2.2.0, ToPIA-service a été intégré au projet ToPIA, chaque service devient un module : - - * `ToPIA-service-migration`_ : service de migration de bases sans perte de données. - * `ToPIA-service-replication`_ : service de replication de données entre 2 bases. - * `ToPIA-service-security`_ : service de sécurité. - -Depuis la version 2.3.3, certains services ne sont plus maintenus (car ils sont à -l'heure actuelle des prototypes et ne sont pas utilisables ad hoc). - - * **ToPIA-service-history** : service d'historisation de données en base. - * **ToPIA-service-index** : service d'indexation de données. - -.. _ToPIA-persistence: ./topia-persistence -.. _ToPIA-service-migration: ./topia-service-migration -.. _ToPIA-service-replication: ./topia-service-replication -.. _ToPIA-service-security: ./topia-service-security - -.. _consultez le guide de migration: ./migrate_to_3.0.html -.. _Hibernate: http://hibernate.org/ - .. |RECOMMENDED| image:: recommended.png .. |INFO| image:: info.png .. |DIAGRAMME| image:: employeeAndCompany.png Deleted: trunk/src/site/rst/migrate_to_3.0.rst =================================================================== --- trunk/src/site/rst/migrate_to_3.0.rst 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/src/site/rst/migrate_to_3.0.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -1,352 +0,0 @@ -.. - -.. * #%L -.. * ToPIA -.. * $Id$ -.. * $HeadURL$ -.. * %% -.. * Copyright (C) 2004 - 2014 CodeLutin -.. * %% -.. * This program is free software: you can redistribute it and/or modify -.. * it under the terms of the GNU Lesser General Public License as -.. * published by the Free Software Foundation, either version 3 of the -.. * License, or (at your option) any later version. -.. * -.. * This program is distributed in the hope that it will be useful, -.. * but WITHOUT ANY WARRANTY; without even the implied warranty of -.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. * GNU General Lesser Public License for more details. -.. * -.. * You should have received a copy of the GNU General Lesser Public -.. * License along with this program. If not, see -.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. -.. * #L% -.. - - -================================ -Migrer depuis ToPIA 2.x vers 3.0 -================================ - -.. contents:: - - -Gestion des dépendances -======================= - -|MANDATORY| - -ToPIA nécessite des versions minimum de Eugene et Hibernate. Vous devez utiliser les version suivantes : - - * Eugene >= 2.9 - * Hibernate >= 4.3.5.Final - - -Configuration du plugin Maven -============================= - -|MANDATORY| - -Les templates sont contenus dans un modules à part, il faut désormais utiliser -cette dépendance dans le plugin eugene. - -:: - - <dependency> - <groupId>org.nuiton.topia</groupId> - <artifactId>topia-templates</artifactId> - <version>3.0</version> - </dependency> - -De plus les templates ont changé de package, le nouveau package est le suivant : - -:: - - org.nuiton.topia.templates - -Refonte des indexed/ordered -=========================== - -|MANDATORY| - -Vous devez migrer votre modèle zargo depuis la beta-3 suite à une confusion entre ordered et indexed (stéréotypes -à placer sur une association-end d'un lien entre deux entités). - - * Le stéréotype "indexed" est déprécié, vous devez le remplacer par l'attribut "ordered" - * L'attribut (ou le stéréotype) "ordered" maintient l'ordre d'insertion en base, il faut donc vous assurer qu'une - colonne <champ>_idx est bien présente dans la base de donnée et au besoin écrire la migration nécessaire (voir - `le guide dédié`_) pour ajouter la colonne et fixer les indexes manquants (en commençant à 0). - * Les types des collections générées ont changé afin d'utiliser un contrat plus proche du modèle (selon la présence - des stéréotypes "unique" et/ou "ordered"). - -NB : La documentation contient des `examples de migration pour la refonte des indexed/ordered`_. - -Code déprécié -============= - -La migration vers ToPIA 3.0 voit un certain nombre de classes et attributs dépréciés. - -Gérer les impacts n'est pas *nécessaire* pour passer à ToPIA 3.0, mais c'est fortement recommandé. En effet, ce code -deviendra incompatible avec ToPIA 3.1, gérer les impacts au plus tôt permettra une migration en douceur. - -Pas vrai, à partir de la 3.0-alpha-6, on casse la rétro-compatibilité car sinon -c'est trop compliqué à gérer. - -Propriétés TOPIA_* ------------------- - -|RECOMMENDED| - -Les constantes suivantes sont à remplacer par leurs homologues avec le prefix *PROPERTY_* : - - * ``TopiaEntity#TOPIA_ID`` devient ``TopiaEntity#PROPERTY_TOPIA_ID`` - * ``TopiaEntity#TOPIA_CREATE_DATE`` devient ``TopiaEntity#PROPERTY_TOPIA_CREATE_DATE`` - * ``TopiaEntity#TOPIA_VERSION`` devient ``TopiaEntity#PROPERTY_TOPIA_VERSION`` - * ``TopiaEntityContextable#TOPIA_CONTEXT`` devient ``TopiaEntityContextable#PROPERTY_TOPIA_CONTEXT`` - * ``TopiaEntity#COMPOSITE`` devient ``TopiaEntityContextable#PROPERTY_COMPOSITE`` - * ``TopiaEntity#AGGREGATE`` devient ``TopiaEntityContextable#PROPERTY_AGGREGATE`` - - -TopiaId -------- - -|MANDATORY| - -La classe sera supprimée. Pour manipuler les topiaId, il faut utiliser le **TopiaIdFactory**. - -La forme des topiaIds générés à changé. Si vous souhaitez conserver l'ancienne forme parce que vous -souhaitez conserver l'uniformité avec une base de données existante ou si vous utilisez -topia-service-security, vous devez explicitement le spécifier à Topia 3.0 via la configuration : - - ``topia.persistence.topiaIdFactoryClassName=org.nuiton.topia.persistence.internal.LegacyTopiaIdFactory`` - - -TopiaContextImplementor est supprimé ------------------------------------- - -Cette classe joue un rôle central dans ToPIA 2. Elle n'existe plus dans ToPIA 3. - -TODO Expliquer par quoi remplacer. - -TopiaEntity modifié -------------------- - -Les méthodes (``getComposite()``, ``getAggregate()``) ont été déplacées vers le contrat ``TopiaEntityContextable``. - -TopiaService#[preInit|postInit](...) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -|MANDATORY| - -Les services implémentant **TopiaService** doivent changer leur code. -Les méthodes ``preInit(TopiaContextImplementor)`` et ``postInit(TopiaContextImplementor)`` doivent être remplacées par -``preInit(TopiaContext)`` et ``postInit(TopiaContext)`` - -Service de migration --------------------- - -|MANDATORY| - -Toute référence à **TopiaContextImplementor** a été supprimé et remplacée par -**TopiaContext**, cela change donc les signatures et rend le code incompatible, -il faut donc bien effectuer le remplacement dans les callbacks que vous avez -écrits. - - -Gestion des exceptions ----------------------- - -|RECOMMENDED| - -**TopiaRuntimeException** est dépréciée. Il faut désormais déclarer **TopiaException** dans la clause catch. -**TopiaException** devient Runtime. Il n'est plus nécessaire de l'intercepter. - -Généricité ----------- - -|RECOMMENDED| - -Les methodes suivantes sont désormais génériques : - - * ``TopiaContext#find(...)`` - * ``TopiaContext#findAll(...)`` - * ``TopiaContext#findUnique(...)`` - -Si le code précédent réalisait un cast, il faut le supprimer car cela peut causer maintenant une erreur de compilation. - - -TopiaContextListener --------------------- - -|RECOMMENDED| - -L'API **TopiaContextListener** contenant des opérations de manipulation du schéma de base de données a été déprécié. -L'interface est remplacée par **TopiaSchemaListener**. Les méthodes présentes sur le **TopiaContext** qui servaient à -ajouter/supprimer un **TopiaContextListener** sont elles aussi dépréciées au profit de méthodes manipulant des -**TopiaSchemaListener**. - - -Transformer pour la génération des Dao --------------------------------------- - -|RECOMMENDED| - -Si vous utilisiez explicitement le Transformer de DAO dans la configuration de votre plugin Eugene, il faut maintenant -changer le nouveau Transformer : org.nuiton.topia.templates.EntityDaoTransformer - -Exemple de configuration : - -:: - - <plugin> - <groupId>org.nuiton.eugene</groupId> - <artifactId>eugene-maven-plugin</artifactId> - <executions> - <execution> - <id>generate-entities</id> - <phase>generate-sources</phase> - <configuration> - <inputs>classpath:model:/:myProject.objectmodel</inputs> - <defaultPackage>org.project.entities</defaultPackage> - <templates> - org.nuiton.topia.templates.EntityDaoTransformer - </templates> - </configuration> - <goals> - <goal>generate</goal> - </goals> - </execution> - </executions> - </plugin> - - - -|MANDATORY| - -Si vous aviez surchargé certains des DAO générés, vous devrez probablement les renommer et changer leur signature. -Surveillez les logs de génération des DAO à la recherche des messages tels que : - -:: - - WARN [main] (EntityDaoTransformer.java:384) warnOnLegacyClassDetected - Legacy DAO detected ! - - You should consider renaming 'org.project.entities.ZoneDAOImpl' to 'org.project.entities.AbstractZoneTopiaDao' - - Expected class declaration is : public class AbstractZoneTopiaDao<E extends Zone> extends GeneratedZoneTopiaDao<E> { - -Pour l'entité Zone, vous devez supprimer votre ZoneDAO et votre ZoneDAOImpl et déplacer les méthodes -* dans ZoneTopiaDao si la méthode ne peut être utilisée seulement pour l'entité Zone (et pas les sous-classes de Zone) -* dans AbstractZoneTopiaDao si la méthode peut être utilisée pour Zone ET les entités qui héritent de Zone - - -Méthodes findAll, find et findUnique sur TopiaContext ------------------------------------------------------ - -|MANDATORY| - -Si vous utilisiez ces méthodes, il est désormais recommandé d'utiliser les méthodes sur le DAO associé à votre éntité -ou par l'intermédiare du **TopiaJpaSupport**. - -Depuis un DAO surchargé -~~~~~~~~~~~~~~~~~~~~~~~ - -Pour faciliter la migration, ces méthodes ont été portées sur l'interface deprecated **TopiaDAO**. Donc si dans votre -DAO vous faisiez : - -:: - - List<Zone> zones = context.find("FROM Zone WHERE name=:name" , startIndex, endIndex, "name", "Principale"); - -Il vous suffit de retirer le "context." : - -:: - - List<Zone> zones = find("FROM Zone WHERE name=:name" , startIndex, endIndex, "name", "Principale"); - -Dans tous les cas -~~~~~~~~~~~~~~~~~ - -Dans tous les cas, ces méthodes étant dépréciées, vous devriez consulter leur Javadoc pour savoir par quels appels de -méthodes les remplacer. S'il n'y pas de documentation, il faut remplacer le code appellant par le corps de la méthode dépréciée -(fonctionnalité « inline » dans l'IDE). - -Amélioration du code sql ------------------------- - -Voir TopiaSqlQuery, TopiaSqlWork et TopiaSqlSupport. - - -Refactoring des packages -======================== - -|MANDATORY| - -Un grand nombre de classes ont été déplacées. Voici les principaux renommages : - -:: - - org.nuiton.topia.TopiaException -> org.nuiton.topia.persistence.TopiaException - org.nuiton.topia.TopiaDaoSupplier -> org.nuiton.topia.persistence.TopiaDaoSupplier - org.nuiton.topia.TopiaJpaSupport -> org.nuiton.topia.persistence.support.TopiaJpaSupport - org.nuiton.topia.TopiaPersistenceContext -> org.nuiton.topia.persistence.TopiaPersistenceContext - org.nuiton.topia.TopiaNotFoundException -> org.nuiton.topia.persistence.TopiaNotFoundException - org.nuiton.topia.TopiaApplicationContextCache -> org.nuiton.topia.persistence.TopiaApplicationContextCache - org.nuiton.topia.TopiaTransaction -> org.nuiton.topia.persistence.TopiaTransaction - org.nuiton.topia.persistence.TopiaHibernateSessionRegistry -> org.nuiton.topia.persistence.internal.TopiaHibernateSessionRegistry - org.nuiton.topia.TopiaListenableSupport -> org.nuiton.topia.persistence.support.TopiaListenableSupport - org.nuiton.topia.persistence.HibernateProvider -> org.nuiton.topia.persistence.internal.HibernateProvider - org.nuiton.topia.TopiaContextFactory -> org.nuiton.topia.persistence.TopiaConfigurationConstants - - -Le refactoring peut s'effectuer facilement en appliquant les commandes suivantes : - -:: - - grep -m 1 -nr 'org.nuiton.topia.TopiaException' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaException/org.nuiton.topia.persistence.TopiaException/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaDaoSupplier' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaDaoSupplier/org.nuiton.topia.persistence.TopiaDaoSupplier/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaJpaSupport' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaJpaSupport/org.nuiton.topia.persistence.support.TopiaJpaSupport/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaPersistenceContext' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaPersistenceContext/org.nuiton.topia.persistence.TopiaPersistenceContext/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaNotFoundException' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaNotFoundException/org.nuiton.topia.persistence.TopiaNotFoundException/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaApplicationContextCache' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaApplicationContextCache/org.nuiton.topia.persistence.TopiaApplicationContextCache/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaTransaction' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaTransaction/org.nuiton.topia.persistence.TopiaTransaction/g' - grep -m 1 -nr 'org.nuiton.topia.persistence.TopiaHibernateSessionRegistry' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.persistence.TopiaHibernateSessionRegistry/org.nuiton.topia.persistence.internal.TopiaHibernateSessionRegistry/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaListenableSupport' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaListenableSupport/org.nuiton.topia.persistence.support.TopiaListenableSupport/g' - grep -m 1 -nr 'org.nuiton.topia.persistence.HibernateProvider' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.persistence.HibernateProvider/org.nuiton.topia.persistence.internal.HibernateProvider/g' - grep -m 1 -nr 'org.nuiton.topia.TopiaContextFactory' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaContextFactory/org.nuiton.topia.persistence.TopiaConfigurationConstants/g' - grep -m 1 -nr 'TopiaContextFactory.CONFIG_' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/TopiaContextFactory.CONFIG_/TopiaConfigurationConstants.CONFIG_/g' - - -FAQ -=== - -Voici quelques appels faisables en ToPIA 2.x et leur équivalent dans ToPIA 3 - -Accès à un Dao depuis un autre Dao ----------------------------------- - -:: - - // ToPIA 2.x - SpeciesDAO speciesDAO = MyModelDAOHelper.getSpeciesDAO(getContext()); - - // ToPIA 3 - SpeciesTopiaDao speciesDAO = topiaDaoSupplier.getDao(Species.class, SpeciesTopiaDao.class); - - - -Accès à la session Hibernate ----------------------------- - -:: - - // ToPIA 2.x : tx étant le TopiaContext - ((MyModelTopiaPersistenceContextImplementor) tx).getHibernate().flush(); - - // ToPIA 3 : tx étant le MyModelTopiaPersistenceContext - tx.getHibernateSupport().getHibernateSession().flush(); - - - - - -.. _le guide dédié: ./user/ordered_vs_indexed_migration.html -.. _examples de migration pour la refonte des indexed/ordered: ./user/ordered_vs_indexed_migration.html - -.. |RECOMMENDED| image:: recommended.png -.. |MANDATORY| image:: mandatory.png Added: trunk/src/site/rst/tutos/from_scratch.rst.vm =================================================================== --- trunk/src/site/rst/tutos/from_scratch.rst.vm (rev 0) +++ trunk/src/site/rst/tutos/from_scratch.rst.vm 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,274 @@ + +======================================== +Créer un projet ToPIA en partant de rien +======================================== + +Ce tutoriel explique comment créer un projet from scratch. Il se base sur `Maven`_ mais si vous êtes plus à l'aise avec + un autre outil de construction de projet, ça ne devrait pas poser de problème. + + +Créer le projet +=============== + +Pour commencer, il faut créer un projet Maven en respectant les conventions habituelles. Partons d'un projet Maven vide : + +:: + + mvn archetype:generate -DgroupId=com.company -DartifactId=my-topia-app -Dversion=0.1-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart + +L'arborescence du projet ressemble alors à : + + +:: + + my-topia-app + ├── pom.xml + └── src + ├── main + │ └── java + │ └── com + │ └── company + │ └── App.java + └── test + └── java + └── com + └── company + └── AppTest.java + + + +Ajoutez un dossier ``src/main/xmi``, c'est ici que nous allons placer le modèle. + +:: + + cd my-topia-app + mkdir src/main/xmi + +Dans le pom, on ajoute ToPIA en dépendance, et on configure la génération : + +:: + + <properties> + <topia-version>${project.version}</topia-version> + <eugene-version>${eugeneVersion}</eugene-version> + </properties> + + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>${topia-version}</version> + </dependency> + </dependencies> + + <build> + <plugins> + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>eugene-maven-plugin</artifactId> + <version>${eugene-version}</version> + <configuration> + <inputs>zargo</inputs> + <resolver>org.nuiton.util.FasterCachedResourceResolver</resolver> + </configuration> + <executions> + <execution> + <id>generate-entities</id> + <phase>generate-sources</phase> + <configuration> + <!-- Corresponding to extracted package from zargo file --> + <fullPackagePath>com.company.app.entities</fullPackagePath> + <!-- DefaultPackage used for DAOHelper generation --> + <defaultPackage>com.company.app.entities</defaultPackage> + <templates> + org.nuiton.eugene.java.JavaInterfaceTransformer, + org.nuiton.eugene.java.JavaBeanTransformer, + org.nuiton.eugene.java.JavaEnumerationTransformer, + org.nuiton.topia.templates.TopiaMetaTransformer + </templates> + </configuration> + <goals> + <goal>smart-generate</goal> + </goals> + </execution> + </executions> + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>${topia-version}</version> + </dependency> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-templates</artifactId> + <version>${topia-version}</version> + </dependency> + </dependencies> + </plugin> + </plugins> + </build> + + +Créer le modèle avec ArgoUML +============================ + +Avec `ArgoUML`_, créez un nouveau modèle. Nous allons créer un modèle simplifié pour une application de gestion de +bibliothèque. + +Nous avons modélisé les entités ``Book`` et ``Author`` avec les champs appropriés. Faites attention à bien placer les +entités dans le bon package (``com.company.app.entities``), sinon elles ne seront pas générées. Pour que ToPIA sache que +ces classes décrivent des entités qui ont vocation à être sauvées en base, il faut leur ajouter le stéréotype ``entity``. + +N'oubliez pas de donner un nom et une version au modèle. + +Enregistrez votre modèle dans ``src/main/xmi`` et nommez le ``library-model.zargo``. + +|MODEL| + +C'est prêt ! +============ + +Il suffit de construire l'application avec Maven. + +:: + + mvn clean install + + + + + + + + + +TODO À terminer + + + + + + + + + + + +La compilation va provoquer la phase de génération. Si on examine le contenu +de notre dossier target : + +:: + + topia-tutorial + ├── pom.xml + ├── src + │ ├── main + │ │ ├── java + │ │ │ └── org + │ │ │ └── nuiton + │ │ │ └── topia + │ │ │ └── tutorial + │ │ │ └── library + │ │ ├── resources + │ │ │ ├── library-config.properties + │ │ │ └── log4j.properties + │ │ └── xmi + │ │ ├── library.properties + │ │ └── library.zargo + │ └── test + │ ├── java + │ └── resources + └── target + ├── classes + │ ├── library-config.properties + │ ├── log4j.properties + │ └── org + │ └── nuiton + │ └── topia + │ └── tutorial + │ └── library + │ ├── LibraryConfig.class + │ └── model + │ ├── AuthorAbstract.class + │ ├── Author.class + │ ├── AuthorDAOAbstract.class + │ . + │ . + │ . + └── generated-sources + ├── annotations + ├── java + │ └── org + │ └── nuiton + │ └── topia + │ └── tutorial + │ └── library + │ └── model + │ ├── AuthorAbstract.java + │ ├── AuthorDAOAbstract.java + │ ├── AuthorDAOImpl.java + │ ├── AuthorDAO.java + │ ├── AuthorImpl.hbm.xml + │ ├── Author.java + │ ├── BookAbstract.java + │ ├── BookDAOAbstract.java + │ ├── BookDAOImpl.java + │ ├── BookDAO.java + │ ├── BookImpl.hbm.xml + │ ├── BookImpl.java + │ ├── Book.java + │ └── LibraryDAOHelper.java + ├── models + │ ├── library.objectmodel + │ └── library.properties + └── xmi + ├── library.properties + └── library.xmi + + + +On peut voir que ToPIA a généré ``LibraryDAOHelper`` qui va nous permettre de +récupérer les différents DAO et, pour chaque entité de notre modèle : + + * Une interface + * Une classe abstraite, qui implémente déjà tout le contrat + * Une implantation (vide, seulement les constructeurs) + * Un DAO abstrait + * Une implantation du DAO + * Un fichier de mapping hibernate (*.hbm.xml) + +Comme il s'agit d'une phase de compilation, Maven va ajouter tout le code généré aux +classpath le code généré sera compilé et lié en même temps que le reste de votre application. +Tous les fichiers .class se retrouveront dans target/classes, dans la suite du processus, on +ne distingue plus le code généré du code utilisateur. + +Par la suite, si vous changez le modèle, tout sera re-généré. À chaque ``clean`` +via Maven, tout ce qui a été généré est effacé. Vous pouvez donc re-généré autant +de fois que nécessaire. Attention, Maven ne détecte pas le changement du modèle +si le fichier .zargo a été modifié : il faut donc faire un clean à chaque fois +afin de forcer le re-génération du modèle dans sa dernière version. + + + + + + + + + + + + + +Les données associées aux éléments du modèle +-------------------------------------------- + +Le modeleur n'est parfois pas suffisant pour décrire toute les subtilités du modèle. Le modèle se voulant indépendant de +la plate-forme cible, on ne peut y inclure directement des notions spécifiques à ToPIA. C'est pourquoi nous allons +pouvoir ajouter ces informations spécifiques via le fichier ``src/main/resources/library-config.properties``. + + +.. _Maven: http://maven.apache.org/ +.. _ArgoUML: http://argouml.tigris.org/ + +.. |MODEL| image:: ../library.png \ No newline at end of file Copied: trunk/src/site/rst/tutos/migrate_to_3.0.rst (from rev 3106, trunk/src/site/rst/migrate_to_3.0.rst) =================================================================== --- trunk/src/site/rst/tutos/migrate_to_3.0.rst (rev 0) +++ trunk/src/site/rst/tutos/migrate_to_3.0.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,380 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +================================ +Migrer depuis ToPIA 2.x vers 3.0 +================================ + +.. contents:: + + +Gestion des dépendances +======================= + +|MANDATORY| + +ToPIA nécessite des versions minimum de Eugene et Hibernate. Vous devez utiliser les version suivantes : + + * Eugene >= 2.9 + * Hibernate >= 4.3.5.Final + + +Configuration du plugin Maven +============================= + +|MANDATORY| + +Les templates sont contenus dans un modules à part, il faut désormais utiliser +cette dépendance dans le plugin eugene. + +:: + + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-templates</artifactId> + <version>3.0</version> + </dependency> + +De plus les templates ont changé de package, le nouveau package est le suivant : + +:: + + org.nuiton.topia.templates + +Refonte des indexed/ordered +=========================== + +|MANDATORY| + +Vous devez migrer votre modèle zargo depuis la beta-3 suite à une confusion entre ordered et indexed (stéréotypes +à placer sur une association-end d'un lien entre deux entités). + + * Le stéréotype "indexed" est déprécié, vous devez le remplacer par l'attribut "ordered" + * L'attribut (ou le stéréotype) "ordered" maintient l'ordre d'insertion en base, il faut donc vous assurer qu'une + colonne <champ>_idx est bien présente dans la base de donnée et au besoin écrire la migration nécessaire (voir + `le guide dédié`_) pour ajouter la colonne et fixer les indexes manquants (en commençant à 0). + * Les types des collections générées ont changé afin d'utiliser un contrat plus proche du modèle (selon la présence + des stéréotypes "unique" et/ou "ordered"). + +NB : La documentation contient des `examples de migration pour la refonte des indexed/ordered`_. + +Code déprécié +============= + +La migration vers ToPIA 3.0 voit un certain nombre de classes et attributs dépréciés. + +Gérer les impacts n'est pas *nécessaire* pour passer à ToPIA 3.0, mais c'est fortement recommandé. En effet, ce code +deviendra incompatible avec ToPIA 3.1, gérer les impacts au plus tôt permettra une migration en douceur. + +Pas vrai, à partir de la 3.0-alpha-6, on casse la rétro-compatibilité car sinon +c'est trop compliqué à gérer. + +Propriétés TOPIA_* +------------------ + +|RECOMMENDED| + +Les constantes suivantes sont à remplacer par leurs homologues avec le prefix *PROPERTY_* : + + * ``TopiaEntity#TOPIA_ID`` devient ``TopiaEntity#PROPERTY_TOPIA_ID`` + * ``TopiaEntity#TOPIA_CREATE_DATE`` devient ``TopiaEntity#PROPERTY_TOPIA_CREATE_DATE`` + * ``TopiaEntity#TOPIA_VERSION`` devient ``TopiaEntity#PROPERTY_TOPIA_VERSION`` + * ``TopiaEntityContextable#TOPIA_CONTEXT`` devient ``TopiaEntityContextable#PROPERTY_TOPIA_CONTEXT`` + * ``TopiaEntity#COMPOSITE`` devient ``TopiaEntityContextable#PROPERTY_COMPOSITE`` + * ``TopiaEntity#AGGREGATE`` devient ``TopiaEntityContextable#PROPERTY_AGGREGATE`` + + +TopiaId +------- + +|MANDATORY| + +La classe sera supprimée. Pour manipuler les topiaId, il faut utiliser le **TopiaIdFactory**. + +La forme des topiaIds générés à changé. Si vous souhaitez conserver l'ancienne forme parce que vous +souhaitez conserver l'uniformité avec une base de données existante ou si vous utilisez +topia-service-security, vous devez explicitement le spécifier à Topia 3.0 via la configuration : + + ``topia.persistence.topiaIdFactoryClassName=org.nuiton.topia.persistence.internal.LegacyTopiaIdFactory`` + + +TopiaContextImplementor est supprimé +------------------------------------ + +Cette classe joue un rôle central dans ToPIA 2. Elle n'existe plus dans ToPIA 3. + +TODO Expliquer par quoi remplacer. + +TopiaEntity modifié +------------------- + +Les méthodes (``getComposite()``, ``getAggregate()``) ont été déplacées vers le contrat ``TopiaEntityContextable``. + +TopiaService#[preInit|postInit](...) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +|MANDATORY| + +Les services implémentant **TopiaService** doivent changer leur code. +Les méthodes ``preInit(TopiaContextImplementor)`` et ``postInit(TopiaContextImplementor)`` doivent être remplacées par +``preInit(TopiaContext)`` et ``postInit(TopiaContext)`` + +Service de migration +-------------------- + +|MANDATORY| + +Toute référence à **TopiaContextImplementor** a été supprimé et remplacée par +**TopiaContext**, cela change donc les signatures et rend le code incompatible, +il faut donc bien effectuer le remplacement dans les callbacks que vous avez +écrits. + + +Gestion des exceptions +---------------------- + +|RECOMMENDED| + +**TopiaRuntimeException** est dépréciée. Il faut désormais déclarer **TopiaException** dans la clause catch. +**TopiaException** devient Runtime. Il n'est plus nécessaire de l'intercepter. + +Généricité +---------- + +|RECOMMENDED| + +Les methodes suivantes sont désormais génériques : + + * ``TopiaContext#find(...)`` + * ``TopiaContext#findAll(...)`` + * ``TopiaContext#findUnique(...)`` + +Si le code précédent réalisait un cast, il faut le supprimer car cela peut causer maintenant une erreur de compilation. + + +TopiaContextListener +-------------------- + +|RECOMMENDED| + +L'API **TopiaContextListener** contenant des opérations de manipulation du schéma de base de données a été déprécié. +L'interface est remplacée par **TopiaSchemaListener**. Les méthodes présentes sur le **TopiaContext** qui servaient à +ajouter/supprimer un **TopiaContextListener** sont elles aussi dépréciées au profit de méthodes manipulant des +**TopiaSchemaListener**. + + +Transformer pour la génération des Dao +-------------------------------------- + +|RECOMMENDED| + +Si vous utilisiez explicitement le Transformer de DAO dans la configuration de votre plugin Eugene, il faut maintenant +changer le nouveau Transformer : org.nuiton.topia.templates.EntityDaoTransformer + +Exemple de configuration : + +:: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>eugene-maven-plugin</artifactId> + <executions> + <execution> + <id>generate-entities</id> + <phase>generate-sources</phase> + <configuration> + <inputs>classpath:model:/:myProject.objectmodel</inputs> + <defaultPackage>org.project.entities</defaultPackage> + <templates> + org.nuiton.topia.templates.EntityDaoTransformer + </templates> + </configuration> + <goals> + <goal>generate</goal> + </goals> + </execution> + </executions> + </plugin> + + + +|MANDATORY| + +Si vous aviez surchargé certains des DAO générés, vous devrez probablement les renommer et changer leur signature. +Surveillez les logs de génération des DAO à la recherche des messages tels que : + +:: + + WARN [main] (EntityDaoTransformer.java:384) warnOnLegacyClassDetected - Legacy DAO detected ! + - You should consider renaming 'org.project.entities.ZoneDAOImpl' to 'org.project.entities.AbstractZoneTopiaDao' + - Expected class declaration is : public class AbstractZoneTopiaDao<E extends Zone> extends GeneratedZoneTopiaDao<E> { + +Pour l'entité Zone, vous devez supprimer votre ZoneDAO et votre ZoneDAOImpl et déplacer les méthodes +* dans ZoneTopiaDao si la méthode ne peut être utilisée seulement pour l'entité Zone (et pas les sous-classes de Zone) +* dans AbstractZoneTopiaDao si la méthode peut être utilisée pour Zone ET les entités qui héritent de Zone + + +Méthodes findAll, find et findUnique sur TopiaContext +----------------------------------------------------- + +|MANDATORY| + +Si vous utilisiez ces méthodes, il est désormais recommandé d'utiliser les méthodes sur le DAO associé à votre éntité +ou par l'intermédiare du **TopiaJpaSupport**. + +Depuis un DAO surchargé +~~~~~~~~~~~~~~~~~~~~~~~ + +Pour faciliter la migration, ces méthodes ont été portées sur l'interface deprecated **TopiaDAO**. Donc si dans votre +DAO vous faisiez : + +:: + + List<Zone> zones = context.find("FROM Zone WHERE name=:name" , startIndex, endIndex, "name", "Principale"); + +Il vous suffit de retirer le "context." : + +:: + + List<Zone> zones = find("FROM Zone WHERE name=:name" , startIndex, endIndex, "name", "Principale"); + +Dans tous les cas +~~~~~~~~~~~~~~~~~ + +Dans tous les cas, ces méthodes étant dépréciées, vous devriez consulter leur Javadoc pour savoir par quels appels de +méthodes les remplacer. S'il n'y pas de documentation, il faut remplacer le code appellant par le corps de la méthode dépréciée +(fonctionnalité « inline » dans l'IDE). + +Amélioration du code sql +------------------------ + +Voir TopiaSqlQuery, TopiaSqlWork et TopiaSqlSupport. + + +Refactoring des packages +======================== + +|MANDATORY| + +Un grand nombre de classes ont été déplacées. Voici les principaux renommages : + +:: + + org.nuiton.topia.TopiaException -> org.nuiton.topia.persistence.TopiaException + org.nuiton.topia.TopiaDaoSupplier -> org.nuiton.topia.persistence.TopiaDaoSupplier + org.nuiton.topia.TopiaJpaSupport -> org.nuiton.topia.persistence.support.TopiaJpaSupport + org.nuiton.topia.TopiaPersistenceContext -> org.nuiton.topia.persistence.TopiaPersistenceContext + org.nuiton.topia.TopiaNotFoundException -> org.nuiton.topia.persistence.TopiaNotFoundException + org.nuiton.topia.TopiaApplicationContextCache -> org.nuiton.topia.persistence.TopiaApplicationContextCache + org.nuiton.topia.TopiaTransaction -> org.nuiton.topia.persistence.TopiaTransaction + org.nuiton.topia.persistence.TopiaHibernateSessionRegistry -> org.nuiton.topia.persistence.internal.TopiaHibernateSessionRegistry + org.nuiton.topia.TopiaListenableSupport -> org.nuiton.topia.persistence.support.TopiaListenableSupport + org.nuiton.topia.persistence.HibernateProvider -> org.nuiton.topia.persistence.internal.HibernateProvider + org.nuiton.topia.TopiaContextFactory -> org.nuiton.topia.persistence.TopiaConfigurationConstants + + +Le refactoring peut s'effectuer facilement en appliquant les commandes suivantes : + +:: + + grep -m 1 -nr 'org.nuiton.topia.TopiaException' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaException/org.nuiton.topia.persistence.TopiaException/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaDaoSupplier' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaDaoSupplier/org.nuiton.topia.persistence.TopiaDaoSupplier/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaJpaSupport' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaJpaSupport/org.nuiton.topia.persistence.support.TopiaJpaSupport/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaPersistenceContext' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaPersistenceContext/org.nuiton.topia.persistence.TopiaPersistenceContext/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaNotFoundException' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaNotFoundException/org.nuiton.topia.persistence.TopiaNotFoundException/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaApplicationContextCache' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaApplicationContextCache/org.nuiton.topia.persistence.TopiaApplicationContextCache/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaTransaction' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaTransaction/org.nuiton.topia.persistence.TopiaTransaction/g' + grep -m 1 -nr 'org.nuiton.topia.persistence.TopiaHibernateSessionRegistry' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.persistence.TopiaHibernateSessionRegistry/org.nuiton.topia.persistence.internal.TopiaHibernateSessionRegistry/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaListenableSupport' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaListenableSupport/org.nuiton.topia.persistence.support.TopiaListenableSupport/g' + grep -m 1 -nr 'org.nuiton.topia.persistence.HibernateProvider' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.persistence.HibernateProvider/org.nuiton.topia.persistence.internal.HibernateProvider/g' + grep -m 1 -nr 'org.nuiton.topia.TopiaContextFactory' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/org.nuiton.topia.TopiaContextFactory/org.nuiton.topia.persistence.TopiaConfigurationConstants/g' + grep -m 1 -nr 'TopiaContextFactory.CONFIG_' . | awk -F ':' '{print $1}' | xargs sed -i -e 's/TopiaContextFactory.CONFIG_/TopiaConfigurationConstants.CONFIG_/g' + + +FAQ +=== + +Voici quelques appels faisables en ToPIA 2.x et leur équivalent dans ToPIA 3 + +Démarrage d'une nouvelle transaction +------------------------------------ + +:: + + // ToPIA 2.x : rootTx étant le TopiaContext root + TopiaContext transaction = rootTx.beginTransaction(); + + // ToPIA 3 : rootTx étant le MyModelTopiaApplicationContext + MyModelTopiaPersistenceContext transaction = rootTx.newPersistenceContext(); + // Note : MyModelTopiaPersistenceContext implémente le contrat TopiaTransaction + + +Accès à un Dao depuis un autre Dao +---------------------------------- + +:: + + // ToPIA 2.x + SpeciesDAO speciesDAO = MyModelDAOHelper.getSpeciesDAO(getContext()); + + // ToPIA 3 + SpeciesTopiaDao speciesDAO = topiaDaoSupplier.getDao(Species.class, SpeciesTopiaDao.class); + + + +Accès à la session Hibernate +---------------------------- + +:: + + // ToPIA 2.x : tx étant le TopiaContext + ((MyModelTopiaPersistenceContextImplementor) tx).getHibernate().flush(); + + // ToPIA 3 : tx étant le MyModelTopiaPersistenceContext + tx.getHibernateSupport().getHibernateSession().flush(); + + + +Liste des classes d'implémentation (ou des contrats) +---------------------------------------------------- + +:: + + // ToPIA 2.x + MyModelDAOHelper.getContractClasses(); + MyModelDAOHelper.getImplementationClasses(); + + // ToPIA 3 + MyModelEntityEnum.getContractClasses(); + MyModelEntityEnum.getImplementationClasses(); + + + + + +.. _le guide dédié: ./user/ordered_vs_indexed_migration.html +.. _examples de migration pour la refonte des indexed/ordered: ./user/ordered_vs_indexed_migration.html + +.. |RECOMMENDED| image:: recommended.png +.. |MANDATORY| image:: mandatory.png Deleted: trunk/src/site/rst/user/FAQ.rst =================================================================== --- trunk/src/site/rst/user/FAQ.rst 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/src/site/rst/user/FAQ.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -1,60 +0,0 @@ -.. - -.. * #%L -.. * ToPIA -.. * $Id$ -.. * $HeadURL$ -.. * %% -.. * Copyright (C) 2004 - 2014 CodeLutin -.. * %% -.. * This program is free software: you can redistribute it and/or modify -.. * it under the terms of the GNU Lesser General Public License as -.. * published by the Free Software Foundation, either version 3 of the -.. * License, or (at your option) any later version. -.. * -.. * This program is distributed in the hope that it will be useful, -.. * but WITHOUT ANY WARRANTY; without even the implied warranty of -.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. * GNU General Lesser Public License for more details. -.. * -.. * You should have received a copy of the GNU General Lesser Public -.. * License along with this program. If not, see -.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. -.. * #L% -.. - - -========================== -Frequently Asked Questions -========================== - -Problème lors du chargement d'une entity -======================================== - -Le chargement utilise les méthodes Set des propriétés, il faut donc faire -attention si on les surcharge. - -Il faut faire attention lors de l'ajout, sur l'entity, de méthodes qui ont la -même signature que des méthods Set de propriétés avec juste des arguments -différents, car elles peuvent être utilisées à la place de la vrai méthode -pour quelque valeur (par exemple null). - -Faire fonctionner les Web Services Topia via RMI -================================================ -L'utilisation des Web Services sur RMI impose la génération de classes sauvées -sur disque. -Elle sont construites à la volée et sauvées dans le dossier "./topiagen". - -Ce dossier doit donc se trouver dans le classpath. - -Comment commit (ou rollback) une transaction directement à partir d'un DAO ? -============================================================================ - -Contrairement à ce que l'on pourrait croire aux premiers abords, les méthodes commitTransaction() -et rollbackTransaction() disponibles dans les DAO ne sont pas prévus à cet effet. Il faut toujours -utiliser le contexte pour commit (ou rollback) une transaction. Donc pour le faire à partir d'un DAO : -dao.getContext().commitTransaction() // on récupère le context (transaction sur le DAO) et on commit. -Le principe reste identique pour le rollback. -Pour revenir sur les méthodes commitTransaction() et rollbackTransaction() disponibles sur le DAO, elles -servent de "callback" au moment du commit (ou rollback) de la transaction. Le context se chargera d'appeler -tous les commitTransaction() des DAO, ceci afin de permettre un traitement spécifique au DAO au moment du commit. -Ce traitement peut donc être effectué directement à partir du dao via cette méthode sans passer par le context. - Deleted: trunk/src/site/rst/user/ModelGeneration.rst.vm =================================================================== --- trunk/src/site/rst/user/ModelGeneration.rst.vm 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/src/site/rst/user/ModelGeneration.rst.vm 2014-05-15 16:25:44 UTC (rev 3108) @@ -1,102 +0,0 @@ -.. - -.. * #%L -.. * ToPIA :: Persistence -.. * -.. * $Id$ -.. * $HeadURL$ -.. * %% -.. * Copyright (C) 2004 - 2010 CodeLutin -.. * %% -.. * This program is free software: you can redistribute it and/or modify -.. * it under the terms of the GNU Lesser General Public License as -.. * published by the Free Software Foundation, either version 3 of the -.. * License, or (at your option) any later version. -.. * -.. * This program is distributed in the hope that it will be useful, -.. * but WITHOUT ANY WARRANTY; without even the implied warranty of -.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. * GNU General Lesser Public License for more details. -.. * -.. * You should have received a copy of the GNU General Lesser Public -.. * License along with this program. If not, see -.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. -.. * #L% -.. - - -====================== -Génération des modèles -====================== - - -Le module "topia-persistence" de topia est capable de -générer la persistence à partir d'un modèle UML. - -Nous allons détailler ici comme inclure la génération dans le -cycle de compilation maven. - - -Architecture maven ------------------- - -+---------------------------------+-----------------------------------------+ -| src/main/xmi/mymodel.zargo | exemple de modele UML avec argoUML | -+---------------------------------+-----------------------------------------+ -| src/main/xmi/mymodel.properties | fichier de propriétés attaché au modele | -+---------------------------------|-----------------------------------------+ - - -Configuration du pom.xml ------------------------- - -Pour générer les sources dans la phase "generate-sources" de maven, et utiliser -les sources générées, et faut configurer le pom. - -Plugin Eugene -============= - -:: - - <plugin> - <groupId>org.nuiton.eugene</groupId> - <artifactId>eugene-maven-plugin</artifactId> - <version>${eugeneVersion}</version> - <executions> - <execution> - <id>Generator</id> - <phase>generate-sources</phase> - <configuration> - <inputs>zargo</inputs> - <fullPackagePath>org.company.package</fullPackagePath> - <extractedPackages>org.company.package</extractedPackages> - <templates>org.nuiton.topia.generator.TopiaMetaGenerator</templates> - <defaultPackage>org.company.package</defaultPackage> - </configuration> - <goals> - <goal>generate</goal> - </goals> - </execution> - </executions> - <dependencies> - <dependency> - <groupId>org.nuiton.topia</groupId> - <artifactId>topia-persistence</artifactId> - <version>${project.version}</version> - </dependency> - </dependencies> - </plugin> - -Pour plus d'information à propos d'Eugene, merci de consulter le site : -http://doc.nuiton.org/eugene/ - -Dépendances du projet -===================== - -Il faut enfin ajouter "topia-persistence" en dépendance du projet : - -:: - - <dependency> - <groupId>org.nuiton.topia</groupId> - <artifactId>topia-persistence</artifactId> - <version>${project.version}</version> - </dependency> Copied: trunk/src/site/rst/user/faq.rst (from rev 3106, trunk/src/site/rst/user/FAQ.rst) =================================================================== --- trunk/src/site/rst/user/faq.rst (rev 0) +++ trunk/src/site/rst/user/faq.rst 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,60 @@ +.. - +.. * #%L +.. * ToPIA +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2014 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +========================== +Frequently Asked Questions +========================== + +Problème lors du chargement d'une entity +======================================== + +Le chargement utilise les méthodes Set des propriétés, il faut donc faire +attention si on les surcharge. + +Il faut faire attention lors de l'ajout, sur l'entity, de méthodes qui ont la +même signature que des méthods Set de propriétés avec juste des arguments +différents, car elles peuvent être utilisées à la place de la vrai méthode +pour quelque valeur (par exemple null). + +Faire fonctionner les Web Services Topia via RMI +================================================ +L'utilisation des Web Services sur RMI impose la génération de classes sauvées +sur disque. +Elle sont construites à la volée et sauvées dans le dossier "./topiagen". + +Ce dossier doit donc se trouver dans le classpath. + +Comment commit (ou rollback) une transaction directement à partir d'un DAO ? +============================================================================ + +Contrairement à ce que l'on pourrait croire aux premiers abords, les méthodes commitTransaction() +et rollbackTransaction() disponibles dans les DAO ne sont pas prévus à cet effet. Il faut toujours +utiliser le contexte pour commit (ou rollback) une transaction. Donc pour le faire à partir d'un DAO : +dao.getContext().commitTransaction() // on récupère le context (transaction sur le DAO) et on commit. +Le principe reste identique pour le rollback. +Pour revenir sur les méthodes commitTransaction() et rollbackTransaction() disponibles sur le DAO, elles +servent de "callback" au moment du commit (ou rollback) de la transaction. Le context se chargera d'appeler +tous les commitTransaction() des DAO, ceci afin de permettre un traitement spécifique au DAO au moment du commit. +Ce traitement peut donc être effectué directement à partir du dao via cette méthode sans passer par le context. + Copied: trunk/src/site/rst/user/model_generation.rst.vm (from rev 3106, trunk/src/site/rst/user/ModelGeneration.rst.vm) =================================================================== --- trunk/src/site/rst/user/model_generation.rst.vm (rev 0) +++ trunk/src/site/rst/user/model_generation.rst.vm 2014-05-15 16:25:44 UTC (rev 3108) @@ -0,0 +1,102 @@ +.. - +.. * #%L +.. * ToPIA :: Persistence +.. * +.. * $Id$ +.. * $HeadURL$ +.. * %% +.. * Copyright (C) 2004 - 2010 CodeLutin +.. * %% +.. * This program is free software: you can redistribute it and/or modify +.. * it under the terms of the GNU Lesser General Public License as +.. * published by the Free Software Foundation, either version 3 of the +.. * License, or (at your option) any later version. +.. * +.. * This program is distributed in the hope that it will be useful, +.. * but WITHOUT ANY WARRANTY; without even the implied warranty of +.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.. * GNU General Lesser Public License for more details. +.. * +.. * You should have received a copy of the GNU General Lesser Public +.. * License along with this program. If not, see +.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. +.. * #L% +.. - + +====================== +Génération des modèles +====================== + + +Le module "topia-persistence" de topia est capable de +générer la persistence à partir d'un modèle UML. + +Nous allons détailler ici comme inclure la génération dans le +cycle de compilation maven. + + +Architecture maven +------------------ + ++---------------------------------+-----------------------------------------+ +| src/main/xmi/mymodel.zargo | exemple de modele UML avec argoUML | ++---------------------------------+-----------------------------------------+ +| src/main/xmi/mymodel.properties | fichier de propriétés attaché au modele | ++---------------------------------|-----------------------------------------+ + + +Configuration du pom.xml +------------------------ + +Pour générer les sources dans la phase "generate-sources" de maven, et utiliser +les sources générées, et faut configurer le pom. + +Plugin Eugene +============= + +:: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>eugene-maven-plugin</artifactId> + <version>${eugeneVersion}</version> + <executions> + <execution> + <id>Generator</id> + <phase>generate-sources</phase> + <configuration> + <inputs>zargo</inputs> + <fullPackagePath>org.company.package</fullPackagePath> + <extractedPackages>org.company.package</extractedPackages> + <templates>org.nuiton.topia.generator.TopiaMetaGenerator</templates> + <defaultPackage>org.company.package</defaultPackage> + </configuration> + <goals> + <goal>generate</goal> + </goals> + </execution> + </executions> + <dependencies> + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>${project.version}</version> + </dependency> + </dependencies> + </plugin> + +Pour plus d'information à propos d'Eugene, merci de consulter le site : +http://doc.nuiton.org/eugene/ + +Dépendances du projet +===================== + +Il faut enfin ajouter "topia-persistence" en dépendance du projet : + +:: + + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>${project.version}</version> + </dependency> Deleted: trunk/src/site/rst/user/start.rst.vm =================================================================== --- trunk/src/site/rst/user/start.rst.vm 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/src/site/rst/user/start.rst.vm 2014-05-15 16:25:44 UTC (rev 3108) @@ -1,248 +0,0 @@ -.. - -.. * #%L -.. * ToPIA :: Persistence -.. * -.. * $Id$ -.. * $HeadURL$ -.. * %% -.. * Copyright (C) 2004 - 2011 CodeLutin -.. * %% -.. * This program is free software: you can redistribute it and/or modify -.. * it under the terms of the GNU Lesser General Public License as -.. * published by the Free Software Foundation, either version 3 of the -.. * License, or (at your option) any later version. -.. * -.. * This program is distributed in the hope that it will be useful, -.. * but WITHOUT ANY WARRANTY; without even the implied warranty of -.. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.. * GNU General Lesser Public License for more details. -.. * -.. * You should have received a copy of the GNU General Lesser Public -.. * License along with this program. If not, see -.. * <http://www.gnu.org/licenses/lgpl-3.0.html>. -.. * #L% -.. - - -================================ -Démarrer un projet ToPIA - Maven -================================ - -Comment démarrer un projet à partir de rien. - -Créer le projet -=============== - -Pour commencer, il faut créer un projet maven en respectant les conventions -habituelles. Partons d'un projet maven vide : - -:: - - mvn archetype:generate -DgroupId=com.masociete -DartifactId=monapplication -DarchetypeArtifactId=maven-archetype-archetype - -Ajoutez un dossier ``src/main/xmi``, c'est ici que nous allons placer le modèle. - -:: - - topia-tutorial - ├── pom.xml - └── src - ├── main - │ ├── java - │ │ └── org - │ │ └── nuiton - │ │ └── topia - │ │ └── tutorial - │ │ └── library - │ ├── resources - │ │ ├── library-config.properties - │ │ └── log4j.properties - │ └── xmi - │ ├── library.properties - │ └── library.zargo - └── test - ├── java - └── resources - -Dans le pom, on ajoute ToPIA en dépendance, et on configure la génération : - -:: - - <properties> - <topiaVersion>${project.version}</topiaVersion> - <eugeneVersion>${eugeneVersion}</eugeneVersion> - </properties> - - <dependencies> - <dependency> - <groupId>org.nuiton.topia</groupId> - <artifactId>topia-persistence</artifactId> - <version>${topiaVersion}</version> - </dependency> - </dependencies> - - - <plugins> - - <!-- ... --> - - <plugin> - <groupId>org.nuiton.eugene</groupId> - <artifactId>eugene-maven-plugin</artifactId> - <version>${eugeneVersion}</version> - <configuration> - <inputs>zargo</inputs> - <resolver>org.nuiton.util.FasterCachedResourceResolver</resolver> - </configuration> - <executions> - <execution> - <id>generate-entities</id> - <phase>generate-sources</phase> - <configuration> - <!-- Corresponding to extracted package from zargo file --> - <fullPackagePath>org.nuiton.topia.tutorial.library</fullPackagePath> - <!-- DefaultPackage used for DAOHelper generation --> - <defaultPackage>org.nuiton.topia.tutorial.library.model</defaultPackage> - <templates> - org.nuiton.topia.generator.TopiaMetaTransformer - </templates> - </configuration> - <goals> - <goal>generate</goal> - </goals> - </execution> - </executions> - </plugin> - - </plugins> - - -Créer le modèle -=============== - -Utiliser ArgoUML pour décrire le modèle ---------------------------------------- - -Avec ArgoUML, créez un nouveau modèle et enregistrez-le dans ``xmi``. Nous -allons créer un modèle simplifié pour une application de gestion de -bibliothèque. - -Nous avons modélisé les entités ``Book`` et ``Author`` avec les champs -appropriés. Faites attention à bien placer les entités dans le bon package, sinon -elles ne seront pas générées. Pour que ToPIA sache que ces classes décrivent -des entités qui ont vocation à être sauvées en base, il faut leur ajouter le -stéréotype ``entity``. - -N'oubliez pas de donner un nom et une version au modèle. - -Les données associées aux éléments du modèle --------------------------------------------- - -Le modeleur n'est pas suffisant pour décrire toute les subtilités du modèle. -Le modèle se voulant indépendant de la plate-forme cible, on ne peut y inclure -directement des notions spécifiques à ToPIA. C'est pourquoi nous allons pouvoir -ajouter ces informations spécifiques via le fichier ``library-config.properties``. - - -C'est prêt ! -============ - -Il suffit de construire l'application avec maven. - -:: - - mvn compile - - -La compilation va provoquer la phase de génération. Si on examine le contenu -de notre dossier target : - -:: - - topia-tutorial - ├── pom.xml - ├── src - │ ├── main - │ │ ├── java - │ │ │ └── org - │ │ │ └── nuiton - │ │ │ └── topia - │ │ │ └── tutorial - │ │ │ └── library - │ │ ├── resources - │ │ │ ├── library-config.properties - │ │ │ └── log4j.properties - │ │ └── xmi - │ │ ├── library.properties - │ │ └── library.zargo - │ └── test - │ ├── java - │ └── resources - └── target - ├── classes - │ ├── library-config.properties - │ ├── log4j.properties - │ └── org - │ └── nuiton - │ └── topia - │ └── tutorial - │ └── library - │ ├── LibraryConfig.class - │ └── model - │ ├── AuthorAbstract.class - │ ├── Author.class - │ ├── AuthorDAOAbstract.class - │ . - │ . - │ . - └── generated-sources - ├── annotations - ├── java - │ └── org - │ └── nuiton - │ └── topia - │ └── tutorial - │ └── library - │ └── model - │ ├── AuthorAbstract.java - │ ├── AuthorDAOAbstract.java - │ ├── AuthorDAOImpl.java - │ ├── AuthorDAO.java - │ ├── AuthorImpl.hbm.xml - │ ├── Author.java - │ ├── BookAbstract.java - │ ├── BookDAOAbstract.java - │ ├── BookDAOImpl.java - │ ├── BookDAO.java - │ ├── BookImpl.hbm.xml - │ ├── BookImpl.java - │ ├── Book.java - │ └── LibraryDAOHelper.java - ├── models - │ ├── library.objectmodel - │ └── library.properties - └── xmi - ├── library.properties - └── library.xmi - - - -On peut voir que ToPIA a généré ``LibraryDAOHelper`` qui va nous permettre de -récupérer les différents DAO et, pour chaque entité de notre modèle : - - * Une interface - * Une classe abstraite, qui implémente déjà tout le contrat - * Une implantation (vide, seulement les constructeurs) - * Un DAO abstrait - * Une implantation du DAO - * Un fichier de mapping hibernate (*.hbm.xml) - -Comme il s'agit d'une phase de compilation, maven va ajouter tout le code généré aux -classpath le code généré sera compilé et lié en même temps que le reste de votre application. -Tous les fichiers .class se retrouveront dans target/classes, dans la suite du processus, on -ne distingue plus le code généré du code utilisateur. - -Par la suite, si vous changez le modèle, tout sera re-généré. À chaque ``clean`` -via maven, tout ce qui a été généré est effacé. Vous pouvez donc re-généré autant -de fois que nécessaire. Attention, Maven ne détecte pas le changement du modèle -si le fichier .zargo a été modifié : il faut donc faire un clean à chaque fois -afin de forcer le re-génération du modèle dans sa dernière version. Modified: trunk/src/site/site_fr.xml =================================================================== --- trunk/src/site/site_fr.xml 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/src/site/site_fr.xml 2014-05-15 16:25:44 UTC (rev 3108) @@ -26,13 +26,13 @@ <project name="ToPIA"> <bannerLeft> - <!--<src alt="ToPIA">${mavenpomSiteCommonResourcesUrl}/images/logos/topia-logo.png</src>--> + <src alt="ToPIA">topia_224_75.png</src> <name>${project.name}</name> <href>index.html</href> </bannerLeft> <bannerRight> - <src>http://www.codelutin.com/images/lutinorange-codelutin.png</src> + <src alt="Code Lutin">lutinorange-codelutin.png</src> <href>http://www.codelutin.com</href> </bannerRight> @@ -46,9 +46,9 @@ <fluidoSkin> <topBarEnabled>true</topBarEnabled> <topBarIcon> - <name>ToPIA</name> - <alt>ToPIA</alt> - <src><!-- TODO Create a 108*20 px icon --></src> + <name>ToPIA : Tools for Portable and Independent Architecture</name> + <alt>ToPIA : Tools for Portable and Independent Architecture</alt> + <src>topia_60_20.png</src> <href>/index.html</href> </topBarIcon> <sideBarEnabled>false</sideBarEnabled> @@ -86,22 +86,17 @@ <link rel="stylesheet" type="text/css" href="${mavenpomSiteCommonResourcesUrl}/css/mavenpom-site.css"/> + + <link rel="stylesheet" type="text/css" href="site.css"/> <!-- XXX AThimel 15/05/2014 May be merged with mavenpom-site.css --> + </head> <breadcrumbs> - <item href="http://doc.nuiton.org/topia" name="${project.name}"/> + <item href="index.html" name="Accueil"/> </breadcrumbs> - <menu name="Documentation" inherit="top"> - <item name="Présentation" href="index.html" /> - <item name="Utilisation" href="user/howto.html" /> - <item name="Génération des modèles" href="user/ModelGeneration.html"/> - <item name="Tag values" href="user/tagvalues.html" /> - <item name="FAQ" href="user/FAQ.html"/> - </menu> - <menu name="Tutoriels" inherit="top"> - <item name="Démarrer avec ToPIA et Maven" href="user/start.html" /> + <item name="Créer un projet ToPIA en partant de rien" href="tutos/from_scratch.html" /> <item name="Commencer à développer avec l'API ToPIA" href="user/start_using_api.html" /> <item name="Étendre le modèle" href="user/extend_model.html" /> <item name="Continuer le développement" href="user/continue_devel.html" /> @@ -109,15 +104,21 @@ <item name="Examples de migration pour le refonte des indexed/ordered" href="user/ordered_vs_indexed_migration.html" /> </menu> - <menu name="Développeurs"> - <item name="Todo" href="devel/Todo.html"/> - <item name="Mapping Hibernate" href="devel/HibernateMapping.html"/> - <item name="Isolation" href="devel/Isolation.html"/> - <item name="Migration de schéma" href="devel/SchemaMigration.html"/> - <item name="Sécurité" href="devel/security.html"/> - <item name="TopiaContextFactory" href="devel/Devel.html"/> - <item name="Projets similaires" href="devel/project.html"/> + <menu name="Documentation" inherit="top"> + <item name="Présentation" href="index.html" /> + <item name="Utilisation" href="user/howto.html" /> + <item name="Génération des modèles" href="user/model_generation.html"/> + <item name="Tag values" href="user/tagvalues.html" /> + <item name="FAQ" href="user/faq.html"/> + <item name="Todo" href="docs/todo.html"/> + <item name="Mapping Hibernate" href="docs/hibernate_mapping.html"/> + <item name="Isolation" href="docs/isolation.html"/> + <item name="Migration de schéma" href="docs/schema_migration.html"/> + <item name="Sécurité" href="docs/security.html"/> + <item name="TopiaContextFactory" href="docs/devel.html"/> + <item name="Projets similaires" href="docs/project.html"/> <item name="Gestion des évènements" href="user/event.html"/> + <item name="Qu'est-ce qu'un cycle de développement en Y ?" href="docs/y_cycle.html"/> </menu> <menu ref="modules"/> @@ -126,6 +127,7 @@ <links> <item name="Nuiton.org" href="https://forge.nuiton.org"/> + <item name="Nuiton.org (ToPIA)" href="https://forge.nuiton.org/projects/topia"/> <item name="Code Lutin" href="http://www.codelutin.com"/> <item name="Libre-Entreprise" href="http://www.libre-entreprise.org/"/> </links> Modified: trunk/topia-service-csv/pom.xml =================================================================== --- trunk/topia-service-csv/pom.xml 2014-05-15 16:19:34 UTC (rev 3107) +++ trunk/topia-service-csv/pom.xml 2014-05-15 16:25:44 UTC (rev 3108) @@ -35,8 +35,8 @@ <groupId>org.nuiton.topia</groupId> <artifactId>topia-service-csv</artifactId> - <name>ToPIA :: Service Csv</name> - <description>To import or export with csv format</description> + <name>ToPIA :: Service CSV</name> + <description>To import or export with CSV format</description> <properties> <!-- Post Release configuration -->