September 2009 - Bonzoms-commits - mailman.cloud.codelutin.com

r72 - in trunk: bonzoms-business/src src/site src/site/resources/schemas src/site/rst src/site/rst/developper src/site/rst/user
by jcouteau＠users.chorem.org 25 Sep '09

25 Sep '09

Author: jcouteau Date: 2009-09-25 11:53:35 +0200 (Fri, 25 Sep 2009) New Revision: 72 Added: trunk/src/site/resources/schemas/ClassDiagram_DTO.png trunk/src/site/resources/schemas/ClassDiagram_Entities.png trunk/src/site/resources/schemas/ClassDiagram_Entities_generation.png trunk/src/site/resources/schemas/ClassDiagram_Services.png trunk/src/site/resources/schemas/ImplDiagram_Entities.png trunk/src/site/resources/schemas/UseCases_Bonzoms.png trunk/src/site/rst/developper/choreg.rst trunk/src/site/rst/developper/organisation.rst trunk/src/site/rst/developper/topia.rst trunk/src/site/rst/presentation.rst trunk/src/site/rst/specifications.rst trunk/src/site/rst/user/ trunk/src/site/rst/user/export.rst trunk/src/site/rst/user/faq.rst trunk/src/site/rst/user/relations.rst trunk/src/site/rst/user/services.rst Removed: trunk/bonzoms-business/src/site/ Modified: trunk/src/site/rst/index.rst trunk/src/site/site.xml Log: Fusion between business and ui sites on root maven-site to have more visibility Added: trunk/src/site/resources/schemas/ClassDiagram_DTO.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/schemas/ClassDiagram_DTO.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/schemas/ClassDiagram_Entities.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/schemas/ClassDiagram_Entities.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/schemas/ClassDiagram_Entities_generation.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/schemas/ClassDiagram_Entities_generation.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/schemas/ClassDiagram_Services.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/schemas/ClassDiagram_Services.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/schemas/ImplDiagram_Entities.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/schemas/ImplDiagram_Entities.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/schemas/UseCases_Bonzoms.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/schemas/UseCases_Bonzoms.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/rst/developper/choreg.rst =================================================================== --- trunk/src/site/rst/developper/choreg.rst (rev 0) +++ trunk/src/site/rst/developper/choreg.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,5 @@ +Choreg + +- Deploiement en stand-alone : utilisation ServletContextListener + +- Implementation des services pour ChoReg (heritage generique) Added: trunk/src/site/rst/developper/organisation.rst =================================================================== --- trunk/src/site/rst/developper/organisation.rst (rev 0) +++ trunk/src/site/rst/developper/organisation.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,113 @@ +Organisation du projet +====================== + +:Author: $Author: fdesbois $ +:Version: 1.0 +:Revision: $Revision: 47 $ +:Date: $Date: 2009-08-19 19:01:06 +0200 (mer, 19 ao� 2009) $ + +*Created by fdesbois on 2009-08-19* + +Le projet Bonzoms utilise Maven pour gérer les dépendances et générer le code via ToPIA. ToPIA permet ainsi de générer les entités, les dtos et les services. +Il y a 7 packages différents dans Bonzoms-business. + +org.chorem.bonzoms +------------------ + +Package principal contenant l'exception de base de Bonzoms : BonzomsException qui est renvoyé par tous les services de Bonzoms. Ce package contient également +la classe ContextUtilBonzoms qui permet de gérer de façon statique le contexte principal pour ToPIA. Ainsi chaque service demande au ContextUtilBonzoms le contexte +root pour ouvrir une nouvelle transaction :: + + TopiaContext transaction = ContextUtilBonzoms.getRootContext().beginTransaction(); + +L'initialisation du contexte root via le fichier de propriétés Topia (ContextBonzoms.properties) est automatique si elle n'a pas déjà été effectuée. Cependant +il est nécessaire d'appeler explicitement la méthode **ContextUtilBonzoms.closeRootContext()** à la fermeture de l'application. + +Le package principal contient une classe permettant de charger les services via ChoReg si ce dernier est présent dans le ClassLoader. (voir documentation sur `choreg`_ ). + +org.chorem.bonzoms.business +--------------------------- + +Ce package contient des classes d'aide (Helper) utiliser pour factoriser un comportement commun entre plusieurs méthodes de services (ex : createUpdatePartyRole). +Ainsi la transaction courante du service est transmis au Helper sans fermeture ni réouverture. Ceci permet d'éviter les communications entre deux services distincts. +Chaque transaction est ouverte et fermer (commit et rollback également) localement à chaque méthode de service. + +org.chorem.bonzoms.enums +------------------------ + +Complément au package précédent, ce package permet de regrouper les différentes valeurs des types manipulés dans Bonzoms : RelationshipType, PartyType, +PartyRoleType et ContactType. + +org.chorem.bonzoms.export +------------------------- + +Gestion des exports de Bonzoms. Que ce soit pour exporter en fichier XML ou utiliser les conversions pour ChoReg. + +org.chorem.bonzoms.impl +----------------------- + +Package regroupant l'implémentation des interfaces des services générés par ToPIA (dans le package org.chorem.bonzoms.services). Chaque service utilise le +root context de ToPIA chargé via la classe ContextUtilBonzoms. Les transactions sont locales aux méthodes des services. + +Implémentation type :: + + public void serviceMethod(params...) throws BonzomsException { + TopiaContext transaction = null; + try { + transaction = context.beginTransaction(); // context root provenant de ContextUtilBonzoms + + // traitement Topia avec utilisation des DAO ou des Helper + + transaction.closeContext(); + } catch (Exception eee) { + ContextUtilBonzoms.serviceException(transaction, "Error", eee); + } + return results; + } + +La majorité des méthodes de services renvoient une BonzomsException qui encapsule généralement l'erreur provoqué dans le service. Cette erreur peut provenir +de Topia ou d'un Helper. Les types d'exceptions connus sont : TopiaException, IllegalArgumentException, EntityException et ConvertException. Un utilitaire d'aide +est principalement utiliser pour faciliter la gestion et le renvoi d'erreurs : ServiceHelper provenant du module chorem-commons de ChoReg. Cette classe +permet d'effectuer les opérations principales : createUpdate, delete, get, getOrCreate, ... tout en gérant et renvoyant les exceptions éventuelles. Il n'est +donc pas nécessaire de gérer les erreurs dans les services, il suffit de les renvoyer via une BonzomsException à l'utilisateur du service. Ainsi l'erreur +pour l'utilisateur sera assez précise pour lui permettre de corriger son comportement. Dans les cas de gestions complexes, il est possible de réencapsulé +directement un nouvelle exception. + +Exemple :: + + if (param == null) { + ContextUtilBonzoms.serviceException(transaction, "unable to use param for this method", new IllegalArgumentException("Argument param null")); + } + +ou plus simplement :: + + if (param == null) { + throw new BonzomsException("Illegal parameter param null for this method"); + } + +L'avantage d'utiliser la méthode serviceException de ContextUtilBonzoms, c'est la gestion des transactions en cas d'échec. En effet la transaction si elle +existe et est ouverte sera annulé (rollback) et fermé (closeContext). + +org.chorem.bonzoms.persistence +------------------------------ + +Package où se situe les entités générés par ToPIA depuis le modèle expliquer dans les `specifications entites`_ . Ce package contient également les surcharges de certaines +entités ou DAO (voir documentation sur la `generation avec ToPIA`_ ) + +.. _specifications entites: ../specifications.html#entites + +.. _generation avec ToPIA: topia.html + +org.chorem.bonzoms.dto +---------------------- + +Package où se situe les dtos générés par ToPIA depuis le modèle expliquer dans les `specifications DTO`_ . + +.. _specifications DTO: ../specifications.html#dto + +org.chorem.bonzoms.services +--------------------------- + +Package où se situe les services générés par ToPIA depuis le modèle expliquer dans les `specifications services`_ . + +.. _specifications services: ../specifications.html#services Added: trunk/src/site/rst/developper/topia.rst =================================================================== --- trunk/src/site/rst/developper/topia.rst (rev 0) +++ trunk/src/site/rst/developper/topia.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,232 @@ +Génération avec ToPIA +===================== + +:Author: $Author: fdesbois $ +:Version: 1.0 +:Revision: $Revision: 47 $ +:Date: $Date: 2009-08-19 19:01:06 +0200 (Wed, 19 Aug 2009) $ + +*Created by fdesbois on 2009-08-19* + +Topia est le framework principal pour le module Bonzoms-business. Il permet de générer les entités, les daos, les dtos et les services. Les transactions topia +sont également utilisés pour permettre de se connecter à une base de données pour la persistance des entités. Ainsi les services utilisent les daos pour +ajouter/modifier/supprimer et sélectionner les entités persistantes de la base de données. Cette dernière est configurable dans le fichier ContextBonzoms.properties :: + + hibernate.hbm2ddl.auto=update + hibernate.show_sql=false + + hibernate.dialect=org.hibernate.dialect.H2Dialect + hibernate.connection.username=sa + hibernate.connection.password= + hibernate.connection.driver_class=org.h2.Driver + hibernate.connection.url=jdbc:h2:file:~/h2data/bonzoms + +Actuellement, le fichier de propriétés par défaut utilise une base de données de type H2. Il est possible d'utiliser un autre fichier de propriétés au moment +de l'exécution de l'application. Ce fichier devra s'appeler **ContextBonzoms.properties** et être placé dans le dossier /etc de votre machine. + +.. _maven-eugene-plugin: http://maven-site.nuiton.org/eugene/maven-eugene-plugin/index.html + +Voici la configuration du plugin maven pour la génération des classes javas (`maven-eugene-plugin`_ ) :: + + <plugin> + <groupId>org.nuiton.eugene</groupId> + <artifactId>maven-eugene-plugin</artifactId> + <version>${generator.version}</version> + <executions> + <execution> + <phase>generate-sources</phase> +  + <configuration> + <addCompileDirectory>true</addCompileDirectory> + <includes>**/*.objectmodel</includes> + <templates>org.nuiton.topia.generator.TopiaMetaGenerator,org.nuiton.topia.generator.BeanGenerator, + org.nuiton.topia.generator.TopiaApplicationServiceMetaGenerator</templates> + <defaultPackage>${project.groupId}</defaultPackage> + <fullPackagePath>${project.groupId}</fullPackagePath> + <extractedPackages>${project.groupId}</extractedPackages> + </configuration> + <goals> + <goal>zargo2xmi</goal> + <goal>xmi2objectmodel</goal> + <goal>generate</goal> + </goals> + </execution> + </executions> + <dependencies> +  + <dependency> + <groupId>org.nuiton.topia</groupId> + <artifactId>topia-soa</artifactId> + <version>${topia.version}</version> + <exclusions> + <exclusion> + <groupId>org.codehaus.xfire</groupId> + <artifactId>xfire-java5</artifactId> + </exclusion> + </exclusions> + </dependency> + </dependencies> + </plugin> + +Comme vous pouvez le constater dans les *goals*, trois étapes de génération sont effectuées : + +- zargo2xmi : Extraction du fichier XMI du modèle zargo (créer via `ArgoUML 0.28`_ ). Le fichier zargo est placé dans le dossier *src/main/xmi*. + +- xmi2objectmodel : Création d'un fichier *objectmodel* depuis le fichier xmi (utilisation de la librairie `EUGene`_ ). Ce fichier est généré dans le dossier + *target/generated-sources/models* + +- generate : Génération via ToPIA des fichiers pour les entités, les daos, les dtos et les services. Les fichiers sont générés dans le dossier + *target/generated-sources/java*. Ce sont les trois générateurs utilisés qui permettent les différentes générations. + +.. _ArgoUML 0.28: http://argouml.tigris.org/ + +.. _EUGene: http://maven-site.nuiton.org/eugene/eugene/index.html + +Note + L'exclusion de xfire évite un conflit lors de l'utilisation de topia-soa. + +TopiaMetaGenerator +------------------ + +Le TopiaMetaGenerator inclus dans ToPIA-persistence permet la génération des entités et daos. Pour chaque entité du modèle avec le stéréotype **<<entity>>** 7 fichiers sont générés. +Prenons l'exemple pour l'entité nommé *ContactEntity* : + +- ContactEntity.java : Interface représentant l'entité. Elle comprend les attributs et méthodes décrits dans le modèle UML + les accesseurs générés pour chaque attribut. + Elle comprend aussi des constantes statiques représentant le nom des attributs existants. Pour ContactEntity nous avons un seul champs, le champs *contact*. + +- ContactEntityAbstract.java : Classe abstraite implémentant les méthodes générés dans l'interface. Seul les méthodes non écrite dans le modèle UML sont implémentés. + +- ContactEntityImpl.java : Classe héritant de la classe abstraite précédente et implémentant l'interface de l'entité. Cette classe est généré uniquement si aucune + méthodes sont écrites dans l'entité dans le modèle UML. En effet ces méthodes devront être implémentés par le développeur et la classe devra être créé dans le + package **org.chorem.bonzoms.persistence**. (Vous pouvez trouver un exemple pour l'entité *PartyEntity* -> PartyEntityImpl). + +- ContactEntityImpl.hbm.xml : Fichier de mapping hibernate pour l'entité. + +- ContactEntityDAO.java : Final class du DAO (Data Access Object) pour manipulation des entités (create, update, delete, find, findAll, ...). Hérite de ContactEntityDAOImpl. + +- ContactEntityDAOAbstract.java : Classe abstraite du DAO avec implémentation des méthodes spécifiques à l'entité. + +- ContactEntityDAOImpl.java : Herite de la classe abstraite et permet la surcharge ou l'ajout de méthodes pour le DAO. Cette classe est vide par défaut et peut + ne pas être généré si l'entité sur le diagramme possède des méthodes avec le stéréotype **<<dao>>** + +La génération respecte l'héritage. Ainsi il est possible de manipuler les DAO d'une classe père pour trouver des fils (Ex : PartyEntityDAO). + +Voici le diagramme qui permet de générer les entités de Bonzoms : + +.. image:: ../schemas/ClassDiagram_Entities_generation.png + :alt: Modèle pour génération des entités + :align: center + +Classes vertes : pas de génération des classes DAOImpl et Impl + +Classes jaunes : pas de génération de la classe Impl + +Classes roses : pas de génération de la classe DAOImpl + +BeanGenerator +------------- + +Le BeanGenerator permet la génération des DTO. Les DTO sont générés comme des Beans. Pour garder une cohérence avec les entités, il est possible d'utiliser les +dépendances UML entre un DTO et son entité. Ainsi le DTO aura directement tous les attributs primitifs (double, int, String, Date, ...) de l'entité qu'il dépend. +Il est possible également de rendre dépendant un DTO de plusieurs entités (principalement utilisé pour l'héritage). + +Des utilitaires de Chorem-commons sont utilisés pour faciliter la conversion des DTO en Entité et vice et versa. Via le ServiceHelper, les ajout/modifications +sur une entité se font via une Map de propriétés qui sera passer aux DAO pour ToPIA. Cette Map reprend les attributs de l'entité. Pour la conversion des entités en DTO, +l'utilitaire Convert est utilisé. Ainsi les valeurs des attributs communs aux deux (DTO et entité) comme l'indique la dépendance se feront automatiquement. Les +attributs rajoutés spécifiquement au DTO sont à la charge du développeur. + +Exemple ajout/modification via ServiceHelper :: + + ContactEntity entity = null; + + if (contact != null && contact.getContact() != null && !contact.getContact().isEmpty()) { + + // Helper pour la creation ou la recuperation de l'entite Type + ContactType contactType = + BonzomsTypeHelper.getTypeEntity(contact.getType(), ContactType.class, transaction, log); + + TopiaDAO dao = null; + + Map<String, Object> existParams = new HashMap<String, Object>(); // Attributs pour l'existence d'un contact dans le cas d'un ajout (id = null) + Map<String, Object> saveParams = new HashMap<String, Object>(); // Attributs pour la sauvegarde de l'entité (ajout/modification) + + existParams.put(ContactEntity.CONTACT, contact.getContact()); + existParams.put(ContactEntity.CONTACT_TYPE, contactType); + + if (contactType.isAddress()) { // Particularité pour l'heritage (AddressEntity extends ContactEntity) + if (log.isDebugEnabled()) { + log.debug("ADDRESS contact"); + } + existParams.put(AddressEntity.CONTACT2,contact.getContact2()); + + CityEntity city = createOrGetCity(contact, transaction, log); + + existParams.put(AddressEntity.CITY_ENTITY,city); + + dao = BonzomsModelDAOHelper.getAddressEntityDAO(transaction); + } else { + dao = BonzomsModelDAOHelper.getContactEntityDAO(transaction); + } + + saveParams = new HashMap<String, Object>(existParams); + + // Appel du ServiceHelper + entity = ServiceHelper.createUpdateEntity(dao,contact.getId(),existParams,saveParams,log); + + // Mise a jour de l'id dans le DTO Contact via une conversion incluse dans le ContextUtilBonzoms + contact.setId(ContextUtilBonzoms.convertId(entity.getTopiaId())); + } else { + throw new IllegalArgumentException("Null Contact contact. Can't create or update null object or with an empty contact attribute"); + } + +Exemple conversion Entité en DTO via Convert :: + + boolean address = entity.getContactType().isAddress(); + // Important, les attributs d'une AddressEntity ne sont pas les memes que ceux d'un ContactEntity + Class interfaceClass = address ? AddressEntity.class : ContactEntity.class; + Contact result = Convert.toDTO(entity,interfaceClass,Contact.class); + + // Specific DTO attributes + result.setType(entity.getContactType().getName()); + result.setId(ContextUtilBonzoms.convertId(entity.getTopiaId())); + result.setEditable(false); // Used for Web Interface + if (address) { + CityEntity cityEntity = ((AddressEntity)entity).getCityEntity(); + if (cityEntity != null) { + result.setCity(cityEntity.getCity()); + result.setPostalCode(cityEntity.getPostalCode()); + result.setCountry(cityEntity.getCountryEntity().getCountry()); + } + } + +La conversion de l'identifiant se fait également via l'utilitaire Convert de Chorem-commons. Dans Bonzoms, on souhaite avoir un identifiant plus simple pour +les DTO afin de rendre plus lisible cet identifiant via Bonzoms-ui (l'identifiant visible dans l'url). ContextUtilBonzoms utilise la méthode *Convert.toWebId* +pour convertir un TopiaId en identifiant simple d'utilisation dans Bonzoms-ui (et donc dans Tapestry). La conversion inverse est automatique dans les méthodes +de ServiceHelper. Une contrainte apparaît, l'identifiant webId ne contient pas le nom de l'entité persistante (comme un TopiaId), ce qui implique l'utilisation +du DAO spécique à l'entité que l'on manipule. Il n'est plus possible d'utiliser un DAO générique pour le cas d'un héritage. Dans l'exemple précédent, la manipulation +d'une AddressEntity impose l'utilisation du AddressEntityDAO et non pas son DAO père ContactEntityDAO. Ceci afin de retrouver le bon TopiaId correspondant à +l'identifiant du DTO. + +Ex ids :: + + webId = K1250241238968K0.6667881086684239 + topiaId = org.chorem.bonzoms.persistence.AddressEntity#1250241238968#0.6667881086684239 + +Voici le diagramme qui permet de générer les dtos de Bonzoms (Entités en Vert et DTO en Jaune) : + +.. image:: ../schemas/ClassDiagram_DTO.png + :alt: Modèle pour la génération des DTO + :align: center + + +TopiaApplicationServiceMetaGenerator +------------------------------------ + +Le TopiaApplicationServiceMetaGenerator provient de ToPIA-SOA qui permet la génération d'interfaces comme services. Le protocole de communication peut être +définit dans le fichier de configuration ContextBonzoms.properties. Pour le moment aucun tests n'a été fait pour permettre l'utilisation des services sur +un serveur distant (via RMI, XML-RPC ou SOAP). La génération est cependant effectuer pour une futur implémentation de la gestion distante. Les interfaces +doivent avoir le stéréotype **<<service>>**. + +Détails des `services`_ (inclut le diagramme permettant la génération). + +.. _services: ../user/services.html Modified: trunk/src/site/rst/index.rst =================================================================== --- trunk/src/site/rst/index.rst 2009-09-25 09:06:12 UTC (rev 71) +++ trunk/src/site/rst/index.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -1,26 +1,22 @@ -Bonzoms Web Interface -===================== +Bonzoms +======= -Ce module correspond à l'interface utilisateur de l'application Bonzoms. Cette interface a été réalisé grâce au framework Apache Tapestry. Il s'agit d'une interface -web basé sur une architecture à base de composants. Aucune configuration XML n'est nécessaire. Il est primordial de bien connaître Tapestry pour pouvoir développer -sur ce module. +Bonzoms est une application permettant la gestion des personnes, sociétés, leurs +relations, rôles et contacts. -Vous trouverez sur les pages de ce module : +L'application est composée de deux modules distincts : un module de présentation +et un module de services comprenant toutes les opérations métier. -* Documentation utilisateur +Sur ce site vous pouvez retrouver toute la documentation de ce projet : - - Introduction au guide utilisateur - - Gestion des personnes : ajout/modification/suppression - - Gestion des sociétés : ajout/modification/suppression, gestion des services, gestion des employés - - Gestion des contacts : pour une personne ou une société - - Gestion des rôles et relations : pour une personne, une société ou un autre tiers (service, association, client, ...) +Documentation utilisateur (à venir), documentation d'utilisation du module de +services, documentation développeur pour les deux modules composant l'application +bonzoms. -* Documentation développeur +A noter que l'application Bonzoms peut-être utilisée seule, mis qu'elle révèle +tout son potentiel lorsqu'elle est utilisée avec d'autres applications du projet +Chorem_ ( Billy_ ou Cash_ par exemple) - - Layout et Gestion des erreurs : utilisation des composants Layout et Warnings - - Composants pour Tapestry : composants liés à l'application (ContactComponent, RoleComponent, RelationComponent) ou composants graphiques (BlockManager, WindowLink) - - Bonnes pratiques avec Tapestry : comment Tapestry est utilisé pour le rendu des données depuis Bonzoms-business et évènementiel en Tapestry - - Todo : fonctionnalités intéressantes non implémentées - - Services : utilisation des services de Bonzoms-business via le AppModule de Tapestry (voir `Tapestry-IoC`_ ) - -.. _Tapestry-IoC: http://tapestry.apache.org/tapestry5.1/tapestry-ioc/module.html \ No newline at end of file +.. _Chorem: http://chorem.org/ +.. _Billy: http://maven-site.chorem.org/billy/ +.. _Cash: http://maven-site.chorem.org/cash/ \ No newline at end of file Added: trunk/src/site/rst/presentation.rst =================================================================== --- trunk/src/site/rst/presentation.rst (rev 0) +++ trunk/src/site/rst/presentation.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,45 @@ +Présentation de Bonzoms +======================= + +:Author: $Author: fdesbois $ +:Version: 1.0 +:Revision: $Revision: 47 $ +:Date: $Date: 2009-08-19 19:01:06 +0200 (mer, 19 ao� 2009) $ + +*Created by fdesbois on 2009-08-19* + +Bonzoms est une application permettant de regrouper l'ensemble des acteurs d'une société et leurs rôles et relations. Il peut servir également d'annuaire +et à l'avenir de CRM. + +Bonzoms fournit l'implémentation d'un modèle solide de gestion des personnes et contacts dans une société. + +Ainsi bonzoms permet : + +- La manipulation des personnes acteurs dans une société (employés, clients, fournisseurs, contacts externes, partenaires, ...) + +- La manipulation des sociétés et groupes auxquels appartiennent ces personnes. + +- Les contacts des personnes et de leurs sociétés (email, adresses, telephones, ...) + +- Les rôles et relations entre les différentes personnes et/ou sociétés, groupes, etc... + +- L'export de ses données suivant le standard Oasis CIQ + +.. image:: schemas/UseCases_Bonzoms.png + :alt: Cas d'utilisations + :align: center + +Les termes suivant seront régulièrement utilisés, que ce soit dans le code source de l'application ou dans la documentation : + +- party : terme désignant un tiers, c'est à dire un acteur que ce soit une personne, une société, un service, une association, ... + +- partyRole : terme désignant le rôle d'un tiers (client, chef de projet, directeur général, maison mère, ...) + +- relationship : relation entre deux rôles et donc entre les deux acteurs de la relation + +Maintenant que les notions de base et le principe de Bonzoms sont exposés, vous pouvez lire le document de `specifications`_ comprenant les diagrammes de classes +de l'application. Sinon vous pouvez vous orienter directement vers la description des services proposés par l'application : `ici`_ . + +.. _specifications: specifications.html + +.. _ici: user/services.html Added: trunk/src/site/rst/specifications.rst =================================================================== --- trunk/src/site/rst/specifications.rst (rev 0) +++ trunk/src/site/rst/specifications.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,81 @@ +Spécifications de Bonzoms +========================= + +:Author: $Author: fdesbois $ +:Version: 1.0 +:Revision: $Revision: 51 $ +:Date: $Date: 2009-08-21 10:34:14 +0200 (ven, 21 ao� 2009) $ + +*Created by fdesbois on 2009-08-19* + +Ce document permet de décrire en détail les données manipulés par Bonzoms et proposés sous la forme de services pour d'autres applications ou son interface web Bonzoms-ui. + +Entites +------- + +La classe principale est la classe PartyEntity correspondant à un tiers qui peut être de plusieurs types différents spécifiés par PartyType. Deux classes filles +héritent de PartyEntity, l'une correspondant à une personne, PersonEntity et l'autre à un groupe de personnes, GroupPersonEntity. Les sociétés sont en fait +considérés comme des groupes de personnes avec pour type *ORGANIZATION*. Ce modèle ne propose pas de détails particuliers pour une société ou un groupe de personnes +en général, seul le nom est utiliser pour l'identifier. Chaque PartyEntity est composés de plusieurs PartyRoleEntity correspondants aux rôles des personnes ou +groupes de personnes. Chaque rôle à un type définit par PartyRoleType et deux dates correspondants à la période sur lequel le rôle est conduit par le tiers. Il +est bien évidemment possible que la date de fin (thruDate) soit vide pour montrer que le rôle est actuellement utilisé par le tiers. Les PartyRoleEntity permettent de +déterminer les RelationshipEntity d'un tiers. Ainsi une RelationshipEntity possède deux rôles, un "from" (rôle fils) et un "to" (rôle parent). Pour simplifier ces termes, +le rôle "to" sert à indiquer le rôle qui est utilisé dans de nombreuses relations du même type. Par exemple, pour une société, les employés auront le rôle "from" +*EMPLOYEE* et la société le rôle "to" conteneur parent *EMPLOYER* pour une relation de type *EMPLOYMENT*. (Voir la documentation sur les `relations`_ existantes pour plus +de détails sur les différentes possibilités). Une PartyEntity a également plusieurs ContactEntity définis également par un ContactType. A savoir que le diagramme +n'indique pas l'héritage entre tous les types (RelationshipType, ContactType, PartyRoleType, PartyType) avec une même entité TypeEntity. Le ContactEntity est donc +défini par son type mais peut être considéré comme une AddressEntity pour plus de paramètres. Notamment une AddressEntity est lié à une CityEntity elle même lié +à une CountryEntity pour permettre la sauvegarde des villes et pays existants. + +.. _relations: user/relations.html + +.. image:: schemas/ClassDiagram_Entities.png + :alt: Modèle du domaine - Entités de Bonzoms + :align: center + +DTO +--- + +Les DTO (Data Transfert Object) de l'application Bonzoms sont des simplifications du modèle d'entité (ou des ajouts au modèle) pour permettre une manipulation plus +simple au niveau des services ou de l'interface web de l'application. Ainsi des dépendances permettent de repérer les liaisons entre les DTO (en jaune) et +les entités (en vert). La dépendance est définie de la manière suivante : tous les attributs de l'entité sont copiés dans ceux du DTO. Ainsi certaines simplifications +apparaissent : un seul DTO Contact permet d'identifier un ContactEntity ou une AddressEntity. Ce DTO comprend également les attributs définissant le CityEntity et le CountryEntity +dans le cas d'une adresse. L'héritage des partys est par contre garder de la même manière que les entités. Quant aux relations, deux différents DTO existent : + +- Relationship : relation entre deux partys sans prise en compte des rôles. + +- RelationshipRoles : relation entre deux rôles, eux même liés aux partys (de la même manière que les entités). + +Pourquoi cette différence ? Bonzoms permet de créer des relations entre deux tiers même si elle ne connaît pas les rôles de ces derniers. Ainsi une partie automatique +de l'application permet d'identifier les deux types de rôles correspondants à un type de relation (voir documentation sur les `relations`_ ). L'utilisateur de Bonzoms +peut ainsi créer précisemment une relation en lui fournissant les deux rôles (préalablement créés), ou bien laisser faire Bonzoms et lui fournir uniquement les deux +tiers impliqués dans la relation (en identifiant bien qui est le père). +La classe RelationshipAbstract quant à elle permet de lier la relation à son entité pour garder la partie commune aux deux types de DTO. + +.. image:: schemas/ClassDiagram_DTO.png + :alt: DTO de Bonzoms + :align: center + +Pour plus de détails techniques sur les dtos voir la documentation sur l'utilisation de `ToPIA`_. + +.. _ToPIA: developper/topia.html + +Services +-------- + +Les services seront ici décrit brievement. Vous pouvez voir le détail de chacun d'eux sur la page `services`_ . + +Les services permettent à l'utilisateur de manipuler le contenu de Bonzoms. On retrouve la notion d'héritage précédente entre les partys. Ainsi le ServiceParty +est l'interface père des ServicePerson et ServiceGroupPerson. Le ServiceOrganization hérite ici du ServiceGroupPerson pour permettre de travailler plus précisemment +sur les sociétés. Trois autres services sont disponibles : ServiceContact, ServiceRelationship et ServicePartyRole pour respectivement manipuler les contacts, +les relations et les rôles de Bonzoms. Certains éléments peuvent être manipulés dans différents services dépendant des besoins de l'utilisateur. Ainsi les contacts +peuvent être manipulés indépendamment des Party ou bien liés à ces derniers. Le principe reste identique pour les rôles et relations. Certaines méthodes permettent +en effet de créer automatiquement la relation et ses rôles (addDivision par exemple dans l'interface ServiceOrganization). + +.. _services: user/services.html + +.. image:: schemas/ClassDiagram_Services.png + :alt: Services de Bonzoms + :align: center + +Pour plus de détails techniques sur les services voir la documentation sur l'utilisation de `ToPIA`_. \ No newline at end of file Added: trunk/src/site/rst/user/export.rst =================================================================== --- trunk/src/site/rst/user/export.rst (rev 0) +++ trunk/src/site/rst/user/export.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,8 @@ +Export + +service d'export xPIL lie a Choreg + +donnees exporter (comment le standard est utilise via Oasis CIQ Api) + + + Added: trunk/src/site/rst/user/faq.rst =================================================================== --- trunk/src/site/rst/user/faq.rst (rev 0) +++ trunk/src/site/rst/user/faq.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1 @@ +FAQ \ No newline at end of file Added: trunk/src/site/rst/user/relations.rst =================================================================== --- trunk/src/site/rst/user/relations.rst (rev 0) +++ trunk/src/site/rst/user/relations.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,3 @@ +Relations + +Types de relations existantes + roles et utilisation des services pour automatisation \ No newline at end of file Added: trunk/src/site/rst/user/services.rst =================================================================== --- trunk/src/site/rst/user/services.rst (rev 0) +++ trunk/src/site/rst/user/services.rst 2009-09-25 09:53:35 UTC (rev 72) @@ -0,0 +1,12 @@ +Services +======== + +.. contents:: Sommaire + +description de chaque service + + +ServiceParty +------------ + +Service \ No newline at end of file Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-25 09:06:12 UTC (rev 71) +++ trunk/src/site/site.xml 2009-09-25 09:53:35 UTC (rev 72) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<project name="Bonzoms-ui"> +<project name="Bonzoms"> <publishDate format="dd/MM/yyyy"/> @@ -9,20 +9,35 @@ <body> -  + </item--> + <item name="Utiliser le module business"> + <item name="Services" href="user/services.html" /> + <item name="Export" href="user/export.html" /> + <item name="Gestion des relations" href="user/relations.html" /> + <item name="FAQ" href="user/faq.html" /> + </item> + </menu> <menu name="Développeur"> - <item name="Layout et Gestion des erreurs" href="developper/layout_erreurs.html"/> - <item name="Composants Tapestry" href="developper/composants.html"/> - <item name="Bonne pratiques pour Tapestry" href="developper/how-to.html"/> - <item name="Services" href="developper/services.html"/> - <item name="Todo" href="developper/todo.html"/> + <item name="User interface"> + <item name="Layout et Gestion des erreurs" href="developper/layout_erreurs.html"/> + <item name="Composants Tapestry" href="developper/composants.html"/> + <item name="Bonne pratiques pour Tapestry" href="developper/how-to.html"/> + <item name="Services" href="developper/services.html"/> + <item name="Todo" href="developper/todo.html"/> + </item> + <item name="Business"> + <item name="Organisation du projet" href="developper/organisation.html" /> + <item name="Génération avec ToPIA" href="developper/topia.html" /> + <item name="Utilisation de ChoReg" href="developper/choreg.html" /> + </item> </menu> <menu name="Downloads"> @@ -36,6 +51,11 @@ </menu> <menu name="Liens"> + <item name="ToPIA" href="http://nuiton.org/embedded/topia/topia-persistence/index.html" title="Documentation ToPIA" /> + <item name="ArgoUML" href="http://argouml.tigris.org/" title="ArgoUML" /> + <item name="ChoReg" href="http://chorem.org/embedded/choreg/choreg" title="Documentation ChoReg" /> + <item name="OASIS CIQ" href="http://www.oasis-open.org/committees/ciq/" title="Standard Oasis CIQ" /> + <item name="OASIS CIQ Api" href="http://chorem.org/embedded/choreg/oasis-ciq-api" title="Documentation Oasis CIQ Api" /> <item name="Tapestry" href="http://tapestry.apache.org/tapestry5.1/" title="Site officiel de Tapestry" /> <item name="Prototype" href="http://www.prototypejs.org/" title="Librarie JavaScript Prototype incluse dans Tapestry" /> <item name="ChenilleKit" href="http://www.chenillekit.org/chenillekit-tapestry/index.html" title="Librairie de composants Tapestry" />

1 0

r71 - in trunk: bonzoms-ui/src src/site src/site/resources src/site/resources/css src/site/resources/schemas src/site/rst src/site/rst/developper
by jcouteau＠users.chorem.org 25 Sep '09

25 Sep '09

Author: jcouteau Date: 2009-09-25 11:06:12 +0200 (Fri, 25 Sep 2009) New Revision: 71 Added: trunk/src/site/resources/ trunk/src/site/resources/css/ trunk/src/site/resources/css/site.css trunk/src/site/resources/schemas/ trunk/src/site/resources/schemas/getActiveBlock_error.png trunk/src/site/resources/schemas/layout_warnings.png trunk/src/site/resources/schemas/partyView_classes.png trunk/src/site/resources/schemas/snapshot_blockManager_hide.png trunk/src/site/resources/schemas/snapshot_blockManager_show.png trunk/src/site/resources/schemas/snapshot_contactComponent_edit_address.png trunk/src/site/rst/developper/ trunk/src/site/rst/developper/composants.rst trunk/src/site/rst/developper/how-to.rst trunk/src/site/rst/developper/layout_erreurs.rst trunk/src/site/rst/developper/services.rst trunk/src/site/rst/developper/todo.rst trunk/src/site/rst/index.rst Removed: trunk/bonzoms-ui/src/site/ Modified: trunk/src/site/site.xml Log: Put maven site on root. Add download links and trackers Copied: trunk/src/site/resources/css/site.css (from rev 70, trunk/bonzoms-ui/src/site/resources/css/site.css) =================================================================== --- trunk/src/site/resources/css/site.css (rev 0) +++ trunk/src/site/resources/css/site.css 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,7 @@ +pre.literal_block { + border: 2px groove #FF4940; + background-color: #FFF1E1; + padding: 11px 11px 0; + font-family: monospace; + color: #58140B; +} \ No newline at end of file Copied: trunk/src/site/resources/schemas/getActiveBlock_error.png (from rev 70, trunk/bonzoms-ui/src/site/resources/schemas/getActiveBlock_error.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/layout_warnings.png (from rev 70, trunk/bonzoms-ui/src/site/resources/schemas/layout_warnings.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/partyView_classes.png (from rev 70, trunk/bonzoms-ui/src/site/resources/schemas/partyView_classes.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/snapshot_blockManager_hide.png (from rev 70, trunk/bonzoms-ui/src/site/resources/schemas/snapshot_blockManager_hide.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/snapshot_blockManager_show.png (from rev 70, trunk/bonzoms-ui/src/site/resources/schemas/snapshot_blockManager_show.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/snapshot_contactComponent_edit_address.png (from rev 70, trunk/bonzoms-ui/src/site/resources/schemas/snapshot_contactComponent_edit_address.png) =================================================================== (Binary files differ) Copied: trunk/src/site/rst/developper/composants.rst (from rev 70, trunk/bonzoms-ui/src/site/rst/developper/composants.rst) =================================================================== --- trunk/src/site/rst/developper/composants.rst (rev 0) +++ trunk/src/site/rst/developper/composants.rst 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,125 @@ +Composants Tapestry de Bonzoms +============================== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-07-15* + +Plusieurs pages nécessitent l'affichage de données communes -> création de composants Tapestry : + +- ContactComponent : Gestion des contacts pour un tiers (party), que ce soit un groupe de personne, un service, une société, une personne, ... +- RoleComponent : Gestion des rôles pour un tiers +- RelationComponent : Gestion des relations pour un tiers + +D'autres composants graphiques ont été créé pour simplifier l'affichage des données : + +- BlockManager : Gestion d'un block considéré comme autonome, gestion du show/hide via JavaScript +- WindowLink : Lien permettant l'ouverture d'une fenêtre en Prototype + +ContactComponent +---------------- + +Ce composant a été le premier implémenté ce qui explique son fonctionnement différent des deux autres (RoleComponent et RelationComponent). +Il manipule une liste de contacts pour un tiers donné. Cette liste est persistante pour Tapestry (utilisation du @Persist) mais n'est pas sauvegardé en base. +La liste (composant `Grid`_ de Tapestry) est éditable : + +- Ajout d'un nouveau contact via un lien au dessus de la liste (différentes icones suivant le type de contact). +- Modification d'un contact existant via une icone au niveau de la ligne du contact (colonne "actions"). + +Un attribut "editable" présent dans l'objet **Contact** permet de connaître l'état du contact qui déterminera l'affichage d'un champs d'édition. +Le type de contact "Address" est différent des autres, il possède plusieurs champs d'édition (complement d'adresse, ville, code postal, pays) dont certains possèdent +un Autocomplete (ville et pays). Le mixin `OnEvent`_ de ChenilleKit est utilisé ici pour la sauvegarde des données en session à chaque changement d'édition (OnBlur ou OnChange). +Ce mixin a été intégré et modifié pour Bonzoms afin de permettre le passage de paramètres en context. + +Les éléments de la liste peuvent donc être ajoutés, modifiés et supprimés sans affecter la base de données. La sauvegarde des données doit se faire dans la page qui inclut +le composant ContactComponent. + +.. image:: ../schemas/snapshot_contactComponent_edit_address.png + :alt: Affichage d'une personne avec gestion des contacts (ContactComponent) + :align: center + +*Affichage d'une personne avec gestion des contacts (ContactComponent)* + +.. _Grid: http://tapestry.apache.org/tapestry5.1/tapestry-core/ref/org/apache/tapestr… + +.. _OnEvent: http://www.chenillekit.org/chenillekit-tapestry/ref/org/chenillekit/tapestr… + +Utilisation +~~~~~~~~~~~ + +ContactComponent est utilisé sur deux pages distinctes : + +- PersonView : affichage d'une personne +- OrganizationView : affichage d'une société + +Le comportement du ContactComponent est commun à ces deux pages. L'implémentation de la gestion des sauvegardes (ajout/modification/suppression) est donc faites +dans la partie commune à ces deux pages : dans la classe abstraite AbstractPartyView dont héritent PersonView et OrganizationView. + +Contrairement aux composants décrits ci-dessous, la gestion du ContactComponent se fait au niveau de la page qui l'utilise. + +RoleComponent +------------- + +Ce composant permet la gestion des rôles : Ajout, modification et suppression d'un rôle pour un tiers donné. Afin de le rendre autonome, il inclut son père sous la forme d'une interface +et via l'annotation @InjectContainer. L'interface utilisé est PartyView qui fournit trois méthodes : + +- getParty() : sélection du tiers +- getPartyId() : sélection de l'identifiant du tiers +- getPartys() : sélection de l'ensemble des tiers + +Chaque page utilisant le RoleComponent doit implémenter l'interface PartyView. De ce fait le RoleComponent est dépendant d'un tiers donné pour le chargement de ses données. +Deux classes implémentent actuellement cette interface : + +- AbstractPartyView : partie commune aux pages PersonView et OrganizationView +- RolesAndRelations : utilisation d'une liste déroulante pour la sélection d'un tiers, en découle la gestion de ses rôles et relations. + +RoleComponent intègre le composant Warnings pour sa gestion propre des erreurs, d'où l'implémentation de DataLoador (voir `Gestion des erreurs`_ ). + +.. image:: ../schemas/partyView_classes.png + :alt: Diagramme d'implémentation des pages PersonView et OrganizationView avec utilisation du RoleComponent + :align: center + +*Diagramme d'implémentation des pages PersonView et OrganizationView avec utilisation du RoleComponent* + +.. _Gestion des erreurs: layout_erreurs.html + +Utilisation +~~~~~~~~~~~ + +La page doit implémenter PartyView et doit intégrer à son tml : <t:rolecomponent /> + +RelationComponent +----------------- + +Ce composant permet la gestion des relations pour un tiers : Ajout, modification et suppression. Son comportement est similaire au RoleComponent. + +Utilisation +~~~~~~~~~~~ + +La page doit implémenter PartyView et doit intégrer à son tml : <t:relationcomponent /> + +BlockManager +------------ + +Il s'agit simplement d'un composant graphique permettant l'affichage dans un bloc d'une partie de la page. Ce bloc peut être caché ou montré. L'état +du bloc est sauvé en session. Il est utilisé pour tous les composants de gestion sur une page (gestion des contact, des services, des employés, des rôles, ...) + +.. image:: ../schemas/snapshot_blockManager_show.png + :alt: BlockManager show + :align: center + +*BlockManager en mode "show"* + +.. image:: ../schemas/snapshot_blockManager_hide.png + :alt: BlockManager hide + :align: center + +*BlockManager en mode "hide"* + +WindowLink +---------- + +Work in progress... \ No newline at end of file Copied: trunk/src/site/rst/developper/how-to.rst (from rev 70, trunk/bonzoms-ui/src/site/rst/developper/how-to.rst) =================================================================== --- trunk/src/site/rst/developper/how-to.rst (rev 0) +++ trunk/src/site/rst/developper/how-to.rst 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,177 @@ +Bonnes pratiques avec Tapestry +============================== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-07-16* + +Tapestry est un framework web en Java basé uniquement sur les conventions de nommage. Aucun XML n'est obligatoire pour la configuration des pages. A chaque page +est lié deux fichiers : + +- fichier template (.tml) : Vue de la page en xhtml + namespace tapestry +- fichier java : Contrôleur de la page avec gestion des évènements (EventHandler) et des propriétés (attributs dynamiques de la page) + +Tapestry est assez complexe à prendre en main, ce document vous servira à mieux appréhender les différentes techniques pour le chargement des données depuis les services +de Bonzoms-business. + +Evènementiel +------------ + +Plusieurs évènements sont lancés au chargement d'une page Tapestry (voir `Cycle de vie`_ ) : + +- Rendu de la page : Trois évènements concernent le rendu de la page (setupRender, beginRender et afterRender) +- Activation / Passivation : Deux évènements lancés à chaque action de la page (ainsi que l'ouverture) + +Tapestry ne garde pas les données en mémoire une fois la page exécutée. Chaque nouvel évènement lancé pourra potentiellement envoyé une exception si une propriété +nécessaire à l'affichage est null. Il existe plusieurs solutions pour pallier au problème de null sur les propriétés (plus ou moins bonnes). De nombreux évènements +peuvent causer ce problème, que ce soit des liens (actionlink ou eventlink), des soumissions de formulaire ou des évènements propres. + +.. _Cycle de vie: http://tapestry.apache.org/tapestry5.1/guide/lifecycle.html + +La question se pose : **Où charger les données depuis mes services (Bonzoms-business) et comment ne pas les perdre à chaque évènement ?** + +L'annotation @Persist +~~~~~~~~~~~~~~~~~~~~~ + +Cette annotation permet à un attribut de le rendre persistant en session (session navigateur web). Cependant, tout mettre en session pour ne pas perdre les données +(et ne pas les recharger), peut provoquer des problèmes de rafraichissement (un nouvel ajout non pris en compte, etc...). De plus, les sessions peuvent coûter en mémoire +côté client. Il ne faut abuser des @Persist !! + +Activate/Passivate +~~~~~~~~~~~~~~~~~~ + +Evènements très intéressants (et indispensables) qui permettent l'utilisation de paramètre (contexte) d'une page à une autre (Notamment via les liens `pagelink`_ avec +utilisation du paramètre "context"). Le Activate est un évènement qui est lancé très souvent sur la page (changement de fenêtre, click sur un lien avec javascript, formualaire, ...). +Il est donc important de ne surtout pas charger les données dans le onActivate. Cette méthode sert uniquement à garder le contexte de la page courante (un identifiant dans +la plupart des cas). + +Attention + Il ne faut pas créé plusieurs méthodes onActivate suivant le nombre de paramètres (comme il serait tentant de le faire en Java) car dans la majorité des cas, toutes + les méthodes onActivate seront exécutées ! Pour pallier au problème, il faut utiliser EventContext. + +.. _pagelink: http://tapestry.apache.org/tapestry5.1/tapestry-core/ref/org/apache/tapestr… + +Exemple:: + + private String monId; // identifiant de l'objet à afficher sur la page + + void onActivate(EventContext ec) { + monId = ec.get(String.class, 0); // Utilisation du EventContext, récupération du premier paramètre + } + + String onPassivate() { // ici on souhaite uniquement gardé un seul paramètre, l'identifiant + // (utilisation du EventContext non testé) + return monId; + } + +setupRender +~~~~~~~~~~~ + +Le setupRender est exécuté une seule fois au chargement de la page, il serait donc intéressant de l'utiliser pour le chargement des données ! Cependant, les évènements +liés au JavaScript sur la page peuvent nécessiter des propriétés de la page devenues null à la fin du chargement. Pour pallier au problème, il est possible d'utiliser +le @Persist, et donc de rendre null tous les attributs à charger dans le setupRender. Ainsi les données sont chargées une seule fois et le setupRender sera réexécuté dès le +rafraichissement (ou changement) de la page. + +Exemple:: + + @Inject + private MyService monService; + + @Persist + private List<String> maListe; + + void setupRender() { + maListe = null; + maListe = monService.getListProps(); + } + +Getter +~~~~~~ + +Tapestry oblige les propriétés d'une page à être "privé" et posséder des accesseurs (getter/setter). Il est possible d'utiliser l'annotation @Property pour ne pas avoir +à écrire les méthodes get et set de chaque propriété. Mais ne serait-il pas judicieux d'effectuer le chargement de chaque donnée au moment où Tapestry en a besoin ? +Ainsi le problème de null ne se posera plus, car le chargement se fera à ce moment là ! + +Exemple:: + + @Inject + private MyService monService; + + private List<String> maListe; + + public List<String> getMaListe() { // convention de nommage du getter + if (maListe == null) { + maListe = monService.getListProps(); + } + return maListe; + } + +Résumé +~~~~~~ + +L'utilisation des getter semble la meilleure solution pour pallier au problème des propriétés null pouvant engendrées des erreurs sur la page. Quel que soit l'évènement, +si Tapestry a besoin de connaître une propriété, il utilisera son getter et le chargement sera fait si l'attribut est null. Pour les données volumineuses, le @Persist +peut éviter de nombreuses requêtes inutiles à la base de données. Dans ce cas il est judicieux d'utiliser le setupRender ET les getter. + +Exemple:: + + @Inject + private MyService monService; + + @Persist + private List<String> maListe; + + void setupRender() { + maListe = null; + getMaListe(); // chargement unique (méthode getMaListe identique au paragraphe précédent) + } + + +DataLoador +---------- + +Une autre problématique concerne la gestion des messages d'erreurs qui peuvent survenir lors de l'utilisation des services. Comme vu dans `Gestion des erreurs`_ , +un composant Warnings (ou directement le Layout) permettent l'affichage des erreurs. Les pages doivent cependant implémenter l'interface DataLoador. Cette interface +est simple et ne possède qu'une seule méthode : loadData(). Cette méthode est exécuté au moment du rendu de la page (équivalent au setupRender) mais dans le composant +Warnings qui s'occupent des messages d'erreurs. Cette méthode permet de charger toutes les données qui engendrent potentiellement des erreurs, avant l'affichage de la page. +Pour simplifier, la méthode loadData() remplace tout simplement le setupRender(). Les données seront chargées via le loadData() de la même manière que le setupRender() +expliquer précédemment. + +.. _Gestion des erreurs: layout_erreurs.html + +Exemple:: + + public MyPage implements DataLoador { + ... + @Inject + private MyService monService; + + @InjectComponent + private Layout layout; + + @Persist + private List<String> maListe; + + void loadData() { + maListe = null; + getMaListe(); // chargement unique + } + + public List<String> getMaListe() { + if (maListe == null) { + try { + maListe = monService.getListProps(); + } catch (Exception eee) { + // utilisation de la gestion d'erreurs du layout + layout.addError("Une erreur est survenue, impossible de charger maListe"); + } + } + return maListe; + } + ... + } + + Copied: trunk/src/site/rst/developper/layout_erreurs.rst (from rev 70, trunk/bonzoms-ui/src/site/rst/developper/layout_erreurs.rst) =================================================================== --- trunk/src/site/rst/developper/layout_erreurs.rst (rev 0) +++ trunk/src/site/rst/developper/layout_erreurs.rst 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,123 @@ +Layout et Gestion des erreurs +============================= + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-07-15* + +Layout +------ + +Le Layout de Bonzoms est un composant Tapestry. Il permet de définir le contour du site comprenant le menu et la barre des langues pour la gestion de l'internationalisation. +Ce composant est appelé sur toutes les pages (package org.chorem.bonzoms.ui.pages):: + + <t:layout t:ident="${div-id}" t:pageTitle="${title}" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd" xmlns:p="tapestry:parameter"> + // contenu tml de la page + </t:layout> + +Cette balise entoure chacun des .tml des pages présents dans le dossier webapp. Deux paramètres sont fournis pour préciser des informations sur la page qui seront +inclus directement dans le layout : + +- pageTitle : titre de la page (placé dans la balise <title> du header du layout). +- ident : identifiant pour la balise <div> englobant la page, utilisé pour le CSS. + +Le layout gère également la gestion i18n via le service PersistentLocale de Tapestry. Les Locales des langues doivent être déclaré dans le AppModule :: + + public static void contributeApplicationDefaults( + MappedConfiguration < String, String > configuration) { + + ... + + configuration.add(SymbolConstants.SUPPORTED_LOCALES, "fr,en"); + ... + } + +Gestion des erreurs +------------------- + +Les erreurs survenues pendant l'affichage d'une page (notamment lors de la manipulation des méthodes des services de Bonzoms-business) peuvent être gérées par +le layout qui se chargera de les afficher. Un composant a été spécialement créé pour cela, le composant Warnings qui gère l'affichage du bloc de messages. +Une classe abstraite AbstractErrorManager permet de manipuler ces messages et de distinguer ceux qui sont des erreurs et ceux qui sont simplement des warnings. +Le composant Warnings ainsi que le Layout héritent tous les deux de cette classe pour permettre aux pages comme aux composants de gérer les erreurs. + +.. image:: ../schemas/layout_warnings.png + :alt: Diagramme d'implémentation du Layout et de la gestion des erreurs + :align: center + +*Diagramme d'implémentation du Layout et de la gestion des erreurs* + +Composant Warnings +~~~~~~~~~~~~~~~~~~ + +L'affichage du composant détermine également l'affichage de son contenu. Généralement le contenu est soit celui d'une page, soit un composant nécessitant un affichage +des erreurs/warnings. Le composant `delegate`_ de Tapestry permet d'afficher la page de trois manières différentes : + +- Existence d'erreurs : Affichage uniquement du bloc de messages d'erreurs +- Existence de warnings sans erreurs : Affichage du bloc de messages des warnings + contenu (t:body) +- Ni warnings, ni erreurs : Affichage du contenu + +.. _delegate: http://tapestry.apache.org/tapestry5.1/tapestry-core/ref/org/apache/tapestr… + +Cas d'une page +~~~~~~~~~~~~~~ + +Comme dit précédemment, chaque page contient le layout (via l'annotation @InjectComponent), et peut donc utiliser les méthodes pour la gestion des erreurs +comme addError, hasErrors, addWarnings, ... +Les erreurs doivent être fournies au Layout avant le rendu de la page, sinon le delegate du composant Warnings s'affichera sans connaître les futures erreurs. +Pour ce faire, l'interface DataLoador est utilisée. Cette interface possède une seule méthode : loadData(). Elle est executée juste avant l'affichage +du delegate du composant Warnings. Ainsi la page concerné implémentera la méthode loadData() qui contiendra ses méthodes nécessitant un affichage des erreurs. +Voir rubrique `Bonnes pratiques`_ pour plus de détails sur l'intérêt du loadData. +En fait le Layout se charge de transférer les erreurs directement au composant Warnings. La page ne se préocuppe pas de l'affichage des messages, le Layout est +là pour ca. + +.. _Bonnes pratiques: how-to.html + +Cas d'un composant +~~~~~~~~~~~~~~~~~~ + +Les composants peuvent également avoir leur propre affichage des erreurs. En effet, ils ne contiennent pas le Layout mais peuvent contenir directement le composant +Warnings qui sera utilisé pour le remplissage des messages d'erreurs/warnings. Sur le même principe qu'une page, le composant concerné devra implémenté l'interface +DataLoador et sa méthode loadData(). Contrairement au cas d'une page, le composant devra explicitement inséré le composant Warnings dans son .tml:: + + <t:warnings> + //contenu tml du composant + </t:warnings> + +Exemple +~~~~~~~ + +La page RolesAndRelations nécessite le chargement d'une liste des tiers (partys) existants. Cette liste sera affichée dans un composant select et ne nécessitera +pas de modifications lors de la navigation sur la page. La méthode getPartys() permet ce chargement. Cette méthode appel le service de Bonzoms-business pour récupérer +l'ensemble des tiers existants en base. Ainsi une BonzomsException peut survenir et un message d'erreur doit être donné au client. + +Trace d'execution : + +- Warnings : Affichage du contenu de la page en passant par le delegate : getActiveBlock() +- Layout : Le composant Warnings est inclut dans le Layout. Warnings connait son parent via l'annotation @InjectContainer. Ce parent doit implémenté la méthode + loadData() de l'interface DataLoador, ce qui est le cas du Layout : container.loadData() +- Layout : Le Layout, sur le même principe que le composant Warnings, connait son parent qui implémente également DataLoador (ceci implique que toutes pages doivent obligatoirement + implémenter DataLoador sinon elles ne pourront pas utiliser le Layout). Le Layout appele également container.loadData() +- RolesAndRelations : La méthode loadData est appelé, chargement des données : getPartys() +- RolesAndRelations : La méthode getPartys fait appel au service de Bonzoms-business et récupère l'exception BonzomsException si une erreur est survenue. Dans ce cas + une erreur est ajouté via la méthode layout.addError(...). +- Layout : Transfert des erreurs au composant Warnings : warnings.initComponent(errors, warnings) +- Warnings : Retour à la méthode getActiveBlock qui détecte une erreur ou non et affiche le contenu de la page en conséquence. + +.. image:: ../schemas/getActiveBlock_error.png + :alt: Séquence cas d'utilisation : Affichage page RolesAndRelations avec erreur lors du chargement des tiers + :align: center + +*Séquence cas d'utilisation : Affichage page RolesAndRelations avec erreur lors du chargement des tiers* + +Erreur lors d'une action +~~~~~~~~~~~~~~~~~~~~~~~~ + +Il est possible qu'une erreur survienne au moment d'une action sur la page, généralement lors d'un appel à un service de Bonzoms-business. L'affichage de cette erreur +peut être afficher simplement en rafraichissant la zone autour du delegate du composant Warnings. Le actionlink qui déclenche l'action doit être lié à cette zone : +<t:actionlink ... t:zone="**showWarnings**" >... Le EventHandler qui reçoit l'évènement sur le actionlink retournera le block que lui fournira le Layout (layout.getBody()) pour le cas +d'une page ou directement la zone depuis le composant Warnings (warnings.getZone()). Voir la documentation Tapestry pour l'utilisation des `Zone`_. + +.. _Zone: http://tapestry.apache.org/tapestry5.1/tapestry-core/ref/org/apache/tapestr… \ No newline at end of file Copied: trunk/src/site/rst/developper/services.rst (from rev 70, trunk/bonzoms-ui/src/site/rst/developper/services.rst) =================================================================== --- trunk/src/site/rst/developper/services.rst (rev 0) +++ trunk/src/site/rst/developper/services.rst 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,44 @@ +Services +======== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-07-16* + +Le AppModule de `Tapestry-IoC`_ permet de simplement lié les services de Bonzoms-business au registre de Tapestry. La méthode build de la classe AppModule permet +de "binder" les interfaces des services avec leurs implémentations. Tapestry se chargera d'instancier les services au moment où ceux ci sont utilisés. + +.. _Tapestry-IoC: http://tapestry.apache.org/tapestry5.1/tapestry-ioc/ + +AppModule +--------- + +:: + + public static void bind(ServiceBinder binder) { + // nécessite un identifiant à cause de l'héritage entre les services (ServicePerson extends ServiceParty, etc...) + binder.bind(ServiceParty.class, ServicePartyImpl.class).withId("serviceParty"); + binder.bind(ServicePerson.class, ServicePersonImpl.class); + binder.bind(ServiceContact.class, ServiceContactImpl.class); + ... + } + +Injection de service +-------------------- + +:: + + public class MyPage { + + @Inject + private ServicePerson servicePerson; + + @InjectService("serviceParty") + private ServiceParty serviceParty; + + ... + } + Copied: trunk/src/site/rst/developper/todo.rst (from rev 70, trunk/bonzoms-ui/src/site/rst/developper/todo.rst) =================================================================== --- trunk/src/site/rst/developper/todo.rst (rev 0) +++ trunk/src/site/rst/developper/todo.rst 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,18 @@ +Todo +==== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-07-20* + +Certaines fonctionnalités intéressantes non pas été implémentées : + +- Gestion des types de tiers (party) : Création d'une nouvelle page ? +- Plus d'options pour la création d'une société (raison sociale, ...) : voir avec Bonzoms-business +- Moteur de recherche sur annuaire : Nouvelle page avec filtres sur l'ensemble des contacts (gestion des contacts liés aux relations, ...) +- Compatibilité avec LDAP (voir avec Bonzoms-business) +- Gestion client/fournisseur plus précise (CRM/SRM) : nouvelles pages + Copied: trunk/src/site/rst/index.rst (from rev 70, trunk/bonzoms-ui/src/site/rst/index.rst) =================================================================== --- trunk/src/site/rst/index.rst (rev 0) +++ trunk/src/site/rst/index.rst 2009-09-25 09:06:12 UTC (rev 71) @@ -0,0 +1,26 @@ +Bonzoms Web Interface +===================== + +Ce module correspond à l'interface utilisateur de l'application Bonzoms. Cette interface a été réalisé grâce au framework Apache Tapestry. Il s'agit d'une interface +web basé sur une architecture à base de composants. Aucune configuration XML n'est nécessaire. Il est primordial de bien connaître Tapestry pour pouvoir développer +sur ce module. + +Vous trouverez sur les pages de ce module : + +* Documentation utilisateur + + - Introduction au guide utilisateur + - Gestion des personnes : ajout/modification/suppression + - Gestion des sociétés : ajout/modification/suppression, gestion des services, gestion des employés + - Gestion des contacts : pour une personne ou une société + - Gestion des rôles et relations : pour une personne, une société ou un autre tiers (service, association, client, ...) + +* Documentation développeur + + - Layout et Gestion des erreurs : utilisation des composants Layout et Warnings + - Composants pour Tapestry : composants liés à l'application (ContactComponent, RoleComponent, RelationComponent) ou composants graphiques (BlockManager, WindowLink) + - Bonnes pratiques avec Tapestry : comment Tapestry est utilisé pour le rendu des données depuis Bonzoms-business et évènementiel en Tapestry + - Todo : fonctionnalités intéressantes non implémentées + - Services : utilisation des services de Bonzoms-business via le AppModule de Tapestry (voir `Tapestry-IoC`_ ) + +.. _Tapestry-IoC: http://tapestry.apache.org/tapestry5.1/tapestry-ioc/module.html \ No newline at end of file Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-24 14:32:50 UTC (rev 70) +++ trunk/src/site/site.xml 2009-09-25 09:06:12 UTC (rev 71) @@ -1,34 +1,50 @@ <?xml version="1.0" encoding="UTF-8"?> -<project name="Bonzoms"> +<project name="Bonzoms-ui"> + <publishDate format="dd/MM/yyyy"/> + <bannerLeft> <name>${project.name}</name> - <href>index.html</href> </bannerLeft> - <poweredBy> - <logo href="http://maven.apache.org" name="Maven" img="${project.url}/images/logos/maven-feather.png"/> - <logo href="http://www.nuiton.org/projects/show/jrst" name="JRst" img="${project.url}/images/jrst-logo.png"/> - <logo href="http://docutils.sourceforge.net/rst.html" name="ReStructuredText" img="${project.url}/images/restructuredtext-logo.png"/> - </poweredBy> - <body> - <breadcrumbs> - <item name="${project.name}" href="${project.url}" /> - </breadcrumbs> - +  + + <menu name="Développeur"> + <item name="Layout et Gestion des erreurs" href="developper/layout_erreurs.html"/> + <item name="Composants Tapestry" href="developper/composants.html"/> + <item name="Bonne pratiques pour Tapestry" href="developper/how-to.html"/> + <item name="Services" href="developper/services.html"/> + <item name="Todo" href="developper/todo.html"/> + </menu> + <menu name="Downloads"> - <item name="Stable" href="http://maven.chorem.org/release/org/chorem/bonzoms"/> - <item name="Snapshot" href="http://maven.chorem.org/snapshot/org/chorem/bonzoms"/> + <item name="Downloads" href="http://chorem.org/projects/list_files/bonzoms"/> </menu> + <menu name="Trackers"> - <item name="Bugs" href="http://chorem.org/projects/bonzoms/issues?query_id=1"/> - <item name="Améliorations" href="http://chorem.org/projects/bonzoms/issues?query_id=2"/> - <item name="Aide" href="http://chorem.org/projects/bonzoms/issues?query_id=3"/> + <item name="Bugs" href="${project.issueManagement.url}?query_id=1"/> + <item name="Améliorations" href="${project.issueManagement.url}?query_id=2"/> + <item name="Aide" href="${project.issueManagement.url}?query_id=3"/> </menu> + <menu name="Liens"> + <item name="Tapestry" href="http://tapestry.apache.org/tapestry5.1/" title="Site officiel de Tapestry" /> + <item name="Prototype" href="http://www.prototypejs.org/" title="Librarie JavaScript Prototype incluse dans Tapestry" /> + <item name="ChenilleKit" href="http://www.chenillekit.org/chenillekit-tapestry/index.html" title="Librairie de composants Tapestry" /> + <item name="Code Lutin" href="http://codelutin.com/"/> + </menu> + <menu ref="reports"/> </body> + </project> +

1 0

r70 - trunk/src/site
by jcouteau＠users.chorem.org 24 Sep '09

24 Sep '09

Author: jcouteau Date: 2009-09-24 16:32:50 +0200 (Thu, 24 Sep 2009) New Revision: 70 Modified: trunk/src/site/site.xml Log: Add download links on maven-site Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-01 10:54:44 UTC (rev 69) +++ trunk/src/site/site.xml 2009-09-24 14:32:50 UTC (rev 70) @@ -18,8 +18,10 @@ <item name="${project.name}" href="${project.url}" /> </breadcrumbs> - <menu ref="modules"/> - + <menu name="Downloads"> + <item name="Stable" href="http://maven.chorem.org/release/org/chorem/bonzoms"/> + <item name="Snapshot" href="http://maven.chorem.org/snapshot/org/chorem/bonzoms"/> + </menu> <menu name="Trackers"> <item name="Bugs" href="http://chorem.org/projects/bonzoms/issues?query_id=1"/> <item name="Améliorations" href="http://chorem.org/projects/bonzoms/issues?query_id=2"/>

1 0

r69 - trunk/src/site
by tchemit＠users.chorem.org 01 Sep '09

01 Sep '09

Author: tchemit Date: 2009-09-01 12:54:44 +0200 (Tue, 01 Sep 2009) New Revision: 69 Modified: trunk/src/site/site.xml Log: use issues filters + remove plublish date format (inherited from mavenpom) Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-08-31 17:12:29 UTC (rev 68) +++ trunk/src/site/site.xml 2009-09-01 10:54:44 UTC (rev 69) @@ -1,8 +1,6 @@ <?xml version="1.0" encoding="UTF-8"?> <project name="Bonzoms"> - <publishDate format="dd/MM/yyyy"/> - <bannerLeft> <name>${project.name}</name> <href>index.html</href> @@ -23,9 +21,9 @@ <menu ref="modules"/> <menu name="Trackers"> - <item name="Bugs" href="http://chorem.org/projects/bonzoms/issues"/> - <item name="Améliorations" href="http://chorem.org/projects/bonzoms/issues"/> - <item name="Aide" href="http://chorem.org/projects/bonzoms/issues"/> + <item name="Bugs" href="http://chorem.org/projects/bonzoms/issues?query_id=1"/> + <item name="Améliorations" href="http://chorem.org/projects/bonzoms/issues?query_id=2"/> + <item name="Aide" href="http://chorem.org/projects/bonzoms/issues?query_id=3"/> </menu> <menu ref="reports"/>

1 0