Author: jcouteau Date: 2009-09-24 15:43:08 +0200 (Thu, 24 Sep 2009) New Revision: 41 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/Chorem-Formats.png trunk/src/site/resources/schemas/Chorem-Registry.png trunk/src/site/resources/schemas/ClassDiagram_ChoReg_API.png trunk/src/site/resources/schemas/ClassDiagram_ChoremRegistryImpl.png trunk/src/site/resources/schemas/ClassDiagram_Exceptions.png trunk/src/site/resources/schemas/ServiceMix3.png trunk/src/site/resources/schemas/UseCaseDiagram_ChoReg.png trunk/src/site/resources/schemas/business_communications_connected.png trunk/src/site/resources/schemas/business_communications_disconnected.png trunk/src/site/resources/schemas/composants_applications_chorem.png trunk/src/site/resources/schemas/exemples/ trunk/src/site/resources/schemas/exemples/ClassDiagram_ServicePersonGeneric.png trunk/src/site/resources/schemas/exemples/ClassDiagram_ServicePersonImpl.png trunk/src/site/resources/schemas/exemples/DeploymentDiagram_Tomcat6_Bonzoms_Cash.png trunk/src/site/resources/schemas/exemples/SequenceDiagram_Execution_Bonzoms_Cash.png trunk/src/site/resources/schemas/ui-business_communications_v2.png trunk/src/site/rst/ trunk/src/site/rst/architecture/ trunk/src/site/rst/architecture/archi_chorem_part1.rst trunk/src/site/rst/architecture/archi_chorem_part2.rst trunk/src/site/rst/developper/ trunk/src/site/rst/developper/details.rst trunk/src/site/rst/developper/project.rst trunk/src/site/rst/developper/todo.rst trunk/src/site/rst/index.rst trunk/src/site/rst/presentation/ trunk/src/site/rst/presentation/api.rst trunk/src/site/rst/presentation/definitions.rst trunk/src/site/rst/presentation/presentation.rst trunk/src/site/rst/recherche/ trunk/src/site/rst/recherche/apache.rst trunk/src/site/rst/recherche/osgi.rst trunk/src/site/rst/recherche/technos.rst trunk/src/site/rst/stage/ trunk/src/site/rst/stage/recapitulatif.rst trunk/src/site/rst/stage/sujet.rst trunk/src/site/rst/user/ trunk/src/site/rst/user/best_practices.rst trunk/src/site/rst/user/deployment.rst trunk/src/site/rst/user/faq.rst trunk/src/site/rst/user/filters.rst trunk/src/site/rst/user/formats.rst trunk/src/site/rst/user/security.rst trunk/src/site/rst/user/start.rst Removed: trunk/choreg/src/site/ trunk/chorem-commons/src/site/ trunk/oasis-ciq-api/src/site/ Modified: trunk/pom.xml trunk/src/site/site.xml Log: Move maven-site to root, remove modules empty maven-sites Modified: trunk/pom.xml =================================================================== --- trunk/pom.xml 2009-09-09 14:17:10 UTC (rev 40) +++ trunk/pom.xml 2009-09-24 13:43:08 UTC (rev 41) @@ -60,8 +60,8 @@ <!-- *** Project Information ************************************* --> <!-- ************************************************************* --> - <name>ChoReg Pom Parent</name> - <description>Chorem Registry for Chorem applications</description> + <name>ChoReg</name> + <description>Registry for Chorem applications</description> <inceptionYear>2009</inceptionYear> <licenses> Copied: trunk/src/site/resources/css/site.css (from rev 40, trunk/choreg/src/site/resources/css/site.css) =================================================================== --- trunk/src/site/resources/css/site.css (rev 0) +++ trunk/src/site/resources/css/site.css 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,11 @@ +pre.literal_block { + border: 2px groove #FF4940; + background-color: #FFF1E1; + padding: 11px 11px 0; + font-family: monospace; + color: #58140B; +} + +table.bodyTable p { + margin: 0; +} \ No newline at end of file Copied: trunk/src/site/resources/schemas/Chorem-Formats.png (from rev 40, trunk/choreg/src/site/resources/schemas/Chorem-Formats.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/Chorem-Registry.png (from rev 40, trunk/choreg/src/site/resources/schemas/Chorem-Registry.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/ClassDiagram_ChoReg_API.png (from rev 40, trunk/choreg/src/site/resources/schemas/ClassDiagram_ChoReg_API.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/ClassDiagram_ChoremRegistryImpl.png (from rev 40, trunk/choreg/src/site/resources/schemas/ClassDiagram_ChoremRegistryImpl.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/ClassDiagram_Exceptions.png (from rev 40, trunk/choreg/src/site/resources/schemas/ClassDiagram_Exceptions.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/ServiceMix3.png (from rev 40, trunk/choreg/src/site/resources/schemas/ServiceMix3.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/UseCaseDiagram_ChoReg.png (from rev 40, trunk/choreg/src/site/resources/schemas/UseCaseDiagram_ChoReg.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/business_communications_connected.png (from rev 40, trunk/choreg/src/site/resources/schemas/business_communications_connected.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/business_communications_disconnected.png (from rev 40, trunk/choreg/src/site/resources/schemas/business_communications_disconnected.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/composants_applications_chorem.png (from rev 40, trunk/choreg/src/site/resources/schemas/composants_applications_chorem.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/exemples/ClassDiagram_ServicePersonGeneric.png (from rev 40, trunk/choreg/src/site/resources/schemas/exemples/ClassDiagram_ServicePersonGeneric.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/exemples/ClassDiagram_ServicePersonImpl.png (from rev 40, trunk/choreg/src/site/resources/schemas/exemples/ClassDiagram_ServicePersonImpl.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/exemples/DeploymentDiagram_Tomcat6_Bonzoms_Cash.png (from rev 40, trunk/choreg/src/site/resources/schemas/exemples/DeploymentDiagram_Tomcat6_Bonzoms_Cash.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/exemples/SequenceDiagram_Execution_Bonzoms_Cash.png (from rev 40, trunk/choreg/src/site/resources/schemas/exemples/SequenceDiagram_Execution_Bonzoms_Cash.png) =================================================================== (Binary files differ) Copied: trunk/src/site/resources/schemas/ui-business_communications_v2.png (from rev 40, trunk/choreg/src/site/resources/schemas/ui-business_communications_v2.png) =================================================================== (Binary files differ) Copied: trunk/src/site/rst/architecture/archi_chorem_part1.rst (from rev 40, trunk/choreg/src/site/rst/architecture/archi_chorem_part1.rst) =================================================================== --- trunk/src/site/rst/architecture/archi_chorem_part1.rst (rev 0) +++ trunk/src/site/rst/architecture/archi_chorem_part1.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,163 @@ +Architecture des applications CHOREM +==================================== + +:Author: $Author$ +:Version: 1.1 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 23-06-2009* + +Applications connus : + +- "Budgeting" : Gestion de la trésorerie (prévisionnel) +- Callao/Lima #EXIST#: Gestion comptable (réel) +- "Invoicing" : Gestion des factures +- "Calendar" : Gestion du calendrier (agendas, évènements, ...) +- Gepeto : Gestion de projet (inclus les notes de frais) +- Bonzoms #EXIST# : Gestion des personnes et sociétés +- "HumanResources" : Gestion des contrats pour les ressources humaines +- "Communication" : Suivi des communications (tracabilité réunion, mails, ...) +- JTimer #EXIST# : Temps réel des tâches +- "SecurityManager" : Gestion des droits et comptes utilisateurs +- Pollen #EXIST# : Application de vote +- "Documents" : Gestion des documents (impression, templates d'edition, ...) + +Chaque application est indépendante mais peut fonctionner en collaboration avec d'autres. Pour cela, un registre enregistre l'ensemble des services proposés et disponibles pour toutes les applications. +Nous appelerons ce registre ChoremRegistry. + +.. image:: ../schemas/composants_applications_chorem.png + :alt: Applications Chorem + +Chaque application comprend deux modules : + +- business : Partie métier de l'application, implémentation des services, gestion de LA base de données. +- ui : Interface utilisateur qui permet un affichage du métier de l'application. + +Un troisième module est envisageable dépendant des technologies utilisés : + +- api : interfaces des services et DTO pour transfert des données. + +Chaque service d'une application sera identifié de manière unique par un sid. Ce dernier sera construit grâce au nom complet du service (ex : org.chorem.bonzoms.services.ServicePerson). +ChoremRegistry connaîtra l'ensemble des services courants (en cours d'execution) ainsi que leur url réel. Les url des UI pourront également être sauvegardés dans un autre registre avec pour clé le même sid. + +Exemple :: + + Map<String, String> registreService; + Map<String, String> registreUI; + registreService.put("org.chorem.bonzoms.services.ServicePerson","iiop://chorem.org:9898/bonzoms/ServicePerson"); + registreUI.put("org.chorem.bonzoms.services.ServicePerson","http://chorem.org:8082/bonzoms/person"); + +Les collaborations entre applications peuvent être de différents types suivant les cas. Voici les trois principaux types : + +- Business-Business : Mode synchro/desynchro, alimentation des données d'une appli à l'autre. +- Business-UI : Validation auprès du SecurityManager + demande de service auprès de ChoremRegistry. +- UI-UI : Validation auprès du SecurityManager + demande d'ui auprès de ChoremRegistry. + +Collaboration Business-Business +------------------------------- + +Une application a besoin des données d'une autre application pour alimenter sa base de données. Pour cela, nous allons utilisé les messages pour la communication. Prenons un exemple : un utilisateur +crée une nouvelle facture via l'application Invoicing. Ces données étant potentiellement utiles à d'autres applications (comme Budgeting), Invoicing va envoyé un nouveau message notifiant la création +d'une nouvelle facture. Si Budgeting est actuellement en cours d'exécution, il va récupérer l'information pour l'enregistrer dans sa base de données. + +.. image:: ../schemas/business_communications_connected.png + :alt: Communications Business-Business en mode connecté + +Deux solutions en cas de non présence de Budgeting : + +- Solution 1 : Topic : Le message est perdu après envoi depuis Invoicing. Lorsque Budgeting sera à nouveau en cours d'exécution (et enregister dans ChoremRegistry), il ira demander les + nouvelles modifications auprès de Invoicing. A noter la nécessité de connaître la dernière date de synchronisation des données. +- Solution 2 : MessageQueue : Le message est sauvegardé en attendant qu'il soit interprété par Budgeting. Invoicing devra connaître le destinaire pour envoyé le message suivant cette + méthode sinon le message ne saura pas quand il doit être supprimé. + +La 1ère solution semble plus adapté. Budgeting n'aura pas besoin de repasser par le gestionnaire de messagerie, il lui suffira d'aller directement à la source pour connaître les nouvelles +modifications. Cependant cela nécessitera de nouvelles méthodes aux services potentiellement synchronisables. + +.. image:: ../schemas/business_communications_disconnected.png + :alt: Communications Business-Business en mode non connecté + +Collaboration Business-UI +------------------------- + +Ici il s'agit de permettre à un UI de récupérer directement un ensemble de données qui seront manipulés spécifiquement dans l'UI. Prenons un exemple : Un utilisateur peut demander +l'affichage des projets sur son agenda via l'application Calendar. Calendar devra donc demander la présence du service adéquat auprès de ChoremRegistry pour afficher les projets sur +l'agenda. Une notion importante se rajoute ici, celle des droits d'accès. En effet l'utilisateur n'aura pas forcément le droit d'accéder à tous les projets, mais potentiellement les siens +uniquement. Calendar aura donc la nécessité de vérifier les droits d'accès de l'utilisateur auprès du SecurityManager. Une fois les permissions requises accordées, Calendar pourra demander +au registre l'url du service nécessaire à la récupération des projets. Si le SecurityManager n'est pas présent dans ChoremRegistry, aucune restriction n'empêchera l'utilisateur d'afficher +les projets. Nous discuterons ultérieurement du format des données transférées. + +.. image:: ../schemas/ui-business_communications_v2.png + :alt: Communications Business-UI + +Collaboration UI-UI +------------------- + +Une interface peut afficher uniquement un lien permettant de rediriger l'utilisateur vers l'application source des données externes à l'application. Prenons un exemple : Nous avons vu précédemment +que Budgeting a enregistrer des données provenant de Invoicing. Au moment de la sauvegarde en base, ces données sont précisémenent lié à leurs sources via un uriChorem. Cette uriChorem comprendra +le sid du service source ainsi que le topiaId de la donnée concernée. Il sera donc possible de rediriger l'utilisateur si le service source, et plus particulièrement son ui, est disponible dans +le registre. Deux solutions se profilent ici (en reconsidérant les précédentes explications sur ChoremRegistry et les deux Map) : + +- Deux registres différents avec comme clé commune le sid du service considéré (comme vu précédemment) +- Une méthode présente dans le service permettant de récupérer l'url de l'ui à afficher. + +La deuxième solution paraît plus souple car les url d'ui peuvent être très spécifiques aux frameworks utilisés empêchant un enregistrement d'une url globale dans le registre. En effet l'identifiant +sera nécessaire pour l'affichage de la facture désiré et le registre ne connaîtra pas forcément la façon de rendre l'url valide pour l'affichage de la page. Autant demandé directement l'url auprès +du service concerné plutôt que de repassé par le registre qui ne saura pas comment retourné l'url. + +Il est également intéressant de pouvoir "coller" une étiquette/description sur l'url, seul le service pourra retourner une url valide et sa description. Globalement chaque service renverra potentiellement +deux (voir trois) types de liens : + +- liste de l'element (List) : peut nécessiter potentiellement des filtres + -> getUrlList(filters) +- description de l'element (View) + -> getUrlView(topiaId) +- formulaire ajout/modification de l'element (Form) + -> getUrlForm(topiaId) // topiaId peut etre null + +Normes à établir +---------------- + +Nous avons vu quels sont les différentes collaborations possibles entre les applications. Voici les normes utilisés pour ChoremRegistry : + +* String sid : package.serviceName + ex : org.chorem.bonzoms.services.ServicePerson + +* String uriChorem : sid://topiaId + ex : org.chorem.bonzoms.services.ServicePerson://org.chorem.bonzoms.persistence.PersonEntity#.3213545024#0.457758 + +* Class Link : + + - String libelle = description du lien + - String url = url de la page + +ex:: + + Link.libelle = "Pollen Project" + Link.url = "http://chorem.org/gepeto/project/K457.547212K1425.0445 + +Il va falloir déterminer précisémment quel est le format des données pour le transfert entre les services ou via les Ui. + +Solution spécifique +------------------- + +- Utilisation des api des applications. Les DTO sont normalisés pour chaque application. Les services utilisent uniquement ces DTO. +- Utilisation des normes existantes pour certains types de données (iCalendar, LDAP, ...) + +`lire la suite`_ : Spécifications de Chorem-Registry + +Note + Le document suivant remet en cause certaines informations décrites ici : le registre ne garde pas les url mais les instances de Services. + +.. _lire la suite: archi_chorem_part2.html + + + + + + + + + + + Copied: trunk/src/site/rst/architecture/archi_chorem_part2.rst (from rev 40, trunk/choreg/src/site/rst/architecture/archi_chorem_part2.rst) =================================================================== --- trunk/src/site/rst/architecture/archi_chorem_part2.rst (rev 0) +++ trunk/src/site/rst/architecture/archi_chorem_part2.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,179 @@ +Chorem-Registry Application (Trouver un nom pour l'application) +=============================================================== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 02-07-2009* + +ChoremRegistry (classe) +----------------------- + +ChoremRegistry est un service permettant la communication entre les différentes applications Chorem. Il possède +deux registres : + +- uis : Contient les services de gestion des liens vers les UI +- services : Contient les services métiers + +Chaque registre est spécifique soit au module business soit au module ui d'une application. Un registre est une map +avec pour clé le sid du service et pour valeur l'implémentation du service. Cette implémentation doit impérativement implémenté les interfaces spécifiques au registre souhaité : + +- registre uis : interface ChoremUIService +- registre services : interface ChoremService + +Ces deux interfaces permettent la communication entre le registre et les services enregistrés. Ainsi chaque service désirant être disponible pour d'autres applications chorem devra +implémenté l'interface adéquat, que ce soit un service pour l'UI ou pour le Business. + +.. image:: ../schemas/Chorem-Registry.png + :alt: Diagramme de classes pour Chorem-Registry + +Chaque application devra au démarrage enregistrer auprès de ChoremRegistry l'ensemble de ses services qui implémentent ChoremService et l'ensemble de ses services d'ui qui +implémentent ChoremUIService. + +ChoremService +------------- + +ChoremService est une interface permettant la sélection d'éléments potentiellement intéressant pour d'autres applications chorem. Elle définie principalement deux méthodes : + +- find : récupération d'un seul objet +- findAll : récupération d'une liste d'objet + +ChoremFormat +------------ + +Le format des données transférés (dans ChoremService) peut être : + +- soit spécifique et définie comme un ChoremFormat : La classe java est connue par les applications chorem dans Chorem-Registry. +- soit inconnue par ChoremRegistry, dans ce cas seul le nom de l'objet (et non sa classe) sera manipulé pouvant potentiellement engendré plus facilement des erreurs (noms des attributs, ...) + mais permettant une manière plus souple de faire communiquer deux applications. + +Il est possible d'utiliser des formats standards existants comme LDAP, iCalendar, ... Ces formats pourront hérités du ChoremFormat ou seront manipulés indépendamment du ChoremRegistry +(pas de vérification de type). + +Chaque service pourra communiquer au ChoremRegistry l'ensemble des formats qu'il manipule, deux cas possibles : + +- le ChoremRegistry ne vérifie pas les formats et fait suivre l'ensemble des demandes à tous les services connus (c'est le service qui se chargera de vérifier si le format est connu) +- le ChoremRegistry connait à l'enregistrement d'un service l'ensemble des formats qu'il manipule pour filtrer les + demandes. + +Le deuxième cas est plus intéressant, permettant ainsi d'alléger le nombre de demande aux services. Ainsi chaque service devra pouvoir fournir l'ensemble des formats qu'il manipule +au moment de son enregistrement auprès du ChoremRegistry. + +Implémentation prévu : + +- MultiMap pour la gestion des formats : la clé correspond au sid du Service et la/les valeurs aux différents formats supportés par le service. +- méthode getFormats à implémenter dans l'interface ChoremService : retourne une liste des formats supportés (sous forme de String par souci de simplicité). + +Contrainte : Chaque service devra pouvoir fournir la source (uri) de chaque objet transférer. + +Dans le cas de l'utilisation des ChoremFormat, il est intéressant de pouvoir connaître les différentes possibilités de filtre lors d'utilisation de la méthode findAll. +Ainsi les filtres possibles seront fournies sous la forme de variable statique dans le ChoremFormat. + +.. image:: ../schemas/Chorem-Formats.png + :alt: Diagramme de classes pour Chorem-Formats + :align: center + +Exemple : +~~~~~~~~~ + +Rappel : Party (Tiers en français) est définit dans Bonzoms comme étant soit une personne (class Person) soit un group de personne (class GroupPerson). Il existe des relations et des rôles +entre les partys (quelque soit leur type). Il est possible de connaître l'ensemble des Person lié à un GroupPerson, et même l'ensemble des Party (groupe ou non) lié à un GroupPerson (une société +par exemple a des services, des employés, des clients, ...) + +- ChoremFormat contient l'uri. +- PartyFormat extends ChoremFormat. +- FILTER_ID_GROUP_PERSON est un filtre disponible pour un PartyFormat (Par convention d'écriture : ID définit le type du filtre, un FILTER_BOOL définira un type Boolean pour le filtre) + +:: + + List<PartyFormat> results = registry.findAll( + userId, + PartyFormat.class, + PartyFormat.FILTER_ID_GROUP_PERSON, + "org.chorem.bonzoms.ServiceGroupPerson://org.chorem.bonzoms.GroupPersonEntity#10.01154879#642.669"); + + // L'identifiant ici est l'uri source de l'objet filtre pour uniformiser les identifiants. + // Il serait possible dans ce cas, de ne pas préciser le sid. Le service se chargera de + // retrouver l'élément (qu'il contient dans sa base !) + + registry.findAll( + userId, + ProjectFormat.class, + ProjectFormat.FILTER_ID_PARTY, + "org.chorem.bonzoms.ServicePerson://org.chorem.bonzoms.Person#10354.067851#524558763.035"); + + // Dans ce deuxième cas, il est important que l'id soit l'uri complète étant donné que Project est un + // format pour l'application Gepeto et non Bonzoms. + +Idées en vrac sur les filtres : +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Possibilité de différencier les filtres id et uri : FILTER_URI_PARTY par exemple (pas de réelle importance à ce niveau) + +- Il serait intéressant également de pouvoir cumuler les memes filtres avec des valeurs différentes. Dans le cas du FILTER_ID_GROUP_PERSON par exemple, connaitre tous les partys ayant + un lien avec 2 groupes de personnes différents (qui peuvent également avoir un lien entre eux, ...) + +- Il serait également possible d'étendre le concept avec les tris ou les limites : ORDER_BY_ASC, ORDER_BY_DESC, FILTER_INT_LIMIT_START, FILTER_INT_LIMIT_MAX + + +ChoremUIService +--------------- + +ChoremUIService est une interface permettant la récupération des liens d'interfaces disponibles. Trois types de liens existent : + +- ViewUrl : Affichage d'un seul élément +- FormUrl : Affichage du formulaire d'ajout/modification de l'élément +- ListUrl : Affichage d'une liste d'éléments + +Par souci de simplicité, la gestion de la navigation entre formulaires ne sera pas expliquer dans ce document. + +Un même objet "Link" fourni par Chorem-Registry permettra l'échange des liens (comprenant le libelle du lien et son url). + +ChoremSecurity +-------------- + +En ce qui concerne la gestion des droits utilisateurs, une interface ChoremSecurity devra être implémenté et enregistré auprès du ChoremRegistry. Une seule implémentation est +possible en meme temps. L'application gérant la sécurité (nom indéterminé...) des applications chorem sera la mieux placé pour implémenté l'interface ChoremSecurity. + +Deux méthodes à implémenter : + +- validate : permet la validation d'un utilisateur auprès d'un uri (appPackageName ou sid ou sid://entityName ou sid://topiaId) +- connect : demande de connexion d'un utilisateur (classe CryptedUser), renvoie un userId (topiaId ou id aleatoire comme jeton de connexion) + +Chaque appel au ChoremRegistry devra utilisé le userId définit ainsi. Cet identifiant pourra potentiellement être null, si aucun service de securité n'est rattaché au +ChoremRegistry (pas de vérification des droits d'accès). + +Exemples : + +============ ========================================================================================== ========= + Login Uri Write +============ ========================================================================================== ========= + fdesbois org.chorem.bonzoms false + fdesbois org.chorem.bonzoms.ServicePerson://org.chorem.bonzoms.PersonEntity#00552354.02#5423647 true + bpoussin org.chorem.bonzoms.ServiceGroupPerson true + bpoussin org.chorem.bonzoms.ServiceRelationship false +============ ========================================================================================== ========= + +Description uri possibles : + +- uri : org.chorem.bonzoms.ServicePerson://org.chorem.bonzoms.PersonEntity#00552354.02#5423647 +- appPackageName : org.chorem.bonzoms +- sid : org.chorem.bonzoms.ServicePerson +- entityName : org.chorem.bonzoms.PersonEntity +- topiaId : org.chorem.bonzoms.PersonEntity#00552354.02#5423647 + +ChoremRegistryException +----------------------- + +Deux principaux types d'exception peuvent survenir (en dehors du IllegalArgumentException) : + +- NoServiceException : aucun service enregistré correspondant à l'uri passé en paramètre. +- NotAllowedException : acces interdit à l'uri (ou le format d'objet) passé en paramètre. + +Alternative aux interfaces +-------------------------- + +Utilisation des messages (JMS) pour la communication. Chaque service enverra un message à ChoremRegistry qui se chargera de dispatcher les messages aux différentes applications et +de récupérer les réponses. Message de type topic (méthode publish/subscribe en analogie avec le register du ChoremRegistry), chaque application ne sachant pas si un destinataire est connecté. Copied: trunk/src/site/rst/developper/details.rst (from rev 40, trunk/choreg/src/site/rst/developper/details.rst) =================================================================== --- trunk/src/site/rst/developper/details.rst (rev 0) +++ trunk/src/site/rst/developper/details.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,82 @@ +ChoremRegistryImpl +================== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-05* + +ChoremRegistryImpl implémente l'interface qui sera utilisé par les applications Chorem pour les accès aux données/urls. Elle comprend trois maps très importantes +pour la manipulation des services et la recherche sur les formats, sid, ... + +.. image:: ../schemas/ClassDiagram_ChoremRegistryImpl.png + :alt: Diagramme d'implémentation du ChoremRegistryImpl + +Structures de données +--------------------- + +La map des services est formé comme ceci : Map<String, Map<String, ChoremService>>. La map principale prend comme clé l'identifiant du service, le sid. Sa valeur +prend une autre map composé du nom du format comme clé et de l'instance de service comme valeur. +Ainsi il peut y avoir plusieurs implémentations (une par format) pour un même service avec un même sid. + +- sid : org.chorem.bonzoms.services.ServicePerson +- formats : XPIL, vCard, ... + +La map des formats quant à elle, a pour clé le nom du format et une liste des sid des services correspondant pour valeurs (Map<String, List<String>>). +Il est donc plus facile de trouver tout les services pour un format donné au moment du findAll. + +La troisième map enregistre les services ui (qui implémente ChoremUIService) pour la récupération des urls. L'identifiant du service ui doit +utiliser le même que celui du service de base (donc pour l'exemple org.chorem.bonzoms.services.ServicePerson). + +Pourquoi ? + +Car la recherche d'une url se fait sur le choremUri qui comprend le sid du service et donc du service de données. + +Ainsi pour résumé nous avons autant d'implémentation de services possibles pour un même sid. Chaque implémentation correspondra à une UI ou un format. + +Extension non prévu : Permettre plusieurs ui pour un même service et donc avec le même sid. + +Validation +---------- + +Il y a plusieurs méthodes de validation en scope **private** dans l'implémentation permettant la vérification du choremUri : + +- nullité +- existence du service (sid inclut dans le choremUri) +- syntaxe correcte (avec ou sans topiaId, ...) + +Il y a également une méthode pour la validation de la sécurité : + +- existence du service +- validation du userId +- validation des droits d'accès auprès du service de sécurité + +Certaines exceptions peuvent émaner de ces validations. + +Exceptions +---------- + +Il y a quatres exceptions différentes possibles en plus de la classique IllegalArgumentException. Trois d'entre elles héritent d'une même exception *ChoregException* : + +- NoServiceException : Erreur sur la demande auprès d'un service (service inconnu par ChoReg) +- NotAllowedException : Erreur de droit d'accès aux données (Sécurité) +- TimeoutException : Erreur sur la session de connexion de l'utilisateur (Sécurité) + +La dernière, *WrongTypeException*, permet aux fournisseurs de services d'indiquer à ChoReg que le type de retour souhaité par le client est incorrect. +Cette exception sera lancé dans les implémentations des méthodes *find* et *findAll* de ChoremService. ChoReg catch uniquement l'exception dans le cas du +findAll pour ne pas bloqué les services qui répondrait aux exigences de type du client. Dans l'autre cas, l'exception est renvoyé au client. + +.. image:: ../schemas/ClassDiagram_Exceptions.png + :alt: Diagramme des Exceptions de ChoReg + +Chaque méthode de ChoReg doit pouvoir potentiellement renvoyés tout ces types d'exceptions en plus du IllegalArgumentException pour le test des paramètres +d'entrée. + +Sécurité +-------- + +Une seule instance de ChoremSecurity possible en même temps, ce qui signifie, une seule application de gestion de sécurité. + +TODO \ No newline at end of file Copied: trunk/src/site/rst/developper/project.rst (from rev 40, trunk/choreg/src/site/rst/developper/project.rst) =================================================================== --- trunk/src/site/rst/developper/project.rst (rev 0) +++ trunk/src/site/rst/developper/project.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,281 @@ +Projet CHOREM Type +================== + +:Author: $Author$ +:Version: 1.3.1 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-05-20* + +Ce document présente une bonne pratique pour la création et l'organisation d'un projet Chorem. +Une bonne partie des outils de base sont définis dans le module Chorem-commons. +Un exemple sera présenté tout au long de ce document pour un projet nommé "Project". + +Architecture Packages +--------------------- + +Pour un souci d'uniformisation, chaque project chorem doit avoir les packages suivant : + +- org.chorem.project.business : Contient la logique métier du projet utilisé par les services. + +- org.chorem.project : Contient les classes de base du projet (ContextUtilProject, ProjectException, ServiceFactory) + +- org.chorem.project.persistence : Contient les classes générées par ToPIA (pouvant être surchargés). + +- org.chorem.project.services : Contient les interfaces correspondant aux services PUBLIC du Projet. + +- org.chorem.project.impl : Contient les implémentations des services. + +- org.chorem.project.dto : Contient les DTO facilitant le transport des entités pour les uis ou les autres projets. + +org.chorem.project.business +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Chaque classe du package sera manipulé de façon statique. Ce package permet de factorisé les actions simples sur les entités. (Aucune manipulation entre services +n'est faites.) + +org.chorem.project +~~~~~~~~~~~~~~~~~~ + +Ce package contient les classes de base nécessaire au projet, notamment le ContextUtilProject qui sert au chargement des properties du projet (config BD ou autre). +Il contient également l'exception qui sera lancé depuis les services (ex : BonzomsException) pour encapsuler tout type d'erreurs depuis les services. + +org.chorem.project.persistence +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ce package sera celui dans lequel les entités du modèle UML devront être placé. Il est possible d'étendre ces entités, +les implémentations seront donc placées dans ce package. + +org.chorem.project.services +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ce package contient uniquement les interfaces des services disponibles pour le projet générés par ToPIA-SOA. Les implémentations seront placées +dans le package org.chorem.project.impl. Les services peuvent utiliser des Helper pour faciliter la gestion des erreurs et factoriser un comportement commun. +Les services manipulent les DTO et les entités (conversions si nécessaire, instanciations des DTO, ...). Les services ne s'appelent pas entre eux pour garder +la transaction courante, plutôt que d'en créer une nouvelle à chaque nouvel appel de méthode d'un service. +Les erreurs à renvoyer au client sont gérés par les services via l'exception du projet ProjectException. (ex : BonzomsException). + +Implémentation type d'une méthode de service :: + + @Override + public void methodName(Params...) throws ProjectException { + TopiaContext transaction = null; + try { + transaction = context.beginTransaction(); + + ... // traitement spécifique à la méthode + + transaction.closeContext(); + } catch (Exception eee) { + ContextUtilProject.serviceException(transaction, message, eee, log); // throws ProjectException + } + } + +La méthode serviceException permet de généralisé le comportement lors d'une erreur. Notamment la fermeture du context si nécessaire. +Une ProjectException encapsulera l'exception qui a été provoqué (ici eee). + +org.chorem.project.dto +~~~~~~~~~~~~~~~~~~~~~~ + +Ce package contient les DTO utilisés pour l'ui ou les autres projets dans les services. Ces DTO sont générés par ToPIA (BeanGenerator). +Pour simplifier la génération d'un DTO, il est possible de le rendre dépendant d'une entité directement depuis le diagramme UML. Cette contrainte implique +la copie des attributs primitifs de l'entité dans le DTO. Les autres attributs spécifiques ou les relations complexes seront à rajouter manuellement sur +le diagramme. Un outil de conversion générique permet la copie automatique des attributs d'une entité dans un DTO (classe Convert de Chorem-commons). La conversion +des autres attributs rajoutés manuellement seront à la charge du développeur. + +Notions à retenir +----------------- + +- Les services ne communiquent pas entre eux : chaque méthode de service manipule une transaction qui sera transmise aux utilitaires ou Helper pour faciliter + le traitement et la gestion des erreurs. + +- Deux niveaux d'utilitaires : ServiceHelper de Chorem-commons et les Helper spécifiques aux entités du projet (ex : ContactHelper). ServiceHelper manipule les + entités via leurs DAO uniquement (Pas de récupération des instances de DAO via le DAOHelper généré par ToPIA). Les autres utilitaires manipulent directement + les transactions. + +- Le ContextUtilProject est indispensable pour chargé les paramètres de connexion à la base de données et créé le context root pour ToPIA. + +- La couche DTO est cachée au client des services. Pas d'instanciation directe. Pas de suffixe DTO. + +- Les services encapsulent les exceptions dans une seule exception propre au projet (ex : BonzomsException). + + +Instanciation des services +-------------------------- + +Via Tapestry-IoC +~~~~~~~~~~~~~~~~ + +L'instanciation des services avec Tapestry est automatique. Ils doivent être "bindé" dans le AppModule:: + + public static void bind(ServiceBinder binder) { + // binder.bind(MyServiceInterface.class, MyServiceImpl.class); + + // Make bind() calls on the binder object to define most IoC services. + // Use service builder methods (example below) when the implementation + // is provided inline, or requires more initialization than simply + // invoking the constructor. + + binder.bind(MyServiceInterface.class, MyServiceImpl.class); + } + ... + } + +Via ChoremRegistry +~~~~~~~~~~~~~~~~~~ + +Les services doivent être enregistrés au démarrage de l'application auprès du `ChoremRegistry`_ : + +.. _ChoremRegistry: ../presentation/api.html + +Maven-dependency:: + + <dependency> + <groupId>org.chorem.choreg</groupId> + <artifactId>choreg</artifactId> + <version>1.0.0</version> + <scope>provided</scope> + </dependency> + +Le scope **provided** est important pour permettre à toutes les applications chorem d'utiliser le même jar 'choreg-1.0.0.jar'. Ce dernier devra être placé +dans le dossier des librairies communes du serveur d'application (à l'instar d'un driver JDBC par exemple). Pour Tomcat 6, il s'agit du dossier **lib**. + +Enregistrement des services:: + + ChoremRegistry registry = ChoremRegistryImpl.getInstance(); + String sid = ChoremConvert.toSid(MyService.class); // Service identifiant via Conversion avec ChoremConvert (inclut dans ChoReg) + registry.register(sid, new MyServiceImpl()); + +Il est possible d'avoir plusieurs implémentation pour un identifiant de service (sid). + +Il y a plusieurs possibilités pour démarrer l'enregistrement au démarrage de l'application. + +Tapestry AppModule +++++++++++++++++++ + +Si l'application possède une interface web avec Tapestry il suffit de créer une classe 'RegisterProjectServices' par exemple qui implémente Runnable. +Dans le AppModule de Tapestry, il faudra ajouter l'instance de cette classe à la méthode contributeRegistryStartup:: + + public static void contributeRegistryStartup(OrderedConfiguration<Runnable> configuration) + { + configuration.add("RegisterServices", new RegisterProjectServices()); + ... + } + +Classe RegisterProjectServices:: + + public class RegisterProjectServices implements Runnable { + + @Override + public void run() { + + // enregistrement des services comme vu précédemment. + } + } + +Note + Si vous voulez lancer votre application sans prise en compte du ChoremRegistry, il suffit de rajouter un try/catch autour de l'ajout à la configuration afin + de catcher une NoClassDefFoundError. + +En ce qui concerne la fermeture il faut utiliser un autre service de Tapestry, RegistryShutdowListener :: + + @EagerLoad // Permet de lancer le build au démarrage de Tapestry + public RegistryShutdownListener buildProjectShutdown(@InjectService("RegistryShutdownHub") RegistryShutdownHub hub) { + RegistryShutdownListener listener = new ContextShutdown(); // Shutdown par defaut (Topia context) + try { + listener = new RegisterProjectServices(); // desenregistrement des services + } catch (NoClassDefFoundError eee) { + // System.out.println("AppModule.buildProjectShutdown() : ChoremRegistry unavailable"); + } + hub.addRegistryShutdownListener(listener); + return listener; + } + +RegisterProjectServices devra implémenter l'interface **RegistryShutdownListener** et sa méthode *registryDidShutdown()*. Quant au ContextShutdown, +il permet de fermer proprement le context ToPIA, il implémente l'interface RegistryShutdownListener et sera utilisé au cas où +le ChoremRegistry n'est pas présent (D'où le catch(NoClassDefFoundError) dans le build ) :: + + public class ContextShutdown implements RegistryShutdownListener { + + private static final Log log = LogFactory.getLog(ContextShutdown.class); // Log Tapestry inutilisable ici (enfin à priori) + + @Override + public void registryDidShutdown() { + try { + ContextUtilProject.closeRootContext(); // appel de la methode closeContext sur le TopiaContext principal. + } catch (BonzomsException eee) { + if (log.isErrorEnabled()) { + log.error("An error occured when closing Topia root context", eee); + } + } + } + + } + +ServletContextListener +++++++++++++++++++++++ + +Si vous voulez rendre indépendant votre module 'business', il lui faut un ServletContextListener et un dossier webapp contenant le fichier web.xml. Ainsi, +il sera possible de déployé le module dans un war pour lui permettre d'être lancé via Tomcat ou un autre serveur d'application. + +Implements ServletContextListener:: + + public class RegisterProjectServices implements ServletContextListener { + + @Override + public void contextInitialized(ServletContextEvent event) { + // enregistrement des services comme vu précédemment. + } + + @Override + public void contextDestroyed(ServletContextEvent event) { + // desenregistrement des services + // fermeture du rootContext ToPIA si existant + } + + } + +Fichier web.xml (dossier src/main/webapp/WEB-INF):: + + <web-app> + ... + <listener> + <listener-class>org.chorem.project.RegisterProjectServices</listener-class> + </listener> + </web-app> + +Note + Il semble important de rajouter un dossier src/main/webapp/META-INF contenant le fichier context.xml avec : + <Context antiJARLocking="true" path="/nom-de-mon-application"/> + Exemple : <Context antiJARLocking="true" path="/bonzoms-business-1.0.0-rc-2-SNAPSHOT"/> + +Il est également possible de combiner les deux méthodes dans une seule classe RegisterProjectServices implémentant les deux interfaces Runnable et ServletContextListener. + +Via ServiceFactory +~~~~~~~~~~~~~~~~~~ + +ServiceFactory propose une implémentation de base pour les services et peut-être étendu. + +:: + + public abstract class ServiceFactory { // A créer dans votre projet-business + + public MyService getNewMyService() { + return new MyServiceImpl(); + } + } + + public class myServiceFactory extends ServiceFactory { // A créer dans votre projet-client (ou ui) + ... + } + +:: + + ServiceFactory services = new myServiceFactory(); + MyService service = services.getNewMyService(); + +Résultat : + Une seule instanciation globale au projet au lieu d'une par service. + Permet l'extension des services via d'autres implémentations. + Copied: trunk/src/site/rst/developper/todo.rst (from rev 40, trunk/choreg/src/site/rst/developper/todo.rst) =================================================================== --- trunk/src/site/rst/developper/todo.rst (rev 0) +++ trunk/src/site/rst/developper/todo.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,9 @@ + +Documentation : +- Security +- FAQ +- Filtres + +Developpement : +- Filtres +- Sécurité \ No newline at end of file Copied: trunk/src/site/rst/index.rst (from rev 40, trunk/choreg/src/site/rst/index.rst) =================================================================== --- trunk/src/site/rst/index.rst (rev 0) +++ trunk/src/site/rst/index.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,79 @@ +Introduction +============ + +ChoReg permet la communication entre les différentes applications Chorem (Bonzoms, Ca$h, JTimer, Pollen, ...). + +Vous trouverez dans cette documentation : + +- Présentation + + * `Contexte et Objectif`_ de ChoReg + * `Definitions et Api`_ de ChoReg (diagramme de classes des interfaces disponibles dans ChoReg) + +- Utilisateur + + * Premiers pas (Getting Started) pour bien commencer avec ChoReg + * Description du `deploiement`_ des applications Chorem et de ChoReg (détails sur comment gérer l'enregistrement/désenregistrement des services au démarrage et + à l'arrêt). + * `Bonnes pratiques`_ d'utilisation de ChoReg et d'implémentations des services qu'il manipule. + * `FAQ`_ (Foire Aux Questions) + * Détails sur la `securite`_ dans ChoReg (utilisation d'une application gérant la sécurité) + * Détails sur les `filtres`_ possibles dans l'utilisation des méthodes de ChoReg + * Description des `formats`_ disponibles et manipulés dans les différentes applications Chorem (Référence de tous les types pour les échanges) + +- Développeur + + * Organisation d'un `projet Chorem type`_ + * Détails sur l'implémentation de `ChoremRegistryImpl`_ + * `TODO`_ + +- Recherche (anciens documents avec création de ChoReg) + + * Description de certains projets `Apache`_ + * Etude sur la `modularite`_ et les différentes technologies existantes pour la création/amélioration de ChoReg + * Etude d' `OSGi`_ avec essais et résultats obtenues + * `Premier document d'architecture`_ pour ChoReg avec étude des communications entre les applications Chorem + * Première ébauche de `specifications`_ pour ChoReg + +- Stage (dans l'optique de créer ChoReg) + + * `Sujet du stage`_ proposé par Code Lutin + * `Comptes rendus`_ d'avancement pendant le stage (étapes de recherche, création de Bonzoms, étude de Tapestry, contributions à ToPIA / EUGene, ...) + +.. _Contexte et Objectif: presentation/presentation.html + +.. _Definitions et Api: presentation/api.html + +.. _Premiers pas: user/start.html + +.. _deploiement: user/deployment.html + +.. _FAQ: user/faq.html + +.. _Bonnes pratiques: user/best_practices.html + +.. _securite: user/security.html + +.. _filtres: user/filters.html + +.. _projet Chorem type: developper/project.html + +.. _ChoremRegistryImpl: developper/details.html + +.. _TODO: developper/todo.html + +.. _Apache: recherche/apache.html + +.. _modularite: recherche/technos.html + +.. _OSGi: recherche/osgi.html + +.. _Premier document d'architecture: architecture/archi_chorem_part1.html + +.. _specifications: architecture/archi_chorem_part2.html + +.. _Sujet du stage: stage/sujet.html + +.. _Comptes rendus: stage/recapitulatif.html + + Copied: trunk/src/site/rst/presentation/api.rst (from rev 40, trunk/choreg/src/site/rst/presentation/api.rst) =================================================================== --- trunk/src/site/rst/presentation/api.rst (rev 0) +++ trunk/src/site/rst/presentation/api.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,235 @@ +API de ChoReg +============= + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-05* + +Voici les différentes classes et interfaces incluse dans le jar de ChoReg : + +.. image:: ../schemas/ClassDiagram_ChoReg_API.png + :alt: Classes de ChoReg + +.. contents:: Contenu + +Les fournisseurs de services +---------------------------- + +Cette partie définie les interfaces que doivent utiliser les fournisseurs de services pour proposer aux autres applications leurs données. + +Fournisseurs de services connus : + +- Bonzoms : + + * org.chorem.bonzoms.services.ServicePerson : format xPIL, service UI + * org.chorem.bonzoms.services.ServiceOrganization : format xPIL + +ChoremUIService ++++++++++++++++ + +Cette interface permet à une application d'enregistrer des services d'interface utilisateur auprès de ChoReg. Ces services permettent de récupérer des adresses +url pour l'affichage des données, que ce soit un élément, une liste d'éléments ou le formulaire d'ajout/modification de l'élément. Cette url correspond +majoritairement à une interface web d'une application. Le but de l'interface est de communiquer à travers ChoReg les url permettant de visualiser certaines données. + +Exemple : Ca$h veut afficher la fiche d'une personne (considéré comme une référence), il va pouvoir demander à ChoReg l'url pour cette personne via la méthode +*findViewUrl* en lui donnant le choremUri de la personne (voir `presentation`_ pour la description du choremUri). A l'affichage, l'utilisateur pourra cliquer sur +le lien via Ca$h pour afficher la fiche de la personne directement dans Bonzoms (qui contient les données de la personne). + +.. _presentation: presentation.html + +findFormUrl +~~~~~~~~~~~ + +Cette méthode permet de récupérer l'url du formulaire d'ajout/modification d'un élément. + +Paramètres : + +- String entityId : identifiant de l'élément (principalement un topiaId) + +Retour : + +- String url : url du formulaire d'ajout/modification d'un élément. + +findListUrl +~~~~~~~~~~~ + +Cette méthode permet de récupérer l'url d'une liste d'éléments. + +Paramètres : + +- String filters : filtres pour l'affichage des données de la liste (TODO) + +Retour : + +- String url : url de la liste d'éléments + +findViewUrl +~~~~~~~~~~~ + +Cette méthode permet de récupérer la fiche descriptive d'un élément. + +Paramètres : + +- String entityId : identifiant de l'élément (principalement un topiaId) + +Retour : + +- String : url de la fiche descriptive de l'élément + +ChoremService ++++++++++++++ + +Cette interface permet à une application d'enregistrer ses services de manipulation des données auprès de ChoReg. Le but étant de proposer à d'autres applications +certains formats de données intéressants pour le partage d'informations. L'application cliente, demandeuse auprès de ChoReg, pourra choisir entre récupérer +une liste d'éléments ou un élément. L'interface propose un et un seul format de donnée. Si un service peut potentiellement en proposer plusieurs, plusieurs +implémentations devront être faites de ce service, une par format. (Voir `format`_ pour plus de détails à ce sujet). + +Exemple : Ca$h demande à ChoReg l'ensemble des données répondant au format XML xPIL (standard OASIS CIQ). ChoReg renverra les données provenant de toutes les +applications proposant ce format. Bonzoms propose deux services répondant à ce format, ServicePerson et ServiceOrganization. Ces deux services seront interpellés +par ChoReg pour la récupération des données demandées par Ca$h. + +.. _format: ../user/formats.html + +getFormat +~~~~~~~~~ + +Cette méthode permet d'identifier précisémment le format manipuler par le service. + +Retour : + +- String : nom du format manipuler par le service + +find +~~~~ + +Cette méthode permet de retourner un et un seul élément du type passé en paramètre. Le type doit être une classe Java inclut dans la JDK 1.6. +Le type sera majoritairement un flux (Stream), que ce soit XML ou autre. + +Paramètres : + +- Class<T> returnType : classe du type de retour souhaité par le client +- String entityId : identifiant de l'élément à retourner (principalement un topiaId) + +Retour : + +- T : objet correspondant à l'élément souhaité par le client + +findAll +~~~~~~~ + +Cette méthode permet de retourner une liste d'élément du type passé en paramètre. Le type doit être une classe Java inclut dans la JDK 1.6. +Le type sera majoritairement un flux (Stream), que ce soit XML ou autre. + +Paramètres : + +- Class<T> returnType : classe du type de retour souhaité par le client +- String filters : filtres à appliquer à la liste d'éléments (TODO) + +Retour : + +- List<T> : Liste d'objets correspondant au type souhaité par le client + +getShowText +~~~~~~~~~~~ + +Texte pour affichage du service dans une interface utilisateur (principalement une liste déroulante). + +Retour : + +- String : nom court du service (ex: Person pour org.chorem.bonzoms.services.ServicePerson) + +ChoremSecurity +++++++++++++++ + +Cette interface permet à l'application de gestion de la sécurité de s'enregister auprès de ChoReg. Cette application doit impérativement manipulé des +choremUri, sid, entityType, topiaId (voir `presentation`_ pour leurs descriptions) pour permettre une meilleure gestion des droits d'accès. + +Deux idées pour les identifiants utilisateurs : + +- token (jeton) généré aléatoirement suivant la session de connexion (timeout possible) +- topiaId de l'utilisateur enregistré en base dans l'application de sécurité + +connect +~~~~~~~ + +Connexion d'un utilisateur, vérification des login/password, création d'une session de connexion. + +Paramètres : + +- CryptedUser user : Utilisateur avec données cryptés (login et password) + +Retour : + +- String : identifiant de l'utilisateur nécessaire à la validation (identifiant transmis aux applications clientes de ChoReg) + +validate +~~~~~~~~ + +Validation d'un uri pour un utilisateur connu (et connecté). + +Paramètres : + +- String userId : identifiant de l'utilisateur connecté +- String uri : choremUri à tester +- writeAccess : accès en droit d'écriture ou non (pour les formulaires) + +Retour : + +- boolean : true si la validation a été effectué, false sinon + +Exceptions : + +- TimeoutException : session de connexion terminé ou userId inconnu +- IllegalArgumentException : paramètres incorrects (uri indéchiffrable) + +Les utilisateurs de choreg +-------------------------- + +Cette partie définie le ChoReg en lui même et toutes ses méthodes d'accès. + +Utilisateurs de choreg connus : + +- Ca$h : format xPIL + +ChoremRegistry +++++++++++++++ + +Le ChoremRegistry est l'interface principale de communication entre les applications et ChoReg. Deux parties distinctes sont proposés, une pour +les fournisseurs de services (enregistrement/desenregistrement des services) et une pour les utilisateurs de services (demande des données, urls, accès +utilisateur). Les demandes utilisent toujours l'identifiant de l'utilisateur et potentiellement une choremUri pour l'accès à un seul élément. + +Sécurité +~~~~~~~~ + +Une méthode permet la demande d'identifiant d'un utilisateur, la méthode findUserId prend en paramètre un CryptedUser comprenant le login et password +cryptés de l'utilisateur demandant un identifiant d'accès. + +Register/Unregister +~~~~~~~~~~~~~~~~~~~ + +Enregistrement et désenregistrement auprès de ChoReg. Trois méthodes : 2 register (une UI, une Service) et l'autre unregister. (Voir diagramme plus haut) +Le même identifiant est valable pour une ui et pour un service et toutes ses implémentations. Il est d'ailleurs fortement conseillé d'utiliser le même identifiant +pour chaque implémentation (ui ou format distinct) d'un même service. + +Ex : ServicePerson possède deux implémentations pour le même identifiant org.chorem.bonzoms.services.ServicePerson : + +- ServiceUIPerson implements ChoremUIService +- ServicePersonXPIL implements ChoremService + +Demande d'URL vers UI (interface utilisateur) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Les méthodes findFormUrl, findListUrl et findViewUrl permettent la demande d'url. Ce sont les mêmes que dans l'interface ChoremUIService avec identifiant +de l'utilisateur en plus. + +Demande de données +~~~~~~~~~~~~~~~~~~ + +Les méthodes findAll et find permettent la demande des données. Ce sont les mêmes que dans l'interface ChoremService avec en plus, l'identifiant de l'utilisateur +et le nom du format souhaité. + +Pour simplifier l'affichage des services disponibles auprès d'une UI (Ex: Ca$h demande les services manipulant du xPIL), une méthode permet de simplement +listés les noms des services manipulant un certain format : findFormatSupportedServiceTitles. \ No newline at end of file Copied: trunk/src/site/rst/presentation/definitions.rst (from rev 40, trunk/choreg/src/site/rst/presentation/definitions.rst) =================================================================== --- trunk/src/site/rst/presentation/definitions.rst (rev 0) +++ trunk/src/site/rst/presentation/definitions.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,35 @@ +Definitions +=========== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-04* + +ChoReg +------ + +SID +--- + +ChoremUri +--------- + +TopiaId +------- + +ChoremService +------------- + +ChoremUIService +--------------- + +ChoremSecurity +-------------- + + + + + Copied: trunk/src/site/rst/presentation/presentation.rst (from rev 40, trunk/choreg/src/site/rst/presentation/presentation.rst) =================================================================== --- trunk/src/site/rst/presentation/presentation.rst (rev 0) +++ trunk/src/site/rst/presentation/presentation.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,117 @@ +Présentation de ChoReg +====================== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-04* + +Contexte initial +---------------- + +Avant la création de ChoReg, Chorem regroupait en un seul projet la gestion des personnes, sociétés, ressources humaines, gestion de projet, trésorerie. +D'autres applications étaient présent au sein du même projet Chorem sur le site du labs de libre-entreprise. Afin de rendre indépendant chacune des applications, +Chorem est devenu le nom d'une forge regroupant l'ensemble des applications de gestion d'entreprise. + +Les applications existantes avant migration sur chorem.org : + +- `JTimer`_ : Gestion du temps passé sur des tâches +- `Callao/Lima`_ : Gestion comptable +- `Pollen`_ : Application de vote +- Chorem : Gestion d'entreprise, ressources humaines, trésorerie, gestion de projet + +Les applications JTimer, Pollen et Callao/Lima ont été migrés sur chorem.org. +Le projet Chorem quant à lui, n'est plus. Il a été scindé en plusieurs applications indépendantes sur chacune des notions utiles à la gestion d'entreprise : + +- Gestion de projet : Gepeto (TODO) +- Gestion des personnes, sociétés et contacts : `Bonzoms`_ +- Gestion des ressources humaines +- Gestion calendrier/agenda +- Gestion de la trésorerie : `Ca$h`_ +- Gestion des factures +- Gestion des communications +- Gestion de la sécurité (droits d'accès) + +.. _JTimer: http://maven-site.chorem.org/jtimer + +.. _Callao/Lima: http://maven-site.chorem.org/callao + +.. _Pollen: http://maven-site.chorem.org/pollen + +.. _Bonzoms: http://maven-site.chorem.org/bonzoms + +.. _Ca$h: http://maven-site.chorem.org/cash + +Contraintes +----------- + +Chacune des applications Chorem doit fonctionner indépendemment des autres. Cependant, les permettrent de communiquer entre elles est indispensable. En effet, +il est important de visualiser les projets et tâches sur un calendrier, de connaître les entrées de trésorerie dans la comptabilité, et de manipuler des personnes +dans les ressources humaines ou les communications. Ces différentes relations n'ont pas toujours le même but et la même façon d'intéragir. Les besoins de l'affichage ne +sont pas les mêmes que ceux de la base de données. Il est donc difficile d'utiliser une méthode unique pour chacun de ces cas d'intéractions. + +Idée de ChoReg +-------------- + +L'idée de ChoReg est de centraliser toutes les interactions entre les différentes applications. Elles ne seront pas directement connectés les unes aux autres mais +uniquement à ChoReg. ChoReg est un registre de services. Chacune des applications voulant partager ses données enregistrera ses services auprès de ChoReg. De l'autre +côté, une application désireuse d'utiliser certains types de données, demandera leurs existances auprès de ChoReg. + +Cas d'utilisations : + +.. image:: ../schemas/UseCaseDiagram_ChoReg.png + :alt: Cas d'utilisations de ChoReg + +Deux types de services +---------------------- + +Il a été mis en place deux types de services : + +- ChoremService : permet la sélection de données suivant un format ou un identifiant spécifique +- ChoremUIService : permet la sélection des urls permettant d'afficher des données + +Une application Chorem est décomposé en deux modules distincts : + +- business : gestion métier, connexion avec la base de données, possible utilisation de ToPIA et Hibernate pour la persistance +- ui : interface utilisateur, client lourd (Swing, ...) ou client léger (GWT, Tapestry, ...) + +Chaque type de service répond donc au besoin de chacun des deux modules principaux d'une application Chorem. + +Demande par format ou identifiant +--------------------------------- + +Deux types de demande sont possibles : + +- Format : une application nécessite l'enregistrement d'un certain type de donnée (format), généralement standard pour permettre l'interopérabilité avec d'autres applications. +- Identifiant : une application connait l'identifiant de la donnée à récupérer. + +Une application Chorem peut donc demander à ChoReg une donnée dans un format ou avec un identifiant donné. + +Voir `documentation`_ pour plus de détails sur les formats. + +.. _documentation: ../user/formats.html + +Norme pour l'identifiant +------------------------ + +Un identifiant Chorem est un uri, appelé **choremUri**. Il est composé de deux identifiants importants, celui du service, appelé **sid** et celui de l'entité qui l'identifie. +Le service correspond à l'interface permettant la manipulation des données et l'entité correspond à une donnée (généralement enregistré en base de données). Les applications +Chorem utilise le framework ToPIA qui définit une norme pour l'identifiant de chacune des entités : il s'agit du nom complet de la classe de l'entité + une partie numérique codé. + +Exemples : + +- sid : org.chorem.bonzoms.services.ServicePerson +- entityType : org.chorem.bonzoms.persistence.PersonEntity +- topiaId : org.chorem.bonzoms.persistence.PersonEntity#1246900056944#0.26595214137921097 +- choremUri : org.chorem.bonzoms.services.ServicePerson://org.chorem.bonzoms.persistence.PersonEntity#1246900056944#0.26595214137921097 + +Ainsi un choremUri est quasimment toujours unique. Il est important d'utiliser cette uri comme source de chaque donnée qui transite via ChoReg. + +Note + Une classe de conversion, *ChoremConvert*, est contenue dans le jar choreg pour effectuer les différentes conversion d'identifiants (sid, topiaId, choremUri) + +Vous pouvez désormais vous rendre sur la partie `api`_ de ChoReg pour plus de détails sur son contenu. + +.. _api: api.html \ No newline at end of file Copied: trunk/src/site/rst/recherche/apache.rst (from rev 40, trunk/choreg/src/site/rst/recherche/apache.rst) =================================================================== --- trunk/src/site/rst/recherche/apache.rst (rev 0) +++ trunk/src/site/rst/recherche/apache.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,183 @@ +============== +Projets Apache +============== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-05-20* + +Dans le monde de l'Open-Source il est indéniable de parler d'`Apache`_ comme une référence. De nombreux projets existent +pour le large panel de toutes les technologies existantes (pour Java ou non). Ce document permet de référencer quelques +projets Apache intéressants dans la conception d'applications et plus particulièrement intéressants pour la conception de +CHOREM. + +.. _Apache: http://en.wikipedia.org/wiki/Apache_Software_Foundation + +Architecturals Frameworks +========================= + +ActiveMQ +-------- + +Implémentation de la spécification `JMS`_ (Java Message Service) de Sun. (Message Broker) + +.. _JMS: http://java.sun.com/products/jms/ + +Site référence : http://activemq.apache.org/ + +QPid +---- + +Implémentation de la spécification `AMQP`_ (Advanced Message Queuing Protocol) qui est un protocole de messagerie. + +.. _AMQP: http://jira.amqp.org/confluence/display/AMQP/Advanced+Message+Queuing+Protoc... + +Site référence : http://qpid.apache.org/ + +Camel +----- + +Framework d'intégration de logiciel basé sur les Enterprise Integration Patterns. + +Site référence : http://camel.apache.org/ + +CXF +--- + +Framework de services, notamment les Web Services `JAX-WS`_ avec l'utilisation de `SOAP`_. + +.. _JAX-WS: https://jax-ws.dev.java.net/ + +.. _SOAP: http://fr.wikipedia.org/wiki/SOAP + +Site référence : http://cxf.apache.org/ + +**XML** + +Felix +----- + +Implémentation de la spécification `OSGi`_ (Framework à base de composants ayant un cycle de vie contrôlé). + +Site référence : http://felix.apache.org/ + +.. _OSGi: http://www.osgi.org/Main/HomePage + +**ANNOTATIONS / XML** + +ServiceMix +---------- + +Implémentation de la spécification `JBI`_ via un `ESB`_. Supporte également l'`OSGi`_. + +.. _JBI: http://fr.wikipedia.org/wiki/Java_Business_Integration + +.. _ESB: http://fr.wikipedia.org/wiki/Enterprise_Service_Bus + +Site référence : http://servicemix.apache.org/ + +**XML** + +Synapse +------- + +Autre serveur basé sur `ESB`_. + +Site référence : http://synapse.apache.org/ + +**XML** + +Server Applications +=================== + +Tomcat +------ + +Conteneur de Servlet. + +Site référence : http://tomcat.apache.org/ + +Geronimo +-------- + +Serveur d'applications JEE. Equivalent à JBoss, JOnAS, ... + +Site référence : http://geronimo.apache.org/ + +Apache +------ + +Serveur HTTP. + +Site référence : http://httpd.apache.org/ + + +Build/Configuration Tools +========================= + +Ant +--- + +Outil permettant de gérer le cycle de construction d'un projet (build, install, package, ...). + +Site référence : http://ant.apache.org/ + +**XML** + +Maven +----- + +Maven est un peu plus performant qu'Ant notamment par le fait qu'il inclut une gestion des dépendances entre +librairies situés sur un ou plusieurs repository distants. + +Site référence : http://maven.apache.org/ + +**XML** + +Web Application Frameworks +========================== + +Tapestry +-------- + +"Convention over Configuration", voilà qui pourrait résumé Tapestry qui n'utilise aucune configuration XML contrairement +à de nombreux concurrents dans le domaine d'application Web (comme Struts). Tapestry possède son propre moteur de template +(ce qui implique de nouvelles balises pour la création des templates) ainsi qu'un moteur d'injection de dépendance propre +(Tapestry-IoC) qui constitue son centre nerveux. + +Site référence : http://tapestry.apache.org/ + +**ANNOTATIONS** + +Wicket +------ + +Site référence : http://wicket.apache.org/ + +Struts +------ + +Contrairement à Tapestry, Struts est basé sur des fichiers de configuration XML dans le but de lier les Servlet (Contrôleurs), +aux JSP (Vues). + +Site référence : http://struts.apache.org/ + +**XML** + +Miscellaneous +============= + +Velocity +-------- + +Moteur de template. + +Site référence : http://velocity.apache.org/ + +Velocity Engine : http://velocity.apache.org/engine/index.html + + + Copied: trunk/src/site/rst/recherche/osgi.rst (from rev 40, trunk/choreg/src/site/rst/recherche/osgi.rst) =================================================================== --- trunk/src/site/rst/recherche/osgi.rst (rev 0) +++ trunk/src/site/rst/recherche/osgi.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,282 @@ +================== +Utilisation d'OSGi +================== + +:Author: $Author$ +:Version: 1.2 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-05-20* + +Le framework `OSGi`_ implémente un modèle de composants dynamique et complet, comblant un manque dans +les environnements Java/VM traditionnels. Les applications et composants (se trouvant sous la forme de +**bundles** pour le déploiement) peuvent être installés, arrêtés, démarrés, mis à jour et désinstallés de +manière distante sans nécessiter de redémarrage ; la gestion des classes/paquetages Java est spécifiée de +manière très détaillée. + +.. _OSGi: http://fr.wikipedia.org/wiki/OSGi + +Apache Felix +============ + +`Apache Felix`_ est une implémentation du framework OSGi. Il définit les éléments fondamentaux de la spécification, +comme l'**OBR** (**O**SGi **B**undle **R**epository) et le **SCR** (**S**ervice **C**omponent **R**untime). Il propose +également d'autres services pour facilité l'implémentation et la manipulation des bundles comme les `iPOJO`_. + +.. _Apache Felix: http://felix.apache.org/site/index.html + +.. _iPOJO: http://felix.apache.org/site/apache-felix-ipojo.html + +Apache Felix Karaf +------------------ + +Nous allons nous intéresser au sous-projet `Karaf`_, d'Apache Felix (utilisé comme Kernel de +`ServiceMix`_). Ce serveur OSGi permet une manipulation plus simple et plus complète des +bundles, notamment par l'apport d'un chargement automatique des fichiers de configurations et des bundles directement dans un dossier. +Il permet également de créer des sous-serveurs (instances) configurables comme environnement de déploiement spécifique pour un +projet (et/ou utilisateur). + +.. _Karaf: http://felix.apache.org/site/apache-felix-karaf.html + +.. _ServiceMix: http://servicemix.apache.org/home.html + +Console (Shell) +~~~~~~~~~~~~~~~ + +La commande help est indispensable et indique toutes les `commandes disponibles +<http://felix.apache.org/site/41-commands.html>`_. Des sous-modules de commandes existent +pour la manipulation de l'environnement OSGi : + +- packages : Liste des packages chargés (importés et exportés). + +- osgi : Environnement OSGi proprement dit. Toutes les commandes connues sont présentes (install, start, stop ...). + +- admin : Gestion du cycle de vie du serveur. + +- features : Gestion des features et leurs repository. + +- config : Gestion des fichiers de configuration du serveur. + +- log : Gestion des logs du serveur. + +- obr : Gestion des OBR (feature à installer). + +Création d'une instance de serveur : + +> admin/create ${mondir} + +Le serveur crééra automatiquement un environnement nouveau (avec bundles par défauts de ServiceMix) dans +${karafdir}/bin/instances/${mondir} avec les dossiers nécessaires (etc, deploy, ...) + +Dossiers du serveur +~~~~~~~~~~~~~~~~~~~ + +Le dossier où sont situés les fichiers de configuration du serveur est le dossier *etc*: + +- config.properties : Configurations principales (paramètres du framework OSGi, paramètres de servicemix/karaf, ...) + +- org.apache.servicemix.features.cfg : Configurations des features (notamment les repository de features) + +- org.ops4j.pax.url.mvn.cfg : Configuration des repository maven + +- org.ops4j.pax.logging.cfg : Configuration des log (équivalent au log4j.properties qui ne sera pas visible) + +TODO: description des autres fichiers + +Le dossier où peuvent être déployés les jars et features est le dossier *deploy*. + +Le dossier *data/cache* contient les bundles chargés (peut être supprimé pour réinitialiser le serveur). + +Modularité de CHOREM +==================== + +Un point essentiel du déploiement d'applications CHOREM est leurs chargements à chaud et leurs dépendances entre eux. +Le framework OSGi permet ainsi de configurer les jar pour qu'ils communiquent entre eux et se chargent automatiquement. +Chaque projet (et même module de projet) est considéré comme un bundle. C'est à dire une entité indépendante (jar) qui fournit +et utilise des services d'autres bundles. Par exemple pour le projet People : People-Business fournit des services de manipulation +des personnes et sociétés qui seront utilisés par People-Ui pour la couche présentation. Le projet WorkEffort aura également +besoin de manipuler des personnes pour la gestion de projet. Ce dernier doit cependant être indépendant si le bundle People-Business +n'existe pas dans l'environnement de déploiement. Felix et plus généralement OSGi permettent de détecter l'existance ou non +de bundle nécessaire au bon fonctionnement. Ces derniers peuvent être indispensables ou optionnels (ce qui est le cas pour People-Business dans +WorkEffort). Il va cependant être nécessaire de définir ces dépendances et ces intéractions. + +Intégration dans MAVEN +---------------------- + +Un plugin maven existe pour la génération automatique de bundle. Un bundle, selon la spécification OSGi, doit définir un fichier +de manifest complet (décrit par le fichier *META-INF/MANIFEST.MF*) pour être considéré comme un bundle. Les possibilités étant nombreuses (voir `documentation +<http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html>`_) nous allons vous présenter un exemple (people-business) :: + + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <version>2.0.0</version> + <extensions>true</extensions> + <configuration> + <instructions> + <Export-Package> + org.chorem.people.services, + org.chorem.people.dto, + org.chorem.people.persistence + </Export-Package> + <Private-Package> + org.chorem.people.* + </Private-Package> + </instructions> + </configuration> + </plugin> + +Version inclut dans chorem-commons :: + + <!-- Felix Bundle plugin --> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <version>2.0.0</version> + <extensions>true</extensions> + <configuration> + <instructions> + <Export-Package> + org.chorem.utils, + <!-- Export des librairies nuiton (ToPIA, EUGene, NuitonUtil) --> + org.nuiton.*, + <!-- Export commons-primitives (bundle inexistant) --> + org.apache.commons.collections.primitives.* + </Export-Package> + <Embed-Dependency> + topia-persistence, + nuitonutil, <!-- Used by topia-persistence --> + eugene, <!-- Used by topia-persistence --> + commons-primitives <!-- Used by eugene --> + </Embed-Dependency> + </instructions> + </configuration> + </plugin> + +Descriptions: + +- <Export-Package>: définit les packages à exporter (services) + +- <Import-Package>: tous les packages à inclure au bundle (y compris ceux exporter) + +- <Private-Package>: packages à ne pas inclure + +- <DynamicImport-Package>: packages à inclure dynamiquement + +- <Embed-Dependency>: librairies à copier dans le bundle (ici ce sont des librairies qui n'existent pas en bundle). + Elles sont présentes dans les dépendances du POM. Les noms indiqués sont les artifactId. + +- <Require-Bundle>: bundles indispensables à l'execution du bundle + +La présence de Topia implique de nombreuses dépendances (notamment à cause d'hibernate) qui devront obligatoirement être +fournies. Elles ne sont pas précisés ici car existent en tant que bundle. Certaines librairies courantes sont par défaut +des bundles (donc dans le maven repository central), comme commons-lang. D'autres doivent être téléchargés sur différents +repository de bundles (`SpringSource`_,`OSGi OBR`_,`ou ServiceMix`_, ...). Le problème étant que beaucoup de librairies ne sont pas +encore normalisées en tant que bundle, ceci implique des interprétations différentes du contenu du MANIFEST.MF. Il est +possible de *wrapper* des librairies existantes en tant que bundle pour faciliter leur inclusion (Non testé, semble peu fiable). +Le problème des dépendances et de la gestion automatique des chargements est en cours de développement. Quelques solutions existent... + +.. _SpringSource: http://www.springsource.com/repository/app/ + +.. _OSGi OBR: http://www.osgi.org/Repository/HomePage + +.. _ou ServiceMix: http://servicemix.apache.org/SMX4/bundles-repository.html + +Gestion des dépendances +----------------------- + +OBR +~~~ + +L'OBR d'OSGi permet de stocker et de référencer un ensemble de bundles, ceci à l'aide d'un simple fichier xml. +Au chargement d'un bundle dans l'environnement de déploiement, les dépendances existantes dans l'OBR (ou les OBR) seront +automatiquement téléchargés. Il est nécessaire de préciser l'ensemble des bundles nécessaires dans le fichier xml +pour que l'OBR trouvent les dépendances (Voir `documentation +<http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html>`_). + +L'OBR est différent du repository maven car tout doit être écrit dans le fichier xml pour qu'il connaisse toutes les dépendances +entre bundles. Un outil créé par Peter Kriens (grand acteur dans le domaine OSGi) nommé `Bindex +<http://www.osgi.org/Repository/BIndex>`_ permet de facilement créé un OBR. +En l'utilisant sur un repository maven, il parcourt tout les Jar pour trouver les MANIFEST.MF et inclut les informations relatives +aux bundles dans le fichier repository.xml (OBR). Cependant même les jar qui ne sont pas des bundles sont inclus. Le programme est libre, +une modification à ce niveau serait intéressante ?? + +Karaf inclut la gestion de plusieurs OBR dans son Shell (il faut préalablement installé le feature obr). Grâce au fichier de configuration +du serveur OSGi (config.properties), il est possible de lui préciser les url des OBR (file:/... , http://... , ...) : + +**obr.repository.url**=http://svn.apache.org/repos/asf/servicemix/smx4/obr-repo/repository.xml \ +http://felix.apache.org/obr/releases.xml \ +file:/var/local/m2repo/repository.xml + +Attention + Karaf semble avoir du mal à gérer les rafraichissements des bundles provenant de l'OBR automatiquement... + +Note + Le plugin maven précédemment présenté ajoute automatiquement le bundle créé dans un fichier repository.xml à l'emplacement + d'installation du jar (repository maven local). + +Features +~~~~~~~~ + +Les `features +<http://felix.apache.org/site/46-provisioning.html>`_ sont un ajout de Karaf pour faciliter la gestion des dépendances entre bundles. A l'instar de l'OBR, les features +sont indiqués dans un fichier features.xml qui servira de repository aux features et devra être inclut à Karaf (via un fichier de config +ou la console). Il est ainsi possible d'indiquer un ensemble de dépendances pour un bundle:: + + <feature name='hibernate' version='3.3.1.GA'> + <bundle>mvn:commons-collections/commons-collections/3.2.1</bundle> + <bundle>...</bundle> + <bundle>file:/home/desbois/bundles/hibernate-3.3.1.GA/com.springsource.org.hibernate-3.3.1.GA.jar</bundle> + </feature> + <feature name='chorem-commons' version='1.0'> + <feature version='1.0'>eugene</feature> + <feature version='3.3.1.GA'>hibernate</feature> + <bundle>...</bundle> + <bundle>mvn:org.chorem/chorem-commons/1.0.0-SNAPSHOT</bundle> + </feature> + +L'utilisation d'une URL tel que mvn: est très partique, permettant d'indiquer l'utilisation d'un bundle présent dans un repository +maven. Les repository maven peuvent être indiqués dans les fichiers de configurations du serveur (org.ops4j.pax.url.mvn.cfg) : + +**org.ops4j.pax.url.mvn.repositories**=file:${servicemix.base}/system@snapshots,file:${user.home}/.m2/repository@snapshots,http://repo1.maven.org/maven2, +http://people.apache.org/repo/m2-snapshot-repository@snapshots@noreleases, +http://svn.apache.org/repos/asf/servicemix/m2-repo,http://lutinbuilder.labs.... + + +Note + Les développeurs de Karaf (ServiceMix Kernel) sont en train de simplifier l'utilisation des features et de créer un + plugin maven permettant l'ajout automatique des dépendances et liens des bundles dans un features.xml (les dépendances + doivent cependant être nécessairement indiqués manuellement, y compris celles transitives(??)). + +Solution ? +~~~~~~~~~~ + +Les features semblent être plus puissants que l'OBR, notamment grâce aux liens avec les repository maven. Il faut néanmoins +déclencher l'installation d'un feature manuellement (comme pour un bundle ceci-dit). + +Problèmes rencontrés +-------------------- + +- Difficulté de mise en place des dépendances dû aux librairies non normalisés en tant que bundle. + +- Problème avec utilisation du bundle H2 pour la base de données (la classe org.h2.Driver + est introuvable au moment de l'éxecution d'Hibernate. Hibernate, H2 et Chorem sont dans des bundles distincts + avec des classloaders distincts. Hibernate ne connaît pas H2 même si ce dernier est importé dans Chorem. + Solution : mettre les bundles en "buddy" avec Equinox (non implémenté dans Felix) ou équivalent, DynamicImport-Package * à placer dans Hibernate...) + +- Rendre compatible Tapestry et OSGi avec Jetty comme serveur d'application facilement intégré dans Apache Felix + +Travail à fournir +----------------- + +- Transformation des librairies lutins en bundle (ToPIA, EUGene, ...) + +- Créer un nouveau bundle pour gestion d'hibernate avec DynamicImport + +- Etudier `Tapestry-OSGi`_ récemment créé indépendamment du projet Apache (Problèmes: framework OSGi différent + (`Equinox`_), utilisation massive d'Eclipse et de Spring...) + +.. _Tapestry-OSGi: http://groups.google.fr/group/tapestry-osgi + +.. _Equinox: http://www.eclipse.org/equinox/ Copied: trunk/src/site/rst/recherche/technos.rst (from rev 40, trunk/choreg/src/site/rst/recherche/technos.rst) =================================================================== --- trunk/src/site/rst/recherche/technos.rst (rev 0) +++ trunk/src/site/rst/recherche/technos.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,127 @@ +========================= +Recherche & Développement +========================= + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-05-20* + +Contraintes sur Architecture CHOREM +=================================== + +Chorem est un `ERP`_ (Enterprise Resource Planning) composé de plusieurs sous-projets : + - Gestion de projet + - Gestion des personnes/sociétés + - Ressources humaines + - Comptabilité (Factures, Trésorerie, ...) + - Application de vote (`Pollen`_) + - Autres... + +Chaque sous-projets doit être indépendant et peut s'utiliser seul. Cependant la présence de plusieurs +sous-projets sur une même plate-forme de déploiement leur permet de communiquer entre eux pour rendre +l'application plus riche et complète. Il existe différentes solutions dans le monde Java pour aboutir +à cette modularité. + +.. _ERP: http://fr.wikipedia.org/wiki/Progiciel_de_gestion_int%C3%A9gr%C3%A9 + +.. _Pollen: http://chorem.org/projects/show/pollen + +OSGi +==== + +Le framework OSGi implémente un modèle de composants dynamique et complet, comblant un manque dans +les environnements Java/VM traditionnels. Les applications et composants (se trouvant sous la forme de +**bundles** pour le déploiement) peuvent être installés, arrêtés, démarrés, mis à jour et désinstallés de +manière distante sans nécessiter de redémarrage ; la gestion des classes/paquetages Java est spécifiée de +manière très détaillée. (`plus de details`_) + +.. _plus de details: ../developper/osgi.html + +Tutoriels +--------- + +- JBoss wiki OSGi getting started : http://www.jboss.org/community/wiki/OSGiGettingStartedWithOSGiDevelopment + +Implémentations du framework +---------------------------- + +- Apache Felix : http://felix.apache.org/site/index.html + +- Spring dmServer : http://www.springsource.com/products/dmserver + +- Equinox : http://www.eclipse.org/equinox/ + +JMS/MOM +======= + +`JMS`_ est une spécification de `Sun`_ pour la gestion de messages. + +- Envoi de messages de manière asynchrone. (publish/subscribe : JMS Topic) + +- Gestion d'une file de messages. (point-to-point : JMS Queue) + +.. _Sun: http://java.sun.com/products/jms/ + +.. _JMS: http://fr.wikipedia.org/wiki/Java_Message_Service + +`MOM`_ (Message-Oriented Middleware) : Couche logicielle pour la gestion des messages. + +.. _MOM: http://fr.wikipedia.org/wiki/Message-Oriented_Middleware + +Tutoriels +--------- + +- Sun JMS Tutorial : http://java.sun.com/products/jms/tutorial/1_3_1-fcs/doc/copyright.html + +Implémentations +--------------- + +- OpenMQ : https://mq.dev.java.net/ + +- Apache ActiveMQ : http://activemq.apache.org/ + +JBI/ESB +======= + +Le problème initial est l'intégration de données en provenance de sources différentes au sein d'un système d'information +composé d'applications disparates. `JBI`_ définit une architecture qui permet la mise en place de solutions d'intégration basées +sur l'utilisation de composants qui communiquent via des messages. Les Enterprise Service Bus (`ESB`_) sont une +implémentation de cette norme. + +.. _JBI: http://fr.wikipedia.org/wiki/Java_Business_Integration + +.. _ESB: http://fr.wikipedia.org/wiki/Enterprise_Service_Bus + +Approche SOA couplé à la gestion d'un bus de messages via des Composants JBI +---------------------------------------------------------------------------- + +- Binding components (**BC**) : Composants permettant la communication en dehors de l'environnement JBI. + Inclusion des protocoles de communications tels que : JMS, HTTP/S, FTP, CORBA, ... Ces composants sont + couplés à une normalisation de message à l'intérieur de l'environnement JBI utilisés par le **NMR** + (Normalized Message Router). + +- Service engines (**SE**) : Composants comprenant la logique métier et/ou les transformations pour la + manipulation des services (XSLT, SpringBean, ...). Ils communiquent avec l'extérieur avec les BC via le NMR. + +En résumé : L'environnement JBI permet de faire communiquer différentes applications utilisant différents gestionnaires +de services et différents protocoles de communication au sein d'un environnement uniforme utilisant un bus de données (ESB). + + +Implémentations de la spécification JBI via ESB +----------------------------------------------- + +- Apache ServiceMix : http://servicemix.apache.org/home.html + +.. image:: ../schemas/ServiceMix3.png + :alt: Architecture de ServiceMix + +- JBossESB : http://www.jboss.org/jbossesb/ + +- Mule : http://www.mulesource.org/display/MULE2INTRO/Home + + + + Copied: trunk/src/site/rst/stage/recapitulatif.rst (from rev 40, trunk/choreg/src/site/rst/stage/recapitulatif.rst) =================================================================== --- trunk/src/site/rst/stage/recapitulatif.rst (rev 0) +++ trunk/src/site/rst/stage/recapitulatif.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,665 @@ +============================= +Compte Rendus durant le Stage +============================= + +Document récapitulatif des comptes rendus fait pendant le stage effectué du 01/04/2009 au 28/08/2009 par fdesbois. + +.. contents:: Sommaire + +SEMAINE 14 (30/03 au 03/04) +=========================== + +CR1 : Projet CHOREM +------------------- + +- Etude de l'existant et lecture anciens rapports +- Mise en place nouvel environnement de dev pour Chorem 6 (nouvelle branche) : 2 modules (chorem-ui sous Tapestry, chorem-people avec ToPIA) +- Formation ToPIA +- Lecture The Data Model Resource Book (Chap 2, 6, 9) +- Analyse et début de conception du coeur de l'applicationn : chorem-people (Gestion des personnes et des sociétés, contacts, ...) + +(Liens : `Documentation ToPIA`_ , `Projet CHOREM`_ ) + +.. _Documentation ToPIA: http://maven-site.nuiton.org/topia/topia-persistence + +.. _Projet CHOREM: http://labs.libre-entreprise.org/projects/chorem/ + +CR1 : Prévu semaine 15 +---------------------- + +- Fin de conception du module chorem-people + Implémentation et tests +- Définition du cahier des charges (Modules Ressources humaines et Gestion de projet) +- Analyse du prochain module : Gestion de projet + +SEMAINE 15 (06/04 au 10/04) +=========================== + +CR2 : Projet CHOREM +------------------- + +- Fin de conception + début implémentation Module Chorem-people +- Léger ajout dans ToPIA-persistence (variables statiques correspondant aux noms des champs des "entity" placés dans les interfaces) +- Angine + +(Lien : `Projet ToPIA`_ ) + +.. _Projet ToPIA: http://nuiton.org/show/topia + +CR2 : Prévu Semaine 16 +---------------------- + +- Formation Tapestry + début d'IHM pour module Chorem-people +- Analyse module Gestion de projet : chorem-workeffort +- Documentation RST + Javadoc du module Chorem-people + +SEMAINE 16 (14/04 au 17/04) +=========================== + +CR3 : Projet CHOREM +------------------- + +- Formation Tapestry +- Mise en place premier CRUD pour Personne avec Tapestry + +(Lien : `Site officiel Tapestry`_ ) + +.. _Site officiel Tapestry: http://tapestry.apache.org/tapestry5.1/ + +CR3 : Prévu Semaine 17 +---------------------- + +- Recherche technique JS pour popups d'édition (formulaire) +- Continuer implémentation + doc chorem-people-business +- Continuer IHM avec Tapestry (Gestion des sociétés) + +SEMAINE 17 (20/04 au 24/04) +=========================== + +CR4 : Projet CHOREM +------------------- + +- Formation Tapestry / Prototype +- Création Mixin Window : Ouverture d'une fenêtre avec contenu chargé en Ajax + +(Lien : `Site officiel Prototype`_ ) + +.. _Site officiel Prototype: http://www.prototypejs.org/ + +CR4 : Projet EUGene +------------------- + +- Ajout gestion des dépendances en UML depuis XMI 1.2 et 2.1 : Ajout dans Objectmodel et Chargement classes Java + +(Lien : `Projet EUGene`_ ) + +.. _Projet EUGene: http://nuiton.org/show/eugene + +CR4 : Prévu Semaine 18 +---------------------- + +- Analyse / Conception module Gestion de projet : workeffort +- Etude architecture logicielle entre les deux modules + +SEMAINE 18 (27/04 au 30/04) +=========================== + +CR5 : Projet CHOREM +------------------- + +- Début analyse module workeffort (Gestion de Projet) +- Ajout d'un projet chorem-common pour certains outils communs +- Ajout d'un outil pour la gestion des contextes ToPIA et chargement des propriétés (placé dans ToPIA-persistence : ContextUtil) +- Début de documentation sur la création d'un projet Chorem (architecture et organisation) +- Recherche solutions pour découplage des modules : + + * En étude : Apache Felix basé sur la sécification du framework d'OSGi (Chargement de modules à chaud sous forme de bundle, synchronisation des services, ...) + * Remarque : JMS ne semble pas adapté pour ca (en attente de recherche plus d'informations) + * A étudier la compatibilité et les échanges entre Félix et Tapestry + +(Lien : `Site officiel d'OSGi`_ ) + +.. _Site officiel d'OSGi: http://www.osgi.org/Main/HomePage + +CR5 : Prévu Semaine 19 +---------------------- + +- Etudier compatibilité entre Felix et Tapestry +- Mise en place essais de Apache Felix avec les deux modules people et workeffort (A noter que les points de connexions sont déjà bien définis) + +CR5 : Avancement Global +----------------------- + +- Module People : + + * Analyse : 85% (RAF : Scénarios) + * Conception : 70% (RAF : Diag de composants/packages) + * Implémentation métier : 30% (RAF : Services à refaire + DTO) + * Interface Tapestry : 10% + * Documentation : 20% (Javadoc uniquement) (RAF : dictionnaire de données, documentation chaque partie(Analyse, Conception, Implémentation)) + +- Module WorkEffort : + + * Analyse : 50% (RAF : Cas d'utilisations et scénarios) + * Conception : 0% + +- Architecture/Modularité (R&D) : + + * JMS : 10% (Apache ActiveMQ, Sun OpenMQ, ... ) + * JMX : obsolète + * JCA : utile pour lié ancien SI avec nouvelles fonctionnalités, par pour projet from scratch + * OSGi : en cours (5%) + * Tapestry-IoC : 90% (non adapté) + * Spring : 70% (Framework présent sur toutes les couches, déjà utilisé dans projet Tapestry-IoC et ToPIA, donc inutile) + +**Solution la plus intéressante : Apache Félix basé sur OSGi** + +SEMAINE 19 (04/05 au 07/05) +=========================== + +CR6 : Projet CHOREM (Architecture/Modularité) +--------------------------------------------- + +- Etude d'OSGi +- Lecture documentation Apache Felix (Qui implémente OSGi) et Apache Felix Karaf (Sous module de Felix qui est le Kernel de ServiceMix) +- Essai de création de bundle, manipulation Karaf, manipulation OBR (OSGi Repository Bundle qui peut être le même que Maven), création de features (en stand by, pas encore release par Karaf) + +- Chorem-people-business est devenu un bundle. Une bonne partie des librairies nécessaires à Chorem-people et ses dépendances sont disponibles en tant que bundle (majoritairement sur SpringSource). + Certaines librairies notamment celle lutins (lutingenerator, topia, lutinutil) sont inclus directement dans le bundle Chorem-people. (Si la solution OSGi est validé, il sera nécessairement plus + pertinent de créer des bundles pour les librairies lutins nécessaires dans Chorem) +- Karaf permet un déploiement à chaud des bundles (déposer dans un dossier) et des configs de ces derniers (deux dossiers distincts sur le serveur). + +(Liens : `Site officiel Apache Felix`_ et `Apache Karaf`_ ) + +.. _Site officiel Apache Felix: http://felix.apache.org/site/index.html + +.. _Apache Karaf: http://felix.apache.org/site/apache-felix-karaf.html + +CR6 : Prévu Semaine 20 +---------------------- + +- Création du bundle Chorem-people-ui avec intégration de Tapestry. Risque problème de serveur d'application : Tomcat à intégrer dans OSGi ou inverse... (L'inverse semble plus pertinent et performant) +- Premier jet d'une documentation sur l'architecture OSGi et sa mise en place pour Chorem (avec études des différentes possibilités d'utilisation) + +SEMAINE 20 (11/05 au 15/05) +=========================== + +CR7 : Projet CHOREM +------------------- + +- Etude OSGi avec Apache Felix et Apache ServiceMix Kernel (devenu sous-projet Karaf de Felix) +- Premier jet de documentation (rst en pièce jointe placé dans le projet chorem-commons) + +Résumé architecture projets créés dans chorem/branches/chorem6-trunk : + +- Chorem-commons (partie commune de chorem : utils, gestion third-party pour les librairies lutins qui ne sont pas des bundles, ...) +- Chorem-people (Gestion des personnes et sociétés) 3 modules : + + * People-business : Métier de Chorem-people, entités et services + * People-client : Client test pour OSGi + * People-ui : Client web avec Tapestry + +- Chorem-workeffort (Gestion de projet). Point de liaison avec People bien identifié et séparé (pour faciliter l'adaptation aux technos OSGi, SOA, JMS, ???, ...) + +(Lien(s) : `Documentation OSGi`_ ) + +.. _Documentation OSGI: ../developper/osgi.html + +CR7 : Problèmes OSGi +-------------------- + +- Chargement du Driver H2 avec Hibernate ne fonctionne pas... (A cause du Class.forName, chaque bundle ayant son propre classloader (donc différent pour Hibernate et notre appli) +- Complexité d'intégration avec Tapestry (manque de connaissances sur les 2 frameworks pour les combiner) + +CR7 : Projets ToPIA et EUGene +----------------------------- + +- migration topia en org.nuiton + dependance avec eugene au lieu de lutingenerator : Topia version : 2.2.0-SNAPSHOT + +CR7 : Prévu Semaine 21 +---------------------- + +- Fignoler doc sur OSGi avec approfondissement sur les travaux R&D effectués depuis 2 semaines +- Etudier DTOGenerator pour la génération des DTO. Voir comment générer les services. +- Retour à l'implémentation/conception : People-business et/ou People-ui... + +SEMAINE 21 (18/05 au 22/05) +=========================== + +CR8 : Projet CHOREM +------------------- + +- Ptite doc Architecture/Technologie pour modularité du projet CHOREM +- Génération DTO (BeanGenerator de ToPIA-persistence) et Services (avec ToPIA-SOA) +- Implémentation de services (ServiceContact) pour Chorem-people + +(Lien : `Documentation Modularite Chorem`_ ) + +.. _Documentation Modularite Chorem: ../recherche/technos.html + +CR8 : Projet EUGene +------------------- + +- Resolve issue on ObjectModelAttribute name property (NullPointerException when name="" in ObjectModel file from XMI 2.1) +- Add reverseAttributeName and reverseMaxMultiplicity in ObjectModel from XMI 2.1 +- Resolve issue on navigable in ObjectModel from XMI 2.1 (it didn't appear when false) + +CR8 : Projet ToPIA +------------------ + +- DTO generation with BeanGenerator + +CR8 : Prévu Semaine 22 +---------------------- + +- Continuer implémentation services de chorem-people +- Tests IHM avec Tapestry + +SEMAINE 22 (25/05 au 29/05) +=========================== + +CR9 : Projet CHOREM +------------------- + +- Implémentation ServiceContact et ServicePerson +- Quelques outils pour faciliter l'implementation et la gestion des erreurs (exceptions, logs) + conversion DTO -> Chorem-commons + +CR9 : DEBAT : Exceptions ?? +--------------------------- + +Comment gérer les erreurs ? Les exceptions offrent de nombreuses possibilités pour facilement géré les erreurs. Mais comment les créer ? Faut-il utiliser +au maximum les exceptions existantes de la JDK ? Faut-il faire hériter toutes les exceptions d'une et une seule correspondant a l'application (à l'instar de TopiaException) ? +Ou même faut-il créer de nouvelles exceptions spécifiques qui héritent de TopiaException ? Ou simplement créer des exceptions suivant les besoins ? + +Pour essayer, dans mon cas j'ai créer quelques exceptions spécifiques au métier (je pense qu'elles seront réencapsulé pour être utilisé dans l'interface) : +NullParameterException, EntityNotExistException, ConvertException, ... Mes services catch toutes les exceptions engendrés par le métier (TopiaException, ou autres cités ci-dessus). +Et renvoie un nouveau jeu d'exceptions pour l'interface ou le client des services. A voir si cette nouvelle encapsulation est utile. Aucun client n'a été testé pour le moment. + +En tout cas, je ne suis pas vraiment sur de mes choix, et j'aurais aimé avoir votre avis sur la gestion des exceptions et des erreurs dans une application de gestion +comme celle-ci. + +CR9 : Projet ToPIA +------------------ + +- Resolve issue of 0..* multiplicity on attribute with primitive type (like String) + +- Changement génération DTO avec BeanGenerator. Une dépendance entre un DTO et une ENTITE signifie : + Tous les attributs de l'entité (seulement ceux primitifs ou dates) sont générés dans le DTO. Les autres attributs devant être précisé a la main dans le DTO pour une manipulation plus spécifique. + Evolution possible : generation d'attributs id automatiquement dans le DTO lorsque l'entité possède des liens navigables vers d'autres entités.... + +CR9 : Problème +-------------- + +- Suppression d'une entité avec une liaison * * et de l'héritage. Le cas est un peu spécifique, mais l'exécution du delete dans le DAOAbstract généré engendre une erreur Hibernate ! + Le problème a été résolut en partie dans ToPIA (modification de DAOAbstractGenerator + jeu de tests sur les suppressions et l'heritage + modification modele topiatest : non commité). + Cependant , même si le jeu de test Topia (meme representation que dans mon modele) passe sans encombre, mon modele de people ne passe pas : + +:: + + 10:41:51,220 WARN JDBCExceptionReporter:100 - logExceptions - SQL Error: 42122, SQLState: 42CR9 + 10:41:51,221 ERROR JDBCExceptionReporter:101 - logExceptions - Column clazz_ not found [42122-112] + + testAddContact(org.chorem.people.impl.ServicePersonImplTest) Time elapsed: 0.099 sec <<< ERROR! + org.hibernate.exception.SQLGrammarException: could not execute query + at org.hibernate.exception.SQLStateConverter.convert(SQLStateConverter.java:90) + at org.hibernate.exception.JDBCExceptionHelper.convert(JDBCExceptionHelper.java:66) + at org.hibernate.loader.Loader.doList(Loader.java:2231) + at org.hibernate.loader.Loader.listIgnoreQueryCache(Loader.java:2125) + at org.hibernate.loader.Loader.list(Loader.java:2120) + at org.hibernate.loader.custom.CustomLoader.list(CustomLoader.java:312) + at org.hibernate.impl.SessionImpl.listCustomQuery(SessionImpl.java:1722) + at org.hibernate.impl.AbstractSessionImpl.list(AbstractSessionImpl.java:165) + at org.hibernate.impl.SQLQueryImpl.list(SQLQueryImpl.java:175) + at org.chorem.people.persistence.PartyEntityDAOAbstract.delete(PartyEntityDAOAbstract.java:33) + +voila le bout de code généré qui posait problème :: + + public abstract class PartyEntityDAOAbstract<E extends PartyEntity> extends org.nuiton.topia.persistence.TopiaDAODelegator<E> implements org.nuiton.topia.persistence.TopiaDAO<E> { + + public void delete(E entity) throws TopiaException { + ... + { + List<org.chorem.people.persistence.ContactEntity> list = getContext().getHibernate().createSQLQuery( + "SELECT main.topiaid " + + "from contactEntity main, contacts_partyentity secondary " + + "where main.topiaid=secondary.contacts" + + " and secondary.partyEntity='" + entity.getTopiaId() + "'") + .addEntity("main", org.chorem.people.PeopleModelDAOHelper.getImplementationClass(org.chorem.people.persistence.ContactEntity.class)).list(); + for (org.chorem.people.persistence.ContactEntity item : list) { + item.removePartyEntity(entity); + } + } + ... + super.delete(entity); + } + ... + } + +J'ai juste changé {main.*} par main.topiaid à la génération. Le main.* provoquait l'ajout de tous les attributs des sous-classes pour une requete sur la classe mère. + +Donc voilà, je comprends pas ce nouveau problème de "Column clazz not found". Je ne vois pas où il engendre ca !!! Ci-joint à ce mail, une image représentant le cas problématique. + +CR9 : Prévu Semaine 23 +---------------------- + +- Continuer implémentation des services +- Tests avec Tapestry si les implémentations sont terminés + +SEMAINE 23 (02/06 au 05/06) +=========================== + +CR10 : Projet Bonzoms +--------------------- + +- Migration sur chorem.org +- Ajout du module chorem-commons (lib temporaire d'utilitaires pour projet chorem) +- Probleme sur la suppression avec multiplicité * * et l'heritage résolu ! (Apres la migration les tests sont OK) +- Implementation ServiceRelationship + tests sur les relations et rôles : Utilisation de la surcharge du DAO avec la nouvelle modif ToPIA + +(Lien : `Projet Bonzoms`_ ) + +.. _Projet Bonzoms: http://chorem.org/show/bonzoms + +CR10 : Projet ToPIA +------------------- + +- Ajout support extension des DAO : A partir du modèle les méthodes avec le stéréotypes <<dao>> sur une entité sont prises en comptent. (v 2.2.0-rc-2-SNAPSHOT). Voir FAQ + commit r1530 +- Suppression TopiaDAODelegator. Fusion TopiaDAOAbstract et TopiaDAOHibernate -> TopiaDAOImpl. Voir changelog + commit r1528 + +CR10 : Prévu Semaine 24 +----------------------- + +- Finir implémentation des services de base de Bonzoms +- Premiers tests avec Tapestry +- Diagramme de composants pour dépendances et utilisations entre projets chorem. + +SEMAINE 24 (08/06 au 12/06) +=========================== + +CR11 : Projet Bonzoms +--------------------- + +2ème semaine sur Tapestry depuis le début du stage : + +- Création composant Tapestry pour la gestion des contacts : + + * Gestion d'une liste (Grid) avec ajout d'une ligne par simple click + * La ligne est modifiable grâce à un champ texte + * La ligne est supprimable. + * Une fois les modifs effectuées, l'utilisateur doit sauvegarder. + * La sauvegarde, enregistre les contacts (ou supprime les anciens) via les services de Bonzoms. + * L'adresse est un contact spécifique avec un formulaire comportant 5 champs directement dans la Grid + * Autocomplete sur la ville. En cours essais Tapestry : Automatiser le remplissage des champs CodePostal et Pays directement après le + click sur l'autocomplete de la ville. + +- Mise en place gestion des erreurs simples dans Tapestry : + + * Refactor des Exceptions de Bonzoms-business et Chorem-commons + * Un seul type d'exception depuis les services : BonzomsException qui encapsule d'autres exceptions comme TopiaException, ConvertException, + EntityException ou IllegalArgumentException pour préciser plus en détails la nature du problème. + * Niveau de précision des erreurs (0, 1 ou 2) pour l'affichage utilisateur dans Tapestry : + + - 0 : erreur directe, ecrite depuis Tapestry avec gestion langues. + - 1 : erreur depuis les Services (BonzomsException) + - 2 : erreur initial depuis le métier de Bonzoms. + +CR11 : Projet EUGene +-------------------- + +- Déplacement de paramètres depuis ObjectModelAttribute vers ObjectModelParameter (min, max multiplicity, isOrdered, isUnique) pour gestion sur parametre de retour d'une méthode +- Ajout isStatic sur un attribut + defaultValue (String) +- Corrections quelques erreurs dans XSL pour XMI 2.1 (superClass en superclass, ordering="true" au lieu de ordering="ordered", ...) + +CR11 : Prévu semaine 25 +----------------------- + +- Continuer interface Tapestry + essais fenêtre JS pour problème de navigation +- Diagramme de composants des modules Chorem +- Si reste du temps : Essai communication WorkEffort et Bonzoms avec Services Bonzoms générés par Topia-SOA + +SEMAINE 25 (15/06 au 19/06) +=========================== + +CR12 : Projet Bonzoms +--------------------- + +- Tapestry : Essais sur fenêtre JS... Toujours même problème, le javascript ne fonctionne plus à l'intérieur de la fenêtre lorsque son contenu est chargé en AJAX... Problème venant de Tapestry ?? +- Tapestry : Mise en place Autocomplete pour la gestion des villes et pays des Contacts (remplissage champs auto en JS) +- Tapestry : Regroupement du comportement commun de deux pages dans une classe abstraite + +- Services : Implémentation de quelques méthodes du serviceOrganization -> en cours... +- Diagramme de composants + mini-rapport sur les liaisons entre les différents projets Chorem. + +CR12 : Prévu Semaine 26 +----------------------- + +- Refactor ancien bout de projet WorkEffort pour créer le nouveau projet de Gestion de Projet (Gepeto pour le moment d'après le sondage) +- Essais communication entre Bonzoms-business et Gepeto-business via Services et ToPIA-SOA + +SEMAINE 26 (22/06 au 26/06) +=========================== + +CR13 : Projet Bonzoms +--------------------- + +- Tapestry : Gestion des services d'une société + un peu de style +- Nettoyage des test unitaires et uniformisation gestion des erreurs dans les services + Javadoc +- Architecture : Debut de réflexion sur architecture des projets Chorem + +CR13 : Prévu Semaine 27 +----------------------- + +- Continuer architecture des projets chorem +- Tapestry : ajouter gestion des roles et des employes + +CR13 : Retour sur Demo du 26/06 +------------------------------- + +L'erreur sur la fenetre JS provenait de l'ajout d'un script pour permettre à firebug de récupérer les messages de debug ou d'erreurs de Tapestry. +Firebug étant désactivé lors de la demo + le fait que mon composant fenetre contienne du debuggage Tapestry JS faisait planter la fenetre, +donc affichage dans une nouvelle page... Les autres erreurs de la demo venait du même problème de firebug. + +SEMAINE 27 (29/06 au 03/07) +=========================== + +CR14 : Projet Bonzoms +--------------------- + +- Gestion des employés terminé +- Gestion des rôles et relations en finition + +Bonzoms quasimment opérationnel + +CR14 : Architecture CHOREM +-------------------------- + +- Analyse en attente de validation (ci-joint 2 rapports : un plus ancien pour situer le contexte, quelques éléments sont revus et corriger dans le + second rapport qui va plus en profondeur. Reste à voir les technologies à utiliser pour la mise en place de cette architecture) + +(Liens : Les 2 rapports sont devenus les pages `Applications Chorem`_ et `Chorem-Registry`_ ) + +.. _Applications Chorem: ../architecture/archi_chorem_part1.html + +.. _Chorem-Registry: ../architecture/archi_chorem_part2.html + +CR14 : Prévu Semaine 28 +----------------------- + +- Quelques finitions avec Tapestry pour Bonzoms +- Début d'analyse pour le projet "Trésorerie" ou "Budgeting" -> un sondage sera surement créé pour lui donner un nom +- Le projet Gepeto concernant la gestion de projet est mis de côté au profit de la trésorerie, plus accessible et plus facilement finissable pour la + fin du stage +- RMLL Jeudi et Vendredi + +SEMAINE 28 (06/07 au 10/07) +=========================== + +- Bonzoms en grande partie terminé (reste quelques détails au niveau interface) +- RMLL pdt 2 jours + +CR15 : Prévu Semaine 29 +----------------------- + +- Documentation pour Bonzoms-ui (composants tapestry, gestion héritage et interfaces pour optimiser les injections de composants) + finition de Javadoc +- Essais sur composant Window + +SEMAINE 29 (15/07 au 17/07) +=========================== + +CR16 : Projet Bonzoms +--------------------- + +- Documentation Bonzoms-ui (doc developpeur uniquement) (deployé sur redmine) +- Essai pour composant Window (popup pour probleme de navigation entre formulaire) : sans AJAX, probleme avec javascript... retour a la version précédente... + +(Lien : `Documentation Bonzoms-ui`_ ) + +.. _Documentation Bonzoms-ui: http://maven-site.chorem.org/bonzoms/bonzoms-ui/ + +CR16 : Projet JRst +------------------ + +- Ajout parametres pour une image (width, height, align) : probleme sur le align, JRst crée le XHTML et le xDOC correctement mais une class CSS + disparait d'une balise lors du passage à Maven via doxia-module... +- Ajout style dans nuiton-skin pour alignement + +(Lien : `Projet JRst`_ et `Documentation JRst`_ ) + +.. _Projet JRst: http://nuiton.org/show/jrst + +.. _Documentation JRst: http://maven-site.nuiton.org/jrst/jrst + +CR16 : Prévu Semaine 30 +----------------------- + +- Analyse pour projet "Tresorerie"/"Budgeting" +- Finitions documentation Chorem-commons et Bonzoms-ui (doc utilisateur non faites) + +SEMAINE 30 (20/07 a 24/07) +========================== + +CR17 : Projet Bonzoms +--------------------- + +- encore un peu de doc / finalisation doc developpeur + déploiement de la doc +- lancement d'une classe au démarrage de Tapestry via le AppModule : + +:: + + public static void contributeRegistryStartup(OrderedConfiguration<Runnable> configuration) + { + configuration.add("RegisterServices", new RegisterBonzomsServices()); // ici RegisterBonzomsServices doit etre Runnable. Il permet d'ajouter ses services au ChoremRegistry + } + +CR17 : Module Chorem-Commons bientot intégré au ChoremRegistry +-------------------------------------------------------------- + +- déploiement de la doc +- début d'implémentation pour le Registry pour essais de communication (Génération des interfaces avec Topia) + +CR17 : Norme OASIS CIQ +---------------------- + +- étude de la norme : gestion des partys, personnes, relations, roles, contacts... sera utilisé par Bonzoms pour l'export des données et la + communication avec les autres applis Chorem +- utilisation de XMLBeans pour génération des classes java associés aux schémas XML de la norme (plugin maven) +- création d'un module pour tout ca : oasis-ciq-api (non commité, sera intégré au projet Registry une fois le vote terminé et le projet créé) +- essai de création d'un fichier XML avec Bonzoms +- un petit ennui : la norme ne propose pas de schema comprenant un ensemble de partys (n'ayant pas forcément de relation) -> il sera peut etre + indispensable d'étendre les schémas (comme le propose la norme) pour avoir un fichier XML comprenant l'ensemble des partys existants (sociétés, + services, clients, personnes, ...) : A tester ! + +(Lien : `Site officiel OASIS CIQ`_ ) + +.. _Site officiel OASIS CIQ: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ciq#announcements + +CR17 : Projet JRst +------------------ + +- Résolution du problème avec l'alignement sur les images (remplacement du tag p par un div) + +CR17 : Prévu Semaine 31 +----------------------- + +- Création projet Registry : intégration modules Chorem-Commons (changement de nom) + oasis-ciq-api + finalisation de l'implémentation de la spec du ChoremRegistry +- Création projet Tresorerie : deux modules : + + * business : génération des entités avec Topia, création d'un service simple d'ajout/modification/suppression et ajout d'une reference (potentiellement une party de Bonzoms). + * ui : Création d'une IHM simple en reprenant les principes de l'ui de Bonzoms + +Le but étant d'avoir une version ultra simplifié de Tresorerie pour testé le Registry et la liaison avec Bonzoms + +Si reste du temps : révision doc ChoremRegistry + doc sur communication + +SEMAINE 31 (27/07 au 31/07) +=========================== + +CR18 : Travail effectué +----------------------- + +- [choreg] : Creation projet ChoReg (inclut oasis-ciq-api, chorem-commons, choreg et choreg-test-webapp) +- [cash] : Creation projet Ca$h (ui et business) +- [bonzoms] : Mise en place de ChoReg pour Bonzoms (enregistrement des services proposant un format xPIL) + +- [cash-business] : Utilisation de ChoReg dans Ca$h pour données depuis Bonzoms (utilisation de oasis-ciq-api) +- [cash-ui] : Page affichant les données au format xPIL + +(Liens : `Projet Ca$h`_ et `Projet ChoReg`_ ) + +.. _Projet Ca$h: http://chorem.org/show/cash + +.. _Projet ChoReg: http://chorem.org/show/choreg + +CR18 : Problème rencontré +------------------------- + +- [cash-ui] : Creation lien dynamique avec Tapestry pour ServiceUIPerson de Bonzoms : pageRender null à l'instanciation au démarrage de Tapestry. + +CR18 : Prévu Semaine 32 +----------------------- + +- [choreg] : Doc présentation et but de ChoReg (introduction/presentation) +- [choreg] : Doc "Getting Started" pour ChoReg (mini-tuto) +- [choreg] : Doc déploiement pour ChoReg +- [choreg] : JavaDoc et uniformisation de la doc ChoReg (doc développeur notamment) + +- [stage] : Plan du rapport de stage +- [planning] : Préparer prochaines étapes avant la fin du stage (Tâches prévus + résultat attendu) + +CR18 : Résultat attendu +----------------------- + +**Documentation complète de ChoReg** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Copied: trunk/src/site/rst/stage/sujet.rst (from rev 40, trunk/choreg/src/site/rst/stage/sujet.rst) =================================================================== --- trunk/src/site/rst/stage/sujet.rst (rev 0) +++ trunk/src/site/rst/stage/sujet.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,38 @@ +Stage: Logiciel de gestion de projet/RH/CRM +=========================================== + +Chorem est un progiciel de gestion intégré (PGI) simple, voulant +répondre à la gestion quotidienne des sociétés. Il dispose de plusieurs +modules répondant chacun à des besoins particuliers : la gestion de +projet, la gestion des contacts ou encore la comptabilité. Chorem est +basé sur ToPIA et se veut simple d'utilisation, modulaire, flexible et +complet. + +Objectif du stage +----------------- + +Ce stage se compose de plusieurs parties: +- intégrer le projet chorem dans le projet Sharengo. +- améliorer le projet en ajoutant un calendrier partagé +- maintenir le site web de présentation du projet +- avoir une reflexion sur l'implantation d'un projet de ce type sur une + architecture MOA (Message Oriented Application) + +Technologies +------------ + +- Java +- SOA +- Jaxx/Tapestry/GWT +- Topia +- Hessian +- MDA +- Spring +- Lucene +- maven +- svn + +Licence du développement +------------------------ + +GPL \ No newline at end of file Copied: trunk/src/site/rst/user/best_practices.rst (from rev 40, trunk/choreg/src/site/rst/user/best_practices.rst) =================================================================== --- trunk/src/site/rst/user/best_practices.rst (rev 0) +++ trunk/src/site/rst/user/best_practices.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,134 @@ +Bonnes pratiques +================ + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-05* + +Implémentation des services +--------------------------- + +ChoReg permet d'utiliser plusieurs implémentations pour un même service. Nous avons vu une implémentation unique dans le `Getting started`_ mais il est plus +intéressant d'organiser différemment ses classes pour permettre d'implémenter plus facilement différents formats pour un seul et même service. +Nous allons utiliser les génériques de Java, ainsi une classe abstraite de notre service se chargera d'effectuer le traitement global à toutes nos implémentations +(généralement les méthodes find et findAll ont le même traitement en base, seule la conversion change). Les sous-classes implémenteront au besoin ChoremService +ou une autre interface (notamment celle manipulé via les interfaces utilisateurs) tout en surchargeant la méthode de conversion définie dans la classe générique. + +.. _Getting started: start.html#impl-mentation-de-choremservice + +Exemple avec ServicePerson dans Bonzoms : + +.. image:: ../schemas/exemples/ClassDiagram_ServicePersonGeneric.png + :alt: Diagramme d'implémentation du ServicePerson dans Bonzoms + +Les méthodes getPerson et getPersons de la classe abstraite ServicePersonGeneric vont effectuer le traitement via ToPIA : recherche des données via les dao, gestion +de la transaction et traitement des exceptions. A la fin du traitement elles appeleront la méthode abstraite *convert* pour effectuer la conversion vers le type +de retour **générique** souhaité. Ainsi la sous-classe ServicePersonDTO convertira l'entité PersonEntity en PersonDTO et la sous-classe ServicePersonXPIL convertira +l'entité PersonEntity en PartyDocument (Classe de l'Api OASIS CIQ qui imlémente le format xPIL). Chacun des deux services est indépendant, l'un servira pour +l'interface utilisateur (dans Bonzoms, elle est faites avec Tapestry), et l'autre servira pour l'export de personnes au format xPIL pour ChoReg. + +Implémentation ServicePersonGeneric<T> :: + + public abstract class ServicePersonGeneric<T> { + + protected T getPerson(String id) throws BonzomsException { + T person = null; + TopiaContext transaction = null; + try { + transaction = context.beginTransaction(); + + PersonEntityDAO dao = BonzomsModelDAOHelper.getPersonEntityDAO(transaction); + + PersonEntity entity = dao.findByTopiaId(id); + + if (entity != null) { + person = convert(entity); + } + + transaction.closeContext(); + } catch (Exception eee) { + // Gestion des erreurs, rollback de la transaction + } + return person; + } + + protected List<T> getPersons() throws BonzomsException { + List<T> persons = new ArrayList<T>(); + TopiaContext transaction = null; + try { + transaction = context.beginTransaction(); + + PersonEntityDAO dao = BonzomsModelDAOHelper.getPersonEntityDAO(transaction); + + for (PersonEntity entity : dao.findAll()) { + T person = (T) convert(entity); + persons.add(person); + } + + transaction.closeContext(); + } catch (Exception eee) { + // Gestion des erreurs, rollback de la transaction + } + return persons; + } + + protected abstract T convert(PersonEntity entity) throws ConvertException; + + } + +Implémentation de ServicePersonXPIL<PartyDocument> :: + + public class ServicePersonXPIL extends ServicePersonGeneric<PartyDocument> implements ChoremService { + + private static final Log log = LogFactory.getLog(ServicePersonXPIL.class); + + @Override + protected PartyDocument convert(PersonEntity entity) throws ConvertException { + // Conversion PersonEntity en PartyDocument + // voir code de Bonzoms ou Api OASIS CIQ + } + + @Override + public String getFormat() { + return FormatType.OASIS_CIQ_XPIL; + } + + @Override + public <T> T find(Class<T> returnType, String entityId) throws Exception { + if (!returnType.equals(XMLStreamReader.class)) { + throw new WrongTypeException("Type de retour '" + returnType.getName() + "' non supporté par ServicePerson"); + } + PartyDocument result = getPerson(entityId); + return result.newXMLStreamReader(); + } + + @Override + public <T> List<T> findAll(Class<T> returnType, String filters) throws Exception { + if (!returnType.equals(XMLStreamReader.class)) { + throw new WrongTypeException("Type de retour '" + returnType.getName() + "' non supporté par ServicePerson"); + } + List<T> results = new ArrayList<T>(); + for (PartyDocument doc : getPersons()) { + results.add(doc.newXMLStreamReader()); + } + return results; + } + + @Override + public String getShowText() { + return "Person"; + } + + } + +Il est désormais aisé de créer une nouvelle classe pour un nouveau format d'exportation d'une personne, en vCard par exemple. + +Note + Lors d'une erreur de type il est important de renvoyé une *WrongTypeException* pour pouvoir être géré par ChoReg. Il est également fortement conseillé + de manipuler uniquement un seul type de donnée par format pour éviter ce genre de désagréments aux applications clientes du format. + + + Copied: trunk/src/site/rst/user/deployment.rst (from rev 40, trunk/choreg/src/site/rst/user/deployment.rst) =================================================================== --- trunk/src/site/rst/user/deployment.rst (rev 0) +++ trunk/src/site/rst/user/deployment.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,147 @@ +Déploiement des applications Chorem +=================================== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-05* + +Ce document décrit la façon dont les applications sont organisés dans le serveur d'application. + +Tomcat 6 +-------- + +Le répertoire contenant les librairies communes de tomcat6 est le répertoire **lib**. C'est dans ce répertoire que sera placé le jar choreg.jar (à télécharger +ou à compiler depuis les sources du `SVN`_ ). Les applications utilisant choreg doivent être déployés dans tomcat. Les fichiers **war** ainsi déployés ne doivent +pas contenir la librairie choreg.jar pour permettre le partage de ChoReg à travers les différentes applications qui l'utilisent. Ainsi pour maven, le scope de +dépendance vers choreg sera obligatoirement **provided**. + +Dans tomcat, chaque application à son propre ClassLoader en plus de ceux de tomcat (ClassLoader Common, System et Bootstrap : `doc tomcat`_ ). Ainsi, Choreg +n'étant présent que dans le common, dès l'utilisation du singleton ChoremRegistry, tomcat ira chercher les classes dans le ClassLoader common de tomcat. + +Il est important de noter que ChoReg n'a aucune dépendance de librairie externe. Ainsi chaque application devra inclure ses propres dépendances. +De plus les types d'objet manipuler à travers ChoReg devront obligatoirement se trouver soit dans ChoReg, soit dans le ClassLoader de tomcat, pour ainsi +dire, dans la JRE Java. + +.. _SVN: http://chorem.org/svn/choreg/trunk/choreg + +.. _doc tomcat: http://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html + +Exemple avec Bonzoms et Ca$h +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Voici l'état de tomcat lors du déploiement des applications Bonzoms et Ca$h : + +.. image:: ../schemas/exemples/DeploymentDiagram_Tomcat6_Bonzoms_Cash.png + :alt: Diagramme de déploiement de Bonzoms et Ca$h dans Tomcat6 + +Oasis CIQ Api n'est pas partagé par les deux applications, c'est un module qui potentiellement devrait l'être car il ne possède que peu de dépendances externes +(XMLBeans 2.4 qui dépend lui même de Stax 1.0.1, voir mvn dependency:tree dans le module oasis-ciq-api). De plus, il est utilisé pour la manipulation +des formats dans ChoReg et permettrait l'utilisation des classes de l'api comme type de données d'échange. +ToPIA quant à lui est beaucoup plus important car il contient Hibernate et de nombreuses librairies externes. Pour son fonctionnement, il ne doit pas être +placé en dehors des **war** des applications. Chaque application manipule son propre contexte ToPIA et sa propre base de données. Leurs fonctionnement reste +indépendants du serveur d'application ainsi que de choreg. + +Usage du singleton ChoremRegistry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ChoReg est manipuler de façon statique, il n'y a qu'une et une seule instance de ChoReg dans tout le serveur d'application. C'est cette instance qui est partagé +via les différentes applications. Pour l'utiliser chaque application devra potentiellement faire attention à sa présence dans le ClassLoader. +Ainsi même si ChoReg est absent du serveur d'application, chaque application fonctionnera indépendamment des autres (pas de transfert de données). +Pour faire simple, chaque application isolera l'utilisation de ChoReg dans une classe (ou plusieurs) qui devront être testé à l'instanciation. +En effet, Java renverra une *NoClassDefFoundError* lorsqu'il ne trouvera pas ChoReg dans le serveur d'application. + +Exemple :: + + public class RegisterBonzomsServices { + + private ChoremRegistry choreg = ChoremRegistryImpl.getInstance(); + + public static startup() { + choreg.register(ServicePerson.class.getName(), new ServicePersonXPIL()); + } + + public static shutdown() { + choreg.unregister(ServicePerson.class.getName()); + } + } + +Démarrage/Arrêt de l'application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Votre application devra pouvoir identifier proprement son déploiement/démarrage et son arrêt. Deux méthodes sont possibles suivant les besoins et les applications. + +Application web (module ui) ++++++++++++++++++++++++++++ + +Pour une application web faites sous Tapestry, il suffit d'utiliser le AppModule de l'application indispensable à Tapestry pour gérer son registre (`Tapestry IoC`_ ). + +.. _Tapestry IoC: http://tapestry.apache.org/tapestry5/tapestry-ioc + +AppModule :: + + public static void contributeRegistryStartup(OrderedConfiguration<Runnable> configuration) + { + try { + configuration.add("BonzomsStartup", new BonzomsManager()); + } catch (NoClassDefFoundError eee) { + System.out.println("AppModule.contributeRegistryStartup() : ChoremRegistry unavailable"); + } + } + + @EagerLoad + public RegistryShutdownListener buildBonzomsShutdown(@InjectService("RegistryShutdownHub") RegistryShutdownHub hub) { + RegistryShutdownListener listener = new ContextShutdown(); // Listener par défaut pour fermer le contexte root de ToPIA + try { + listener = new BonzomsManager(); + } catch (NoClassDefFoundError eee) { + System.out.println("AppModule.buildBonzomsShutdown() : ChoremRegistry unavailable"); + } + hub.addRegistryShutdownListener(listener); + return listener; + } + +BonzomsManager :: + + public class BonzomsManager implements Runnable, RegistryShutdownListener { + + private static ChoremRegistry choreg = ChoremRegistryImpl.getInstance(); + + @Override + public void run() { + // startup + } + + @Override + public void registryDidShutdown() { + // shutdown + } + } + +Services métier (module business) ++++++++++++++++++++++++++++++++++ + +Voir `documentation projet chorem`_ pour l'utilisation du ServletContextListener + +.. _documentation projet chorem: ../developper/project.html#servletcontextlistener + +Exemple d'exécution +~~~~~~~~~~~~~~~~~~~ + +Bonzoms est démarré via son module ui (donc via Tapestry), il enregistre son ServicePerson (manipule format xPIL) auprès de ChoReg et son ServiceUI pour ServicePerson. +Ca$h va faire une demande de données au format xPIL auprès de ChoReg. ChoReg va chercher les services correspondants à la demande et va trouver celui enregistrer +par Bonzoms. Ca$h récupère ainsi les données et demande pour chacune d'entre elle son url s'il existe auprès de ChoReg. ChoReg renvoie alors l'url correspondant +pour chaque demande de Ca$h. + +Pour simplifier le diagramme ci-dessous le détail du contenu de Ca$h Business (plus d'une classe est manipulé) et Ca$h ui n'est pas détaillé. De même les méthodes +search au niveau de ChoremRegistry sont des simplifications des recherches dans les structures de données qui contiennent les services, formats et uis. + +.. image:: ../schemas/exemples/SequenceDiagram_Execution_Bonzoms_Cash.png + :alt: Diagramme de séquence d'une demande de données au format xPIL à travers ChoReg + +Vous pouvez maintenant vous orienter vers le document `Bonnes pratiques`_ pour plus de détails sur la bonne façon d'implémenter les services qui seront enregistrer dans ChoReg. + +.. _Bonnes pratiques: best_practices.html + Copied: trunk/src/site/rst/user/faq.rst (from rev 40, trunk/choreg/src/site/rst/user/faq.rst) =================================================================== --- trunk/src/site/rst/user/faq.rst (rev 0) +++ trunk/src/site/rst/user/faq.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,47 @@ +FAQ +=== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-05* + +Quelle est la différence entre le type de retour des méthodes *find* et *findAll* et le format passé en paramètre ? +------------------------------------------------------------------------------------------------------------------- + +Le type de retour des méthodes *find* et *findAll* est un type de retour générique. Il s'agit d'une classe java qui doit être passé en paramètre des méthodes. +Cette classe java doit obligatoirement faire partie de ChoReg ou des librairies incluses dans le serveur d'application, plus généralement dans la JRE Java. +Le format quant à lui correspond au format des données retournées (encapsulé dans l'objet java). Il s'agit plus particulièrement d'un standard ou d'une norme +connu permettant l'interopérabilité entre les applications. + +Exemple : + +- formats : xPIL (XML), iCalendar, vCard, ... +- types de retour : InputStream, Reader, XMLStreamReader, Object, String, ... + +Voir documentation sur les `formats`_ + +.. _formats: formats.html + +Comment savoir qu'un format ou un uri ne correspond à aucun service dans ChoReg ? +--------------------------------------------------------------------------------- + +Les méthodes de ChoReg renvoient des exceptions de type ChoregException ou IllegalArgumentException. Il est possible de catcher une autre exception qui +est un sous type de ChoregException, il s'agit du NoServiceException. Il est donc important de séparer les catch d'une NoServiceException des autres +exceptions engendrés par ChoReg. + +Exemple :: + + try { + List<XMLStreamReader> results = choreg.findAll(userId, FormatType.OASIS_CIQ_XPIL, XMLStreamReader.class, null); + + } catch (NoServiceException eee) { + // Pas de service manipulant le format xPIL + } catch (Exception eee) { + // Autres ChoregException ou IllegalArgumentException... + } + +Il existe une autre possibilité de tester l'existence d'un service à condition de connaître son sid. Il suffit d'utiliser les méthodes *existService* ou *existUI* +qui prennent toutes deux en paramètre le sid du service (ex : org.chorem.bonzoms.services.ServicePerson). \ No newline at end of file Copied: trunk/src/site/rst/user/filters.rst (from rev 40, trunk/choreg/src/site/rst/user/filters.rst) =================================================================== --- trunk/src/site/rst/user/filters.rst (rev 0) +++ trunk/src/site/rst/user/filters.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,4 @@ +Filtres +======= + +TODO \ No newline at end of file Copied: trunk/src/site/rst/user/formats.rst (from rev 40, trunk/choreg/src/site/rst/user/formats.rst) =================================================================== --- trunk/src/site/rst/user/formats.rst (rev 0) +++ trunk/src/site/rst/user/formats.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,72 @@ +Formats +======= + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-05* + +Les formats manipulés dans ChoReg doivent être des standard / norme. Chaque format peut proposer plusieurs types java correspondant au format. Par simplicité, +chaque format ne devrait renvoyé qu'un seul type d'objet java. + +.. contents:: Sommaire + +Normes / Standards +------------------ + +Oasis CIQ +~~~~~~~~~ + +Le standard Oasis CIQ propose deux principaux formats xPIL et xPRL qui sont tous les deux des fichiers XML. Pour facilement manipuler ces fichiers XML, une api +est disponible dans le projet choreg : `oasis-ciq-api`_ . + +Format xPIL : Description des party (tiers), que ce soit des personnes ou des organisations. Il comprend les contacts, les rôles/occupations et les informations +personnelles et professionnelles des party. Il n'y a qu'un seul party par fichier XML. + +Format xPRL : Description des relations (rôles et dates) entre différentes party. + +.. _oasis-ciq-api: http://maven-site.chorem.org/choreg/oasis-ciq-api + +Types d'objets possible représentant les formats : + +- JRE 1.6 : InputStream, String, XMLStreamReader, Reader +- Apache XMLBeans : XmlObject, Node +- Oasis CIQ Api : PartyDocument + +Application Bonzoms +------------------- + +Utilisation de format depuis ChoReg : + +aucun + +Enregistrement des services : + +- org.chorem.bonzoms.services.ServicePerson : format xPIL, service UI +- org.chorem.bonzoms.services.ServiceOrganization : format xPIL + +Formats proposés : + +- Format xPIL types de retour : InputStream, String, XMLStreamReader + +Application Ca$h +---------------- + +Utilisation de format depuis ChoReg : + +- xPIL + +Enregistrement des services : + +aucun + +Formats proposés : + +aucun + + + + + Copied: trunk/src/site/rst/user/security.rst (from rev 40, trunk/choreg/src/site/rst/user/security.rst) =================================================================== --- trunk/src/site/rst/user/security.rst (rev 0) +++ trunk/src/site/rst/user/security.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,4 @@ +Sécurité +======== + +TODO \ No newline at end of file Copied: trunk/src/site/rst/user/start.rst (from rev 40, trunk/choreg/src/site/rst/user/start.rst) =================================================================== --- trunk/src/site/rst/user/start.rst (rev 0) +++ trunk/src/site/rst/user/start.rst 2009-09-24 13:43:08 UTC (rev 41) @@ -0,0 +1,260 @@ +Getting Started +=============== + +:Author: $Author$ +:Version: 1.0 +:Revision: $Revision$ +:Date: $Date$ + +*Created by fdesbois on 2009-08-04* + +Environnement testé : Tomcat 6.0, Ubuntu 9.04, JRE 1.6 + +Installation +------------ + +Telecharger le binaire +~~~~~~~~~~~~~~~~~~~~~~ + +1. Téléchargez le fichier jar choreg.jar + +2. Copiez le jar télécharger dans le dossier des librairies communes de votre serveur d'application + +3. Voila, ChoReg est installé !! + +Lignes de commandes, utilisation SVN et Maven +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Récupération des sources depuis le SVN + >> svn co http://chorem.org/svn/choreg/trunk/choreg + +2. Compilation avec Maven + >> cd choreg ; mvn clean install + +3. Copie du jar dans le dossier des librairies communes de votre serveur d'application (ici tomcat6) + >> cp choreg/target/choreg-1.0.0.jar /usr/local/tomcat6/lib + +4. ChoReg installé !! + +Utilisation +----------- + +Pour utiliser ChoReg dans votre application, il vous faut ajouter la dépendance maven suivante :: + + <dependency> + <groupId>org.chorem.choreg</groupId> + <artifactId>choreg</artifactId> + <version>1.0.0<version> + <scope>provided</scope> + </dependency> + +A noter l'importance du scope **provided** d'où la nécessité de copier le jar de ChoReg dans le serveur d'application. + +Vos services doivent implémenter une des deux interfaces de ChoReg pour pouvoir être enregistrer : + +- ChoremService : Interface permettant la sélection des données +- ChoremUIService : Interface permettant la sélection des liens (urls) vers les données. Plus particulièrement vers leurs interfaces web. + +Implémentation de ChoremService +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PréRequis : Il est conseillé de connaître un minimum `ToPIA-persistence`_ pour mieux comprendre l'exemple + +.. _ToPIA-persistence: http://maven-site.nuiton.org/topia/topia-persistence + +Contexte de l'exemple : Vous voulez enregister un service manipulant le format xPIL (`OASIS CIQ`_ ) auprès de ChoReg. + +Note + Le format xPIL permet sous forme XML de diffuser les informations d'une personne ou une organisation (contacts, adresses, informations professionnelles, ...) + +Prenons l'exemple d'un service de manipulation des personnes, service qui a tout intérêt à pouvoir exporter ses données au format xPIL. L'implémentation du +ServicePerson va implémenter également ChoremService en plus de son interface de base utilisé pour son IHM (Interface Homme Machine). Deux méthodes permettent +la sélection des données depuis ChoReg : + +- <T> T find(Class<T> returnType, String entityId) : Permet la sélection d'une donnée bien déterminée par son identifiant (généralement un topiaId) +- <T> List<T> findAll(Class<T> returnType, String filters) : Permet la sélection d'une liste de données + +Dans notre exemple nous allons manipuler des PartyDocument qui est le type permettant l'enregistrement d'une personne au format XML xPIL. L'attribut +*returnType* permet ici d'avoir différentes possibilités de types de données. Pour simplifier, nous manipulerons que des types inclus dans la JDK, et donc +pour un fichier XML, un flux comme `XMLStreamReader`_ par exemple. L'attribut *filters* quant à lui permettra de filtrer la liste de données désirée suivant +certains paramètres (Nous détaillerons les possibilités et l'utilisation des filtres dans un autre document). + +Note + Le type PartyDocument est un type provenant de l'Api oasis-ciq-api permettant la manipulation des données du schéma XSD xPIL. Cette api est disponible en tant + que module du projet ChoReg. (voir doc `oasis-ciq-api`_ ) + +.. _OASIS CIQ: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ciq + +.. _XMLStreamReader: http://java.sun.com/javase/6/docs/api/javax/xml/stream/XMLStreamReader.html + +.. _oasis-ciq-api: http://maven-site.chorem.org/choreg/oasis-ciq-api + +Exemple du ServicePerson : + +.. image:: ../schemas/exemples/ClassDiagram_ServicePersonImpl.png + :alt: Exemple de l'implémentation du ServicePerson + +Classe d'implémentation :: + + public class ServicePersonImpl implements ServicePerson, ChoremService { + + private static final Log log = LogFactory.getLog(ServicePersonXPIL.class); + + @Override + public PersonDTO getPerson(String personId) throws Exception { + ... + } + + ... // autres implémentations de l'interface ServicePerson + + @Override + public String getFormat() { + return FormatType.OASIS_CIQ_XPIL; // Format manipulé par ce service (static provenant de ChoReg) + } + + @Override + public <T> T find(Class<T> returnType, String entityId) throws Exception { + // Récupération de l'entité avec comme identifiant "entityId" depuis la base de données ou via un DAO + // Exemple ToPIA extrait de l'application Bonzoms + TopiaContext transaction = rootContext.beginTransaction(); + PersonEntityDAO dao = BonzomsModelDAOHelper.getPersonEntityDAO(transaction); + PersonEntity entity = transaction.findByTopiaId(entityId); + transaction.closeContext(); + + // Conversion de l'entité en PartyDocument (donc en XML xPIL) + // Utilisation de l'Api Oasis CIQ (incluse dans le projet ChoReg, à utiliser indépendamment du jar choreg.jar) + PartyDocument doc = PartyDocument.Factory.newInstance(); + + PartyType party = doc.addNewParty(); + + String uri = Convert.toChoremUri(serviceClass, entity); // Conversion en choremUri (classe Convert incluse dans Chorem-commons) + // L'utilisation d'un uri chorem comme identifiant est importante pour permettre à ChoReg de plus facilement retrouver la source de l'élément. + XPILHelper.setMainIdentifier(party, uri); + + // Ajout du nom de la personne + PersonName personName = party.addNewPartyName().addNewPersonName(); + XNLHelper.addNameElement(personName, PersonNameElementList.FIRST_NAME, person.getFirstName()); + XNLHelper.addNameElement(personName, PersonNameElementList.LAST_NAME, person.getLastName()); + + ... + + if (returnType.equals(XMLStreamReader.class)) { + return doc.newXMLStreamReader(); + } + throw new WrongTypeException("Type de retour '" + returnType.getName() + "' non supporté par ServicePerson"); + } + + @Override + public <T> List<T> findAll(Class<T> returnType, String filters) throws Exception { + // même principe que pour la méthode find + } + } + +Nous avons maintenant un service opérationnel conforme à ChoReg, permettant la sélection de personnes au format xPIL. + +Enregistrement du service +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Il nous faut désormais enregister notre service auprès de ChoReg. Il est judicieux de le faire au démarrage de votre application (voir `Deploiement`_ ). +Dans l'optique de rendre indépendant votre application de ChoReg, il est préférable de gérer l'enregistrement et le désenregistrement des services auprès +de ChoReg dans une classe distincte. + +.. _Deploiement: deployment.html + +Exemple extrait de l'application Bonzoms:: + + public class RegisterBonzomsServices { + + private static final Log log = LogFactory.getLog(RegisterBonzomsServices.class); + + private static final ChoremRegistry choreg = ChoremRegistryImpl.getInstance(); // Singleton de ChoReg + + public static void startup() { + if (log.isInfoEnabled()) { + log.info("Bonzoms registration business services"); + } + choreg.register(ServicePerson.class.getName(), new ServicePersonImpl()); // Enregistrement du service + } + + public static void shutdown() { + choreg.unregister(ServicePerson.class.getName()); // Desenregistrement du service + + // En utilisant ToPIA, il est préférable de fermer proprement le rootContext à ce niveau là + try { + ContextUtilBonzoms.closeRootContext(); // ContextUtilBonzoms gère le rootContext de ToPIA + } catch (BonzomsException eee) { + if (log.isErrorEnabled()) { + log.error("Error when closing Root Context", eee); + } + } + } + } + +Récupération des données depuis une autre application +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nous allons pouvoir maintenant utiliser ChoReg dans notre autre application qui nécessite de récupérer des données au format xPIL. Comme précédemment, +il est préférable de définir une classe distincte pour la récupération des données au cas où ChoReg ne serait pas présent dans le serveur d'application. +Un exemple de Client est présent dans le projet ChoReg, il s'agit du module choreg-test-webapp, qui inclut la récupération des données au format xPIL comme +test à l'enregistrement des services depuis Bonzoms. + +Récupération d'une personne, choremUri connu :: + + try { + // Le premier attribut concerne la sécurité, cette partie est détaillée dans un autre document + XMLStreamReader result = choreg.find(null, FormatType.OASIS_CIQ_XPIL, XMLStreamReader.class, choremUri); + + // Lecture du XMLStreamReader + // ou utilisation de l'Api Oasis CIQ : + PartyDocument doc = PartyDocument.parse(result); + PartyName partyName = doc.getParty().getPartyName(); + + for (SimplifiedNameElement name : XNLHelper.getPersonNames(partyName)) { + out.println("[" + name.getType() + " : " + name.getValue() + "] "); + } + + // ou plus simplement + if (XNLHelper.hasPersonNames(partyName)) { + out.println("[" + XNLHelper.getPersonSimpleName(partyName) + "] "); // Concaténation "FirstName LastName" + } + + } catch (NoServiceException eee) { + // Pas de service correspondant au choremUri dans ChoReg + } catch (Exception eee) { + // gestion dans le cas des autres erreurs dont erreurs de parsing + } + +Récupération de toutes les donnés au format xPIL :: + + try { + // Le premier attribut concerne la sécurité + // Le dernier attribut concerne les filtres + List<XMLStreamReader> results = registry.findAll(null, FormatType.OASIS_CIQ_XPIL, XMLStreamReader.class, null); + + } catch (NoServiceException eee) { + // Pas de service manipulant le format xPIL + } catch (Exception eee) { + // gestion dans le cas des autres erreurs dont erreurs de parsing + } + +Nous avons désormais une bonne première approche de l'utilisation de ChoReg, vous pouvez désormais vous rendre sur : + +- `Deploiement`_ des applications avec utilisation de ChoReg + +- `Bonnes pratiques`_ sur l'implémentation des services enregistrés auprès de ChoReg + +- Utilisation des `Filtres`_ (TODO) + +- Gestion de la `Securite`_ avec ChoReg (TODO) + +- `Formats`_ connus et testés avec ChoReg + +.. _Bonnes pratiques: best_practices.html + +.. _Securite: security.html + +.. _Filtres: filters.html + +.. _Formats: formats.html + + Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-09 14:17:10 UTC (rev 40) +++ trunk/src/site/site.xml 2009-09-24 13:43:08 UTC (rev 41) @@ -17,15 +17,60 @@ <breadcrumbs> <item name="${project.name}" href="${project.url}" /> </breadcrumbs> - - <menu ref="modules"/> + <menu name="Présentation"> + <item name="Sommaire" href="index.html"/> + <item name="Contexte / Objectif" href="presentation/presentation.html"/> + <item name="Définitions / Api" href="presentation/api.html"/> + </menu> + + <menu name="Utilisateur" inherit="top"> + <item name="Premiers pas" href="user/start.html"/> + <item name="Déploiement" href="user/deployment.html"/> + <item name="Bonnes pratiques" href="user/best_practices.html"/> + <item name="FAQ" href="user/faq.html"/> + <item name="Sécurité" href="user/security.html"/> + <item name="Filtres" href="user/filters.html"/> + <item name="Formats" href="user/formats.html"/> + </menu> + + <menu name="Développeur" inherit="top"> + <item name="Projet Chorem Type" href="developper/project.html"/> + <item name="ChoremRegistryImpl" href="developper/details.html"/> + <item name="Todo" href="developper/todo.html"/> + </menu> + + <menu name="Recherche (Old)"> + <item name="Fondation Apache" href="recherche/apache.html"/> + <item name="Modularité" href="recherche/technos.html"/> + <item name="OSGi" href="recherche/osgi.html"/> + <item name="Applications Chorem" href="architecture/archi_chorem_part1.html"/> + <item name="Chorem-Registry" href="architecture/archi_chorem_part2.html"/> + </menu> + + <menu name="Stage"> + <item name="Sujet" href="stage/sujet.html"/> + <item name="Compte Rendus" href="stage/recapitulatif.html"/> + </menu> + + <menu name="Downloads"> + <item name="Downloads" href="http://maven.chorem.org/release/org/chorem/choreg"/> + </menu> + <menu name="Trackers"> <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="ToPIA" href="http://maven-site.nuiton.org/topia/topia-persistence"/> + <item name="Tomcat" href="http://tomcat.apache.org/"/> + <item name="OSGi" href="http://www.osgi.org/Main/HomePage"/> + <item name="Apache Felix" href="http://felix.apache.org/site/index.html"/> + <item name="Tapestry IoC" href="http://tapestry.apache.org/tapestry5/tapestry-ioc/"/> + </menu> + <menu ref="reports"/> </body>