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 of model generator--> + <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> + <!-- Topia generation from zargo --> + <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> - <!--menu name="Utilisateur" inherit="top" > + <menu name="Utilisateur" inherit="top" > + <!--item name="Utiliser l'interface"> <item name="Introduction" href="user/introduction.html" /> <item name="Personnes" href="user/person.html" /> <item name="Sociétés" href="user/company.html" /> <item name="Contacts" href="user/contacts.html" /> <item name="Roles et relations" href="user/roles_relations.html" /> - </menu--> + </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" />