How to

30 Jan 2009

      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 persistée par Topia. D'autre stérotypes (extern, service, ...) sont
disponiples mais ne sont pas présentés.

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
attribut>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();

Julien

Julien Ruchaud

tags

participants (1)