Author: fdesbois Date: 2009-08-25 18:49:18 +0200 (Tue, 25 Aug 2009) New Revision: 53 Modified: trunk/bonzoms-business/src/site/rst/developper/topia.rst Log: documentation for Topia finished Modified: trunk/bonzoms-business/src/site/rst/developper/topia.rst =================================================================== --- trunk/bonzoms-business/src/site/rst/developper/topia.rst 2009-08-24 08:46:28 UTC (rev 52) +++ trunk/bonzoms-business/src/site/rst/developper/topia.rst 2009-08-25 16:49:18 UTC (rev 53) @@ -114,7 +114,7 @@ Voici le diagramme qui permet de générer les entités de Bonzoms : .. image:: ../schemas/ClassDiagram_Entities_generation.png - :alt: Modèle du domaine - Entités de Bonzoms + :alt: Modèle pour génération des entités :align: center Classes vertes : pas de génération des classes DAOImpl et Impl @@ -126,15 +126,107 @@ BeanGenerator ------------- -DTO Generation +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). -- Dependances -- Convert -- TopiaId +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. -Services Generation +Exemple ajout/modification via ServiceHelper :: -- ToPIA-SOA non utilise en runtime + 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