Author: ruchaud Date: 2008-12-19 13:23:10 +0000 (Fri, 19 Dec 2008) New Revision: 1283 Added: topia/trunk/topia-persistence/src/site/rst/howto.rst Log: Document pour la prise en main de Topia Added: topia/trunk/topia-persistence/src/site/rst/howto.rst =================================================================== --- topia/trunk/topia-persistence/src/site/rst/howto.rst (rev 0) +++ topia/trunk/topia-persistence/src/site/rst/howto.rst 2008-12-19 13:23:10 UTC (rev 1283) @@ -0,0 +1,244 @@ +How to +====== + +Ce document a pour objectif de prendre en main le framework Topia. Le document +est constitué de 4 parties, la modèlisation, la génération, la configuration et +l'utilisation. + +Modélisation +------------ + +La première étape constiste à réaliser le modèle UML soit avec Argouml +(http://argouml.tigris.org) soit avec Poséidon (http://www.gentleware.com). + +Le stérotype «entity» sur les classes permet de préciser que la classe est +persister par Topia. D'autre stérotypes (extern, service, ...) sont disponiples +mais ne sont pas présenté. + +Le fichier de modélisation peut être compléter par un fichier de configuration +nommé <nom fichier modélisation>.properties. Il contient des informations +techniques propres au librairie utilisé par Topia. + +Exemple : + +# Précise comment est mappé un type +# model.tagvalue.<type java>=<type base de donnée> +model.tagvalue.java.lang.String=text + +# Précise le schema de la base de données par défaut +# model.tagvalue.dbSchema=<nom schéma> +model.tagvalue.dbSchema=test + +# Précise l'entête de l'ensemble des fichiers générés +# model.tagvalue.copyright=<valeur> +model.tagvalue.copyright=/* *##%\n Copyright (C) 2007 Code Lutin\n *##% */ + +# Force le chargement d'un attribut +# <nom paquetage>.<nom entité>.attribute.<nom attribut>.tagvalue.lazy=false +org.codelutin.Person.attribute.association.tagvalue.lazy=false + +Génération +---------- + +La génération des fichiers Topia se font par l'utilisation d'un plugin maven. +Le plugin est disponnible sur le repository maven de Code Lutin à l'adresse +suivante http://lutinbuilder.labs.libre-entreprise.org/maven2. + +Configuration du plugin maven : + +<plugin> + <groupId>org.codelutin</groupId> + <artifactId>maven-generator-plugin</artifactId> + <version>0.63</version> + <executions> + <execution> + <phase>process-sources</phase> + <!--Configuration of model generator--> + <configuration> + <addCompileDirectory>true</addCompileDirectory> + <srcDirZuml>${maven.src.dir}/main/xmi</srcDirZuml> + <srcXmiDest>${maven.gen.dir}/xmi/</srcXmiDest> + <srcGenDest>${maven.gen.dir}/objectmodel/</srcGenDest> + <includes>**/*.objectmodel</includes> + <templates>org.codelutin.topia.generator.TopiaMetaGenerator</templates> + <destDirGen>${maven.gen.dir}/java</destDirGen> + <defaultPackage>org.codelutin</defaultPackage> + <extractedPackages>org.codelutin</extractedPackages> + </configuration> + <goals> + <goal>zargo2xmi</goal> + <goal>xmi2objectmodel</goal> + <goal>generate</goal> + </goals> + </execution> + </executions> + <dependencies> + <dependency> + <groupId>org.codelutin.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>2.1.0-SNAPSHOT</version> + <scope>compile</scope> + </dependency> + </dependencies> +</plugin> + +Le plugin utilise lutin generator avec les templates de génération de Topia, le +fichier argouml ou poséidon doit se trouver dans le répertoire +${maven.src.dir}/main/xmi. Les fichiers sont générés dans le répertoire +${maven.gen.dir}/java. Il faut préciser au plugin les paquetages à traiter avec +le defaultPackage et extractedPackages. + +Ajout dans des dépendances de Topia pour la compilation des fichiers générés : + +<dependency> + <groupId>org.codelutin.topia</groupId> + <artifactId>topia-persistence</artifactId> + <version>2.1.1</version> + <scope>compile</scope> +</dependency> + +Pour une classe modélisé, nous retrouvons 6 fichiers : + * Une interface + * Une classe abstraite + * Une implantation + * Une configuration hibernate + * Un DAO abstrait + * Une implantation du DAO + +Une classe Helper est aussi générée, permettant l'accès à l'ensemble des DAO. + +Configuration +------------- + +Un fichier contenant les informations de connexion à la base de données et de +configuration de Topia doit être créé au niveau des ressources du projet. + +Exemple : + +# Permet la création, la modification, ou pas automatique de la base de données +# [create | update | none] +hibernate.hbm2ddl.auto=update + +# Affichage des requêtes dans la console +# [true | false] +hibernate.show_sql=false + +# Permet de préciser les classes à persister +topia.persistence.classes=org.codelutin.Person, org.codelutin.Pet + +# Informations de connection : + +# Dialect à utiliser +hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect + +# Driver JDBC +hibernate.connection.driver_class=org.postgresql.Driver + +# URL de connection +hibernate.connection.url=jdbc:postgresql://localhost/mydb + +# Login de l'utilisateur qui se connecte +hibernate.connection.username=user + +# Mot de passe de l'utilisateur +hibernate.connection.password=xxxx + +Utilisation +----------- + +Implantation des méthodes +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Si des méthodes ont été définis dans le modèle de données il faut créer +l'implantation correspondante. Le paquetage doit porter le même nom que celui de +la génération. + +Gestion des transactions +~~~~~~~~~~~~~~~~~~~~~~~~ + +>>> Properties conf = Resource.getConfigProperties("/TopiaContext.properties"); + +Permet de charger un fichier contenant les informations de connexion à la base +et de configuration de Topia. + +>>> TopiaContext rootContext = TopiaContextFactory.getContext(conf); + +Récupère le context de départ pour la création de sous context pour la gestion +des entités. + +>>> TopiaContext transaction = rootContext.beginTransaction(); + +Création d'un sous context pour la gestion des entités. + +>>> transaction.commitTransaction(); + +Validation de l'état du context, les modifications des entités sont reportées +dans la base de données. + +>>> transaction.rollBackTransaction(); + +Invalidation de l'état du context, les modifications des entités ne sont pas +reportées dans la base de données. + +>>> transaction.closeContext(); + +Relâche la connexion JDBC d'un sous context et de ses sous contexts sans +validation de l'état des contexts. + +>>> rootContext.closeContext(); + +Relâche l'ensemble des ressources (cache, pools, ...) et relâche la connexion +JDBC des sous contexts avec validation de l'état des contexts. + +Manipulation des entités +~~~~~~~~~~~~~~~~~~~~~~~~ + +>>> PersonDAO personDAO = <nom modele>Helper.getPersonDAO(transaction); + +Récupération d'un DAO pour accéder à une entité. + +>>> Person person = personDAO.findByTopiaId(id); + +Les méthodes find permettent de récupérer une ou plusieurs selon différents +critères. + +>>> person.setName("tutu"); + +Manipulation de l'entité par les getters et setters. + +>>> Person person = personDAO.create(); + +Création d'une entité. Si vous utilisez l'instanciation classique java avec le +new, l'entité n'est pas persistée. + +>>> personDAO.update(person); + +Modification d'un entité. + +>>> personDAO.delete(person); + +Suppression d'une entité. + +Exemple +~~~~~~~ + +Properties conf = Resource.getConfigProperties("/TopiaContext.properties"); +TopiaContext rootContext = TopiaContextFactory.getContext(conf); + +TopiaContext transaction = rootContext.beginTransaction(); +PersonDAO personDAO = ModelHelper.getPersonDAO(transaction); + +Person person = personDAO.create(); +person.set...(...); +person.set...(...); +personDAO.update(person); + +person.get...(...); +person.get...(...); + +personDAO.delete(person); + +transaction.commitTransaction(); +transaction.closeContext(); + +rootContext.closeContext();