Author: jcouteau Date: 2009-09-04 17:22:49 +0200 (Fri, 04 Sep 2009) New Revision: 2770 Added: trunk/src/site/fr/ trunk/src/site/fr/rst/ trunk/src/site/fr/rst/analyse.rst trunk/src/site/fr/rst/architecture.rst trunk/src/site/fr/rst/business.rst trunk/src/site/fr/rst/developer.rst trunk/src/site/fr/rst/index.rst trunk/src/site/fr/rst/install.rst trunk/src/site/fr/rst/tutoriel.rst trunk/src/site/fr/rst/ui.rst trunk/src/site/fr/rst/user.rst trunk/src/site/fr/rst/votecounting.rst trunk/src/site/resources/pollen.png trunk/src/site/resources/tutoriel/Creation-links.png trunk/src/site/resources/tutoriel/Creation-step1.png trunk/src/site/resources/tutoriel/Creation-step2.png trunk/src/site/resources/tutoriel/Creation-step3.png trunk/src/site/resources/tutoriel/Creation-step4.png trunk/src/site/resources/tutoriel/Results.png trunk/src/site/resources/tutoriel/Vote.png trunk/src/site/rst/analyse.rst trunk/src/site/rst/architecture.rst trunk/src/site/rst/business.rst trunk/src/site/rst/developer.rst trunk/src/site/rst/index.rst trunk/src/site/rst/install.rst trunk/src/site/rst/tutoriel.rst trunk/src/site/rst/ui.rst trunk/src/site/rst/user.rst trunk/src/site/rst/votecounting.rst trunk/src/site/site_fr.xml Modified: trunk/pom.xml trunk/src/site/resources/schemas/DC_Pollen.png trunk/src/site/resources/schemas/DC_PreventRules.png trunk/src/site/resources/schemas/DET_PollState.png trunk/src/site/resources/schemas/UC_Gestiondesvotes.png trunk/src/site/resources/schemas/composants.png trunk/src/site/resources/schemas/packages.png trunk/src/site/site.xml Log: Multi language maven site English by default and french Translation of french doc to english Modified: trunk/pom.xml =================================================================== --- trunk/pom.xml 2009-09-04 15:19:14 UTC (rev 2769) +++ trunk/pom.xml 2009-09-04 15:22:49 UTC (rev 2770) @@ -278,6 +278,9 @@ <eugene.version>1.0.0</eugene.version> <tapestry.version>5.1.0.5</tapestry.version> + <!--Multilanguage maven-site --> + <maven.site.locales>en,fr</maven.site.locales> + <!-- license to use --> <license.licenseName>gpl_v3</license.licenseName> Added: trunk/src/site/fr/rst/analyse.rst =================================================================== --- trunk/src/site/fr/rst/analyse.rst (rev 0) +++ trunk/src/site/fr/rst/analyse.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,360 @@ +Analyse +======= + +:Author: Erwan NEMA <nemawan@hotmail.com> +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2738 $ +:Date: $Date: 2009-08-20 17:12:21 +0200 (jeu 20 aoû 2009) $ + +Les besoins +~~~~~~~~~~~ + +Le projet Pollen vise à mettre en place une application de vote libre en mode Web enrichie +en fonctionnalités par rapport à ce qui existe déjà sur le marché. +Le principe est le suivant. Un utilisateur crée un sondage puis il envoie le lien aux participants du sondage. Ensuite il peut suivre l'évolution du sondage en ligne. Les participants votent en saisissant leur nom et leur choix. + +La création d'un vote doit être simple mais doit permettre les opérations suivantes : + +- définir des listes de votants +- choisir d'autres types de votes (pourcentage, Condorcet...) +- permettre à chaque votant d'ajouter de nouveaux choix de vote +- voter anonymement si on utilise une liste de votants restreinte +- relancer les personnes n'ayant pas encore voté (si liste de votants restreinte) +- définir des dates de début et de fin de vote +- définir le nombre de votes possibles par personne (1 choix ou N choix parmi les propositions) +- pouvoir ajouter un commentaire global ou à son vote +- définir avant le vote le poids des votants (si liste de votants restreinte) +- rendre graphiquement le résultat des votes +- exporter un vote dans un format standard (vote, liste de votant, résultat de votes) pour des échanges avec d'autres outils de vote. + +Les concepts généraux +~~~~~~~~~~~~~~~~~~~~~ + +Ce paragraphe présente les différents concepts manipulés dans l’application de vote. +Le tableau représente le dictionnaire de données de notre application. + +- Sondage (Poll) : Un sondage est une enquête effectuée auprès de participants (votants). + Le sondage peut porter sur une question avec multi propositions, sur un choix de date. +- Règles de fin de sondage (PreventRule) : Gestion des règles de terminaison de sondage (quotas de votants, date avant rappel, ...). +- Sondage Libre (FreePoll) : Le sondage est accessible à n’importe quel votant. +- Sondage restreint (RestrictedPoll) : Le sondage n’est accessible qu’aux personnes de la liste restreinte. +- Sondage groupe (GroupPoll) : Le sondage est accessible à plusieurs liste restreintes. +- Vote : Réponse d’un votant à la question formulée, cette réponse est enregistrée afin d’être exploitée, + l’identité du votant est connue. +- Vote anonyme (AnonymousVote) : Réponse à la question formulée sans connaître l’identité du votant. +- Type de dépouillement (VoteCounting) : Exploitation des résultats du sondage, le dépouillement peut être effectué de manière normale (comptabilisation des réponses), + dans le cas de choix multiple, selon la méthode Condorcet (un ordre de préférence est attribué à chaque réponse) où selon la méthode Condorcet en attribuant un pourcentage à chaque réponse. +- Type de vote (ChoiceType) : Définit la formulation de la question et donc la réponse à apporter + (oui/non, choix d’une heure, réponse sous forme de texte, image,….). +- Utilisateur (User) : Personne gérant le sondage, cette personne peut être identifiée ou non. +- Votant (VotingPerson) : Personne votant à un sondage. +- Créateur du sondage (PollAccount) : Personne déjà identifiée ou pas créant un sondage. +- Liste de votants prédéfinie (PersonList) : Liste de votants prédéfinie créée par un utilisateur et sauve-gardée dans le système, cette liste peut servir de base à la mise en place d’une liste de votants restreinte. +- Liste de votants (VotingList) : Liste des votants participants au sondage. +- Type de liste de votant (ListType) +- Liste de votants libre (FreeVotingList) : Liste de votants, les votants peuvent ne pas être préalablement enregistrés dans le système. +- Liste de votants restreinte (RestrictedVotingList) : Liste de votants restreinte, tous les votants sont connus et seront identifiés à partir de cette liste. +- Groupe de votants (VotingGroup) : Liste de votants restreinte pouvant faire l’objet d’une pondération globale lors d’un dépouillement (ex : groupe des développeurs). +- Commentaire globale (Comment) : Commentaire sur le sondage. +- Commentaire local (Vote.comment) : Commentaire sur un vote. + +Les types de dépouillements ++++++++++++++++++++++++++++ + +Dans un premier temps, nous allons implémenter les types de dépouillements les plus usuels. + +- Le vote simple ou libre : c'est le vote uninominal, chaque réponse recueille un suffrage, + la somme des suffrages par réponse représente les résultats du sondage. +- Le vote condorcet : le votant classe ses choix par ordre de préférence (ex a>b>c), + on compare chaque choix aux autres votes en notant les duels gagnés ou perdus, + le résultat de cette comparaison représente les résultats du sondage. +- Le vote pondéré par note : chaque choix est noté (en fonction d'un barème), + le cumul des notes par réponse représente les résultats du sondage. + +La pondération +++++++++++++++ + +Chaque votant peut ne pas avoir le même poids lors d'un vote, cette pondération aura donc des conséquences +lors du dépouillement des résultats. La pondération sur chaque votant est possible dans le cas d'une liste restreinte. +De même un groupe de votant pourra lui aussi être pondéré lors de la participation de plusieurs listes à un sondage. + +Le vote anonyme ++++++++++++++++ + +L'application permet de voter anonymement dans le cas des sondages basés sur une liste restreinte de votant. +L'anonymat est assuré pour la totalité des votants de la liste. +Dans ce cas, le vote sera comptabilisé pour le votant, mais l'application ne liera pas le vote au votant. +Le fait de fournir son identité dans le cas d'un vote anonyme (seul moyen de savoir si le votant a déjà participé au sondage) est gênant pour le votant. +Donc dans le cas du vote anonyme, le votant s'identifiera grâce à un numéro d'anonymat. +Le votant ne connaît pas le fonctionnement interne de l'application pour la gestion des votes anonymes, +cette approche le confortera concernant la prise en compte de son anonymat dans le sondage. + +Les fonctionnalités (cas d'utilisation) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Le diagramme de cas d'utilisation au format UML 2.0 de l'application permet de présenter de manière simple et concise les différents acteurs de l'application ainsi que ses fonctionnalités. +Pour rappel, le stéréotype <<includes>> précise une décomposition du use case avec une prise en compte obligatoire du cas d'utilisation inclus, le stéréotype <<extends>> précise une extension optionnel de fonctionnalité, le stéréotype <<generalize>> fait référence à la notion d'héritage. + +Les acteurs du système sont au nombre de 3 : + +- L'administrateur gère les utilisateurs et est habilité à modérer un sondage. +- L'utilisateur peut gérer un sondage et voter. +- Le votant peut voter. + +.. image:: ../schemas/UC_Gestiondesvotes.png + :alt: Les fonctionnalités + +Les cas d'utilisations « créer un sondage », « voter » et « dépouiller un sondage » seront explicités dans les paragraphes suivants. + +Créer un sondage +++++++++++++++++ + +Le scénario détaillé de la création d'un sondage. + +Acteur : + +l'utilisateur. + +Pré-conditions : + +Scénario de base : + +1. L'utilisateur choisit de créer un sondage. +2. L'utilisateur choisit le type de sondage libre. +3. L'utilisateur renseigne le titre du sondage. +4. L'utilisateur renseigne une description pour le sondage. +5. L'utilisateur saisit son nom. +6. L'utilisateur saisit le date de fin de sondage. +7. L'utilisateur choisit le type de vote options textuelles. +8. L'utilisateur saisit les différentes options. +9. L'utilisateur choisit sondage à choix unique. +10. L'utilisateur valide la création. +11. Deux URLs sont automatiquement générées par l'application : + Une URL pour administrer le sondage. + Une URL pour voter. +12. L'utilisateur est invité à sauvegarder les URLs. +13. Un email est automatiquement envoyé par l'application à l'administrateur chargé de modérer les sondages. + +Variations :: + + 1a. L'utilisateur s'authentifie. + 1a1. Si le user est black listé, la connexion est impossible, un message d'erreur apparaît. + 2a. L'utilisateur choisit un sondage de type restreint. + 2a1. L'utilisateur choisit une liste prédéfinie. + - L'utilisateur peut pondérer chaque votant de la liste pour le sondage. + 2a2. L'utilisateur choisit plusieurs listes prédéfinies (groupes). + - L'utilisateur peut pondérer chaque votant de chaque groupe + - L'utilisateur peut pondérer chaque groupe + 2a3. L'utilisateur choisit de créer une liste restreinte en saisissant le nom et l'adresse email des votants. + L'utilisateur spécifie si un choix peut être ajouté par un des votants. + L'utilisateur spécifie s'il s'agit d'un sondage anonyme. + 5a. Si l'utilisateur est black listé, la création est impossible, un message d'erreur apparaît. + 7a. L'utilisateur choisit le type de vote options de date. + 7b. L'utilisateur choisit le type de vote options d'image. + 9a. L'utilisateur peut choisir un sondage à choix multiple si le nombre d'options >2 + L'utilisateur choisit le type de dépouillement. + 10a. Si l'utilisateur s'est authentifier ou a saisi son email : le système demande si l'utilisateur souhaite recevoir un email lors de chaque vote. + 11a. Si l'utilisateur a saisi son email, un email contenant les 2 URLs du sondage est automatiquement envoyé au créateur du sondage. + 11b. Si l'utilisateur est authentifié, un mail contenant les 2 URLs du sondage est automatiquement envoyé lors de la création du sondage. + 11c. Dans le cas d'un sondage sur liste restreinte, un email contenant l'URL pour voter et l'identifiant de vote du votant est automatiquement envoyé à tous les votants du sondage. + 12a. L'utilisateur non authentifié ne sauvegarde pas les URLs : l'utilisateur ne peut pas accéder au sondage. + 13a. Si le sondage est invalidé par l'administrateur : le sondage sera supprimé, les URLs ne seront plus accessibles. + Si l'utilisateur a saisi des informations d'authentification ou possède un compte, celui ci est black listé. + +Extensions :: + + 5a. L'utilisateur saisit son nom et son email. + 5a1. voir variation 5a. + 10a. L'utilisateur peut saisir un commentaire avant de valider le sondage. + +Une illustration des actions reprenant le scénario de base et ses variations est fournie par le diagramme d'activité suivant : + + +.. image:: ../schemas/CreerSondage.jpg + :alt: Créer Sondage partie 1 + +.. image:: ../schemas/CreerSondage2.jpg + :alt: Créer Sondage partie 2 + + +Voter ++++++ + +Acteur : + +Le votant + +Pré-conditions : + +Le votant connaît l'URL du sondage. +Le sondage est accessible. + +Scénario de base : + +1. Le votant se connecte au sondage à partir d'une URL. +2. Le votant saisit son ou ses choix. +3. Le votant saisit son identifiant de vote. +4. Le votant valide son vote. + +Variations :: + + 2a. Si le sondage est restreint et si cette option est autorisé sur le sondage en cours, le votant peut ajouter un choix de vote, le créateur du sondage et tous les participants sont alertés par email de la modification du sondage. + 4a. Si le votant n'a pas saisi un identifiant de vote valide: un message d'erreur apparaît, le vote n'est pas comptabilisé. + 4b. Si le votant est black listé par le créateur du vote, il n'est pas autorisé à voter : un message apparaît, le vote n'est pas enregistré. + +Extensions :: + + 3a. L'utilisateur saisit son identifiant de vote + son email. + 3b. Le votant saisit un commentaire sur son vote. + 4a. L'utilisateur reçoit un email de confirmation de vote. + 4b. Le créateur du sondage reçoit un email concernant le vote du votant. + 4c. Le votant peut modifier son vote. + +.. image:: ../schemas/Voter.jpg + :alt: Voter + +Dépouiller les résultats +++++++++++++++++++++++++ + +Acteur + +L'utilisateur + +Pré-conditions + +Le sondage est terminé. + +Scénario de base : + +1. L'utilisateur se connecte au sondage par l'intermédiaire de l'URL +2. L'utilisateur choisit de dépouiller les résultats +3. L'application exécute l'algorithme de calcul des résultats du sondage +4. Les résultats (votants, réponses) du sondage sont affichés + +Variations :: + + 1a. L'utilisateur s'authentifie dans l'application et choisit le sondage dans une liste de ces sondages + 1a1. voir 1b + 1b. Si le sondage a déjà été dépouillé, les résultats sont affichés. + 2a. Le sondage est automatiquement dépouillé lorsque la date de fin de sondage est atteinte. + 4a. Dans le cas d'un sondage avec une liste de votants anonymes: les informations concernant les votants ne sont pas affichées. + +Extensions :: + + 4a. Les résultats peuvent être exportés au format XML. + +La chronologie des interactions entre les différentes entités définies dès l'étape d'analyse est présentée dans le diagramme de séquence d'analyse suivant : + +.. image:: ../schemas/Depouiller.jpg + :alt: Scénario de base + +.. image:: ../schemas/Depouiller_1a.jpg + :alt: Variation 1a + +Exigences non fonctionnelles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +L'application ne doit pas seulement prendre en compte les exigences formulées dans le cahier des charges par la maîtrise d'ouvrage. Un certain nombre de contraintes doivent être obligatoirement étudiées. +Ces exigences sont les suivantes : + +- Le système doit assurer la mise à disposition et la sauvegarde des informations manipulées: l'utilisation d'un SGBD permettra de gérer ces besoins concernant les données. +- L'application ne sera pas fortement liée à un SGBD du marché : l'utilisation d'une couche de persistance s'impose. +- L'application doit assurer une ergonomie et une facilité d'utilisation au moins équivalente aux produits concurrents sur le marché. +- L'application doit être totalement orientée service, toute la logique métier sera donc facilement découplée de la couche de présentation. +- Le système doit assurer aux utilisateurs une sécurité totale dans le cadre des transactions effectuées vers et à partir du serveur ainsi que dans l'utilisation même du logiciel. + Ceci implique la mise en place d'une politique de gestion de droits adéquats au niveau de l'application. + +Les classes métiers +~~~~~~~~~~~~~~~~~~~ + +Le processus d'analyse fournit le diagramme de classe cohérent de la partie données de l'application. Ce diagramme servira de base pour l'implantation du schéma de base de données. + +.. image:: ../schemas/DC_Pollen.png + :alt: Diagramme de classes d'analyse + +**Classes et commentaire associé** : + +- PollType, Type de sondage. +- ChoiceType, Type de choix. +- VoteCounting, Type de dépouillement. +- UserAccount, Utilisateur enregistré dans l'application. +- PollAccount, Compte pour un sondage englobe la notion de votant et de créateur d'une sondage. +- PersonList, Liste prédéfinie de comptes. +- VotingList, Liste de votants. +- PersonToList, Votants d'une liste. +- Vote, Vote. +- Choice, Choix de vote. +- VoteToChoice, Valeur des choix lors d'un ordre de préférence pour un sondage multichoix. + +**Classe Result** (Résultat du sondage) : + +Attribut : + +- byGroup, Indique que le résultat a été dépouillé par groupe. + +**Classe Poll** (Sondage) : + +Attributs : + +- pollId, Identifiant unique du sondage. +- beginChoiceDate, Date d'ouverture à l'ajout de choix. +- maxChoiceNb, Nombre de choix maximum pour le votant. +- choiceAddAllowed, Autorise l'ajout de choix au sondage. +- closed, Indique que le sondage est terminé. +- anonymous, Sondage avec votants et votes anonymes. +- anonymousVoteAllowed, vote anonyme autorisé. +- publicResults, Indique si les résultats du sondage sont publics. +- continuousResults, Indique si les résultats du sondage sont visibles en continue lors du vote. + +**Classe PreventRule** (Règles de notification) : + +Des règles de notification sont associées aux sondages. Elles sont utilisées pour exécuter des +actions (affichage d'un message, envoi d'un email...) en fonction de certains critères. + +Attributs : + +- method, Action à déclencher. +- scope, Contexte dans lequel l'action peut se déclencher. +- sensibility, Valeur provoquant le déclenchement de l'action. +- active, Indique si la règle est actuellement active +- oneTime, Indique si l'action doit se déclencher une seule fois (la règle est désactivée après sa première exécution). +- repeated, Indique si l'action peut se déclencher de manière répétitive (une action de sensibilité 2 est déclenché pour les valeurs 2, 4, 6, 8...). + +.. image:: ../schemas/DC_PreventRules.png + :alt: Cycle de vie d'un sondage + +La classe PreventRuleManager permet de gérer des règles de notification. Lorsque la méthode +*execute()* est appelée, la méthode définie par la règle est exécutée à condition que sa +sensibilité et sa portée soient valides. + +Exemple : affichage d'un message tous les 100 votes :: + + // Définition d'une règle : portée "vote", sensibilité 100, répétitive + PreventRuleDTO preventRule = new PreventRuleDTO("vote", 100, true, + PreventRuleManager.PRINT_ACTION); + PreventRuleManager manager = new PreventRuleManager(preventRule); + + // On lance l'exécution en précisant une portée et une sensibilité + // Le manager se charge de vérifier si l'action doit être effectuée + // en fonction de la règle et des paramètres + manager.execute("vote",100,"un message"); // affiche "un message" + manager.execute("vote",200,"autre message"); // affiche "autre message" + + // Exemples n'exécutant rien + manager.execute("scope",100); // "scope" n'est pas la bonne portée + manager.execute("vote",50); // 50 n'est pas la bonne sensibilité + +Les notifications sont utilisées dans Pollen pour envoyer un message de confirmation à la +création d'un compte, pour prévenir le créateur d'un sondage lorsque des votes ont lieu ou +pour relancer les personnes qui n'ont pas encore voté... + +Cycle de vie d'un sondage +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Initialement un sondage ne possédait que deux états : ouvert et fermé, auxquels s'ajoutait +une notion de date de début et de date de fin. Une fois qu'il a été rendu possible d'ajouter +des choix à un sondage en cours, il est devenu nécessaire d'ajouter une date de début +d'ajout de choix ainsi que les états définis dans le diagramme suivant. + +.. image:: ../schemas/DET_PollState.png + :alt: Cycle de vie d'un sondage Added: trunk/src/site/fr/rst/architecture.rst =================================================================== --- trunk/src/site/fr/rst/architecture.rst (rev 0) +++ trunk/src/site/fr/rst/architecture.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,75 @@ +Architecture de l'application Pollen +==================================== + +:Author: Florian DESBOIS <florian.desbois@gmail.com> +:Revision: $Revision: 2613 $ +:Date: $Date: 2009-06-30 15:32:57 +0200 (mar 30 jun 2009) $ + +.. image:: ../schemas/schema-architecture.png + :alt: Architecture global + +Composants +---------- + +Présentation +~~~~~~~~~~~~ + +L'application est composé de trois composants globaux distincts : + +- Presentation / IHM : Couche de présentation de l'application +- Business : Couche de persistance de l'application +- VoteCounting : Module séparé permettant la gestion des dépouillements + +.. image:: ../schemas/composants.png + :alt: Composants de l'application + +Composant IHM (pollen-ui) +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Il permet l'affichage des données à l'utilisateur. C'est la vue de notre application. +Cette partie sera faites en utilisant le framework Tapestry de Apache. + +Composant Business (pollen-business) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Le Composant Business est composé de 3 composants différents : + +- ServicesImpl : Composant qui implémente l'ensemble des services de l'application +- DAO : Couche de manipulation des entités persistantes (Creation/Modification/Suppression) +- Persistence : Composant regroupant toutes les entités persistantes. + +Le Composant Business propose 6 différentes interfaces/services disponibles pour la couche de présentation : + +- ServiceAuth : Service d'authentification à l'application (valable pour les utilisateurs ayant un compte) +- ServiceManagerUser : Service permettant la manipulation des utilisateurs (personnes ayant un compte) +- ServiceList : Service permettant la manipulation des listes de votants (groupes, favoris, ...) +- ServicePoll : Service de gestion des sondages (poll) : Création/Modification/Suppression/Modération... +- ServiceVote : Service de gestion des votes : Fonctionnalités accessible pour un votant. +- ServiceResults : Service de gestion des résultats. +- ServiceComment : Service de gestion des commentaires. + +Composant VoteCounting (pollen-votecounting) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Le Composant VoteCounting est composé de 2 composants différents : + +- VoteCountingExport : Composant permettant l'export de résultats et de sondages sous un format de fichier quelconque (ici XML par défaut) +- VoteCountingExecuter : Composant permettant la gestion des différents algorithmes de dépouillement + +Le Composant VoteCounting propose 2 différentes interfaces/services correspond respectivement à chaque composant présenté ci-dessus : + +- ServicePollExport : Service de gestion des exports d'un sondage et de ses résultats sous un format Standard +- ServiceVoteCounting : Service de gestion des dépouillements. + + +Modules Maven +------------- + +3 Modules sont créés pour géré ces différents composants : + +- UI : Couche présentation (Framework Tapestry) +- Business : Couche métier de l'application et persistance (Utilisation de ToPIA-Persistence) +- VoteCounting : Module séparé de gestion des dépouillements + + + Added: trunk/src/site/fr/rst/business.rst =================================================================== --- trunk/src/site/fr/rst/business.rst (rev 0) +++ trunk/src/site/fr/rst/business.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,56 @@ +business +======== + +:Author: +:Revision: $Revision: 2613 $ +:Date: $Date: 2009-06-30 15:32:57 +0200 (mar 30 jun 2009) $ + +DTO +--- + +Le package dto assure la communication entre le client Web et la partie persistance de l'application. +Pour des soucis de découplage et de maintenabilité, le client ne manipule pas directement les objets de la base de données et utilise donc une représentation simplifiée des entités présentes au niveau de la couche persistance. + +Le modèle de classe de dtos mis en place dans le module Pollen-Business est le suivant : + +.. image:: ../schemas/business/DC_businessDTOs.png + :alt: DTO du module Pollen-business + + +Ce modèle est centré sur la notion de sondage, par ce fait, en un seul appel distant (dans le cadre d'une architecture répartie) toutes les informations associées au sondage seront récupérées. +De plus, toujours pour prendre en compte une éventuelle évolution vers une architecture totalement distribuée, chaque dto réalise l'interface serializable permettant de sérialiser l'objet dto créé pour un transfert distant (cet aspect n'apparait pas sur le diagramme). + +Services +-------- + +Dans notre architecture orientée service, les services sont une façade donnant accés à la gestion de la persistance au client, il propose un certain nombre d'opérations en cachant leur implémentation au client . Pour ce faire il s'appuie sur le pattern DTO pour échanger des informations avec celui-ci. + +Ce modèle présente le service fourni dans le cadre de la gestion d'un sondage. + +.. image:: ../schemas/business/DC_ServicePoll.png + :alt: Services du composant Poll + +Il est nécessaire de transformer les dtos échangés avec le client en entité pour persister les données et d'effectuer l'opération inverse pour fournir des données au client. Ces opérations sont prises en compte spécifiquement pour le sondage par la classe DataPollConverter. + +De plus on remarque que dans le cadre de la gestion d'un sondage , le service peut faire appel à d'autre service tel que le service de gestion de choix, le service de gestion de commentaire. + +Créer un sondage +~~~~~~~~~~~~~~~~ + +Le diagramme de séquence montre les échanges de message entre les classes du composant Pollen-Business lors de la création d'un service. + +.. image:: ../schemas/business/DS_Conception_CreerSondage.jpg + :alt: Diagramme de séquences : Création d'un sondage + + +Persistance +----------- + +Dans le cadre de l'utilisation de l'Api Topia-Persitence, nous devons gérer un contexte global chargeant les propriétés de connexion JDBC à la base de données et fournissant des sous contextes utilisés dans le cadre de transaction vers la base de données. +Le contexte global de persistance pour l'application est géré sous forme de singleton, les classes manipulant ces concepts sont les suivantes : + +.. image:: ../schemas/business/DC_DBUtil.png + :alt: Classes Utilitaires pour la connexion à la base de données + +La classe ContextUtil permet également de charger les tables de référentiels (type de dépouillement, type de sondage, type de liste, type de choix) ne possédant pas pour l'instant d'IHM, à partir du fichier de properties pollenconfig.properties. + Added: trunk/src/site/fr/rst/developer.rst =================================================================== --- trunk/src/site/fr/rst/developer.rst (rev 0) +++ trunk/src/site/fr/rst/developer.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,19 @@ +Documentation développeur +========================= + +Vous trouverez ici toute la documentation développeur sur Pollen et ses +différents modules. + +Vous pouvez trouver de la documentation sur : + +- `Analyse des besoins et de l'existant`_ +- Architecture_ +- `Module de depouillement votecounting`_ +- `Module metier business`_ +- `Module de presentation ui`_ + +.. _Analyse des besoins et de l'existant: analysis.html +.. _Architecture: architecture.html +.. _Module de depouillement votecounting: votecounting.html +.. _Module metier business: business.html +.. _Module de presentation ui: ui.html \ No newline at end of file Added: trunk/src/site/fr/rst/index.rst =================================================================== --- trunk/src/site/fr/rst/index.rst (rev 0) +++ trunk/src/site/fr/rst/index.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,26 @@ +Bienvenue sur le site de Pollen +=============================== + +Pollen, qu'est-ce que c'est ? +----------------------------- + +Pollen est une application de vote web. Elle est destinée aux petites entitées +qui veulent un moyen simple de gérer des votes tout enrestant maîtres de leurs +données. + +Pourquoi Pollen est super ? +--------------------------- + +- Pollen permet de voter pour des textes, dates ou images. +- Vous pouvez voter anonymement. +- Vous pouvez importer des listes de votants depuis des fichiers de CSV ou des + annuaires LDAP. +- Vous pouvez importer/exporter des votes. +- Vous pouvez installer Pollen sur votre propre serveur pour garder le contrôle + de vos données (vote confidentiel par exemple). +- Pollen est basé sur les services pour pouvoir être intégré partout. +- Pollen est libre, vous pouvez le modifier, l'améliorer ou l'adapter a vos besoins. +- Pollen est super beau. + +.. image:: ../pollen.png + :alt: Pollen screenshot Added: trunk/src/site/fr/rst/install.rst =================================================================== --- trunk/src/site/fr/rst/install.rst (rev 0) +++ trunk/src/site/fr/rst/install.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,46 @@ +Installation +============ + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2760 $ +:Date: $Date: 2009-08-27 17:10:53 +0200 (jeu 27 aoû 2009) $ + +Pour installer l'application il suffit de déployer l'archive war dans un conteneur Web comme Tomcat. + +Par défaut une base de donnée H2 est créée dans le répertoire */tmp*. Pour modifier ce comportement par défaut il suffit de créer le fichier */etc/pollen.properties* et de le remplir avec les propriétés suivantes :: + + # Configuration de la base de données + hibernate.show_sql=false + hibernate.dialect=org.hibernate.dialect.H2Dialect + hibernate.connection.username=username + hibernate.connection.password=password + hibernate.connection.driver_class=org.h2.Driver + hibernate.connection.url=jdbc:h2:file://tmp/pollen/pollen + + # Répertoire des images transférées + upImgDir=/tmp/pollen/uploadedImages + + # Taille maximal des images transférées (en octets) + upload.filesize-max=1048576 + upload.requestsize-max=10485760 + + # Configuration de l'envoi d'emails automatiques + email_host=smtp.free.fr + email_port=25 + email_from=bot@pollen.org + + # Répertoire des flux de syndication (Atom) + feedDir=/tmp/pollen/feeds + + # Adresse du site (utilisée pour les emails de rappel) + siteUrl=http://www.site.org/pollen/ + +Pour une base PostgreSQL on aura :: + + hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect + hibernate.connection.driver_class=org.postgresql.Driver + hibernate.default_schema=public + +Il peut-être nécessaire de redéployer l'application après avoir modifié ce fichier. + +Un utilisateur avec les droits d'administration est créé automatiquement (identifiant "admin", mot de passe "pollen"). Par mesure de sécurité il est important de supprimer cet utilisateur après avoir créer un autre compte administrateur. Added: trunk/src/site/fr/rst/tutoriel.rst =================================================================== --- trunk/src/site/fr/rst/tutoriel.rst (rev 0) +++ trunk/src/site/fr/rst/tutoriel.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,78 @@ +Tutoriel +======== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2759 $ +:Date: $Date: 2009-08-27 17:01:18 +0200 (jeu 27 aoû 2009) $ + +Nous allons voir à travers un exemple comment créer un sondage avec Pollen. Les trois étapes nécessaires sont les suivantes : la création, le vote et la visualisation des résultats. + +Création +-------- + +La première étape consiste à fournir les informations générales à propos du sondage et de son créateur. Tous les champs ne sont pas obligatoires. Le type de sondage est défini par l'un des termes suivants : + +- **Free** : accessible à tout le monde +- **Restricted** : accessible uniquement à une liste de votants +- **Group** : accessible à plusieurs listes de votants + +Le type de dépouillement correspond à un l'un des suivants : + +- **Normal** : sélection de 1 ou n choix parmis les choix possibles +- **Percentage** : attribution d'un pourcentage à chaque choix +- **Condorcet** : classement des choix par ordre de préférence (cf `Condorcet`_ ) + +.. _Condorcet: http://fr.wikipedia.org/wiki/M%C3%A9thode_Condorcet + +.. image:: ../tutoriel/Capture.png + :alt: Création : étape 1 + +La deuxième étape permet de spécifier des options pour le sondage. Les icônes en forme de point d'interrogation permettent d'afficher des aides : + +- Sondage anonyme : les votants ainsi que leurs votes sont anonymes +- Autoriser le vote anonyme : les votants peuvent être anonymes +- Résultats continus : les résultats du sondage sont affichés en continu au moment du vote +- Résultats publics : les résultats du sondage sont consultables par tout le monde +- Autoriser l'ajout de choix : il est possible d'ajouter des choix au sondage à partir de la date donnée +- Limiter le nombre de choix par vote : le nombre de choix que l'utilisateur peut sélectionner est limité +- Recevoir des emails de notification : un email est envoyé tous les N votes pour prevenir le créateur +- Envoyer des emails de rappel : un email de rappel est envoyé aux votants qui n'ont pas encore voté N heures avant la fin du sondage + +.. image:: ../tutoriel/Capture-1.png + :alt: Création : étape 2 + +La troisième étape ne concerne que les votes restreints ou par groupe. Si vous êtes connecté vous pouvez utiliser des listes prédéfinies pour remplir les groupes de votants (le sondage sélectionné apparaît en gris). Sinon il faut saisir leurs noms et emails. Il est aussi possible de donner un poids à chaque votant ainsi qu'aux groupes. + +.. image:: ../tutoriel/Capture-2.png + :alt: Création : étape 3 + +La quatrième étape sert à indiquer les choix du sondage. Les choix peuvent être de type texte, date ou image. On peut préciser également une description par choix. + +.. image:: ../tutoriel/Capture-3.png + :alt: Création : étape 4 + +Une fois le sondage créé, une page indique deux adresses. La première est l'adresse de vote à envoyer aux votants (automatique si des emails ont été rensignés). La seconde est l'adresse de modification du sondage qui doit rester privé (elle permet aussi de clore le sondage). + +.. image:: ../tutoriel/Capture-4.png + :alt: Création : liens + +Vote +---- + +La page de vote contient un rappel des informations du sondage ainsi qu'une représentation des votes de chaque votant. Le créateur du sondage ainsi que le votant concerné peuvent modifier un vote. Si le sondage est public, il est possible de voir les résultats. De plus, l'actualité du sondage peut être suivie par flux Atom et on peut poster des commentaires. + +.. image:: ../tutoriel/Capture-5.png + :alt: Vote + +Résultats +--------- + +La page de résultats permet de visualiser les résultats du sondage sous la forme d'un diagramme. Elle rappel les informations du sondage et indique le vainqueur. Plusieurs affichage sont disponibles : cammembert, cammenbert 3D et anneau. + +.. image:: ../tutoriel/Capture-6.png + :alt: Résultats + +Autres fonctionnalités +---------------------- + +Un utilisateur identifié a accès à d'autres fonctionnalités. Il peut notamment voir la liste des sondages qu'il a créé ou auxquels il a participé. Il peut aussi créer des listes de votants manuellement ou à partir d'un fichier CSV ou d'une url LDAP. Un administrateur peut quant à lui gérer l'ensemble des sondages et des utilisateurs. Added: trunk/src/site/fr/rst/ui.rst =================================================================== --- trunk/src/site/fr/rst/ui.rst (rev 0) +++ trunk/src/site/fr/rst/ui.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,221 @@ +UI +== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2613 $ +:Date: $Date: 2009-06-30 15:32:57 +0200 (mar 30 jun 2009) $ + +L'interface web de l'application a été créée grâce au framework Tapestry de la fondation Apache. +Tapestry est un framework de développement pour applications Web J2EE dont l'architecture est à base de composants. + +Il présente de nombreux avantages : + +- peu de configuration grâce aux annotations +- fortement orienté objet : abstraction des notions de sessions, requêtes, cookies... +- séparation complète du code métier Java et de la présentation en XHTML +- feedback avancé : messages d'erreurs pertinents et complets +- rechargement à chaud : pas besoin de recompiler le code +- développement de composants facilité + +Data +---- + +Le package data contient les éléments du modèle de l'architecture de l'UI. + +UIO +~~~ + +Les UIO (User Interface Objects) sont l'équivalent des DTO du business côté UI. Les attributs des UIO sont privés et possèdent des accesseurs et des modifieurs, car le framework Tapestry manipule les objets via ces derniers. +L'interface graphique manipule directement les DTO mais il y a deux UIO qui héritent du DTO ChoiceDTO : DateChoiceUIO et ImageChoiceUIO. Ils sont utiles lors de la création des choix des sondages de type date ou image. + +.. image:: ../schemas/ui/DC_UIOs.png + :alt: Diagramme de classe des UIOs + +Lien +~~~~ + +La classe Lien représente un lien hypertext : elle possède un attribut name, qui est la chaîne de caractère sous laquelle sera affiché le lien, et un attribut address, qui est l'adresse sur laquelle pointe le lien. + +EvenOdd +~~~~~~~ + +La classe EvenOdd permet d'attribuer une classe aux lignes d'un tableau ou aux éléments d'une liste, pour les afficher en changeant les couleurs une ligne sur deux. + +PollStep +~~~~~~~~ + +L'énumération PollStep représente les étapes du formulaire de création/modification de sondage. + +Composants +---------- + +Border +~~~~~~ + +Le composant Border est un composant présent sur toutes les pages de l'application : il s'agit du menu, de la barre d'adresse et du pied de page. +Il prend en paramètres un Array de Liens, qui servira à créer la barre d'adresse, et un type de page (Creation, Index, Vote ou VoteCounting) qui détermine le logo et les couleurs de la page. + +.. image:: ../schemas/ui/topIndex.png + :alt: Border Index + +.. image:: ../schemas/ui/topCreation.png + :alt: Border Création + +.. image:: ../schemas/ui/topCount.png + :alt: Border VoteCounting + +.. image:: ../schemas/ui/topVote.png + :alt: Border Vote + +LoginComponent +~~~~~~~~~~~~~~ + +Ce composant est un formulaire de connexion qui est affiché quand l'utilisateur essaye d'accéder à une page pour laquelle il doit être identifié. + +DateTimeField +~~~~~~~~~~~~~ + +Ce composant est un type de champ de formulaire permettant de sélectionner une date et une heure. + +.. image:: ../schemas/ui/dateTimeField.png + :alt: Composant DateTimeField + +FeedBack +~~~~~~~~ + +Le composant FeedBack gère l'affichage des messages à destination de l'utilisateur. Ces messages ont une apparence différente selon leur signification. Par exemple un message d'erreur ressortira plus qu'un message d'information. Le composant permet donc d'afficher ces types de messages lors du rendu de la page. Il est possible d'afficher plusieurs messages de types différents en même temps. Ceux-ci ne seront affichés qu'une seule fois et aussitôt supprimés. Ce composant se comporte un peu comme le composant Tapestry Error qui affiche les erreurs de validation des formulaires. + +.. image:: ../schemas/ui/feedBack.png + :alt: Composant FeedBack + +Pour personnaliser l'apparence des messages, il faut définir les classes *fb-error* et *fb-info* dans le CSS. Dans le template il suffit de placer la balise du composant :: + + <t:feedback t:id="feedback"/> + +Dans la classe, après avoir déclaré le composant, il est possible d'ajouter des messages :: + + @Component(id = "feedback") private FeedBack feedback; + + feedback.addInfo("message d'info"); + feedback.addError("message d'erreur"); + +Image +~~~~~ + +Le composant Image sert à afficher une image dynamique, telle qu'une image téléchargée sur le serveur grâce à un formulaire. À priori, on ne connaît pas le nom du fichier correspondant à l'image, on ne peut donc pas utiliser d'asset pour l'afficher de la manière suivante :: + + <img src="${asset:context:img}/image.png" /> + +Le composant crée une élément HTML de type image en l'associant à un flux de type ImageStreamResponse :: + + <t:image src="/img/image.png" /> + +Chart +~~~~~ + +Le composant Chart affiche un diagramme de type camembert (PieChart). Pour cela il utilise la librairie JFreeChart et convertit le résultat en une image facilement intégrable dans une page Web :: + + <t:chart width="210" height="190" values="choice" title="title" type="1"/> + +Le paramètre *values* correspond à une liste de chaînes représentant les labels et leur valeurs respectives (exemple : {"val1", "20", "val2", "10"}). Le paramètre *type* est le type de représentation du diagramme (1:PIE, 2:PIE3D, 3:RING). + +.. image:: ../schemas/ui/chart.png + :alt: Composant Chart + +Pages +----- + +Les pages sont à la fois la vue et le contrôleur de l'architecture. Cependant chaque page est représentée par trois fichiers : + +- un template .tml (la vue) qui contient le code HTML et les composants Tapestry +- une classe Java (le contrôleur) qui initialise les composants et les données traîtées, qui définit les actions associées aux composants et qui utilise la classe BusinessServices du package services pour appeler les services du business. +- un fichier .properties (ou plusieurs pour l'internationalisation) qui contient les messages affichés sur la page. + +Création d'un sondage +~~~~~~~~~~~~~~~~~~~~~ + +La page de création de sondage permet de créer un sondage en renseignant : + +- le titre du sondage (obligatoire) +- la description du sondage +- une date de début et une date de fin +- le nom du créateur (obligatoire) +- l'anonymat du sondage +- la possibilité pour les utilisateurs d'ajouter des choix +- l'envoi d'email au créateur en cas de vote ou de commentaires +- le type de choix (texte, image ou date) +- les différents choix et leur description + +L'application ne gère pas encore la date de début et la date de fin, ni l'envoi d'email, ni la possibilité d'ajouter des choix. +Lorsque les choix sont des images, les fichiers sont envoyés sur le serveur. En revanche, l'endroit où elles sont enregistrées reste à configurer. +Si la création du sondage réussit en base, alors une page de confirmation est affichée et fournit à l'utilisateur deux liens : un pour voter, qu'il pourra envoyer aux personnes qu'il souhaite voir voter, et l'autre pour modifier ou clore le sondage. + +Modification d'un sondage +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Les champs pouvant être modifiés sont les suivants : + +- le titre +- la description du sondage +- le nom du créateur +- les dates (même si à terme, il faudra déterminer des conditions) +- l'envoi d'email +- l'ajout de choix +- la description des choix + +Cette page prend en argument l'identifiant Topia haché en MD5 du sondage concaténé à l'identifiant Topia haché du créateur. +C'est également sur cette page qu'il pourra clore le sondage pour pouvoir le dépouiller. + +Vote +~~~~ + +Cette page permet à un utilisateur de voter à un sondage. Il doit renseigner son nom et cocher ou non une pou plusieurs cases. +Cette page permet aussi d'ajouter des commentaires au sondage. +Cette page prend en argument l'identifiant Topia haché en MD5 du sondage. + +Les votes portant sur des images nécessitent de pouvoir télécharger ces images sur le serveur. Le composant Tapestry Upload permet de faire ceci simplement en le plaçant dans un formulaire et en enregistrant le fichier ainsi soumis (UploadedFile) dans un répertoire du serveur. De plus il est possible de limiter la taille des fichiers dans la classe AppModule (méthode *contributeApplicationDefaults()*) :: + + configuration.add(UploadSymbols.FILESIZE_MAX, "500000"); + configuration.add(UploadSymbols.REQUESTSIZE_MAX, "5000000"); + +La miniature correspondant à l'image est créée une fois pour toutes lors de sa soumission afin de ne pas surcharger le serveur en redimensionnant les images à chaque fois qu'un client les consulte. +Par contre il n'est pas aussi aisé d'afficher ces images par la suite à cause du fonctionnement de Tapestry. Un composant Image à donc été créé pour remplir cette fonction. + +Résultats +~~~~~~~~~ + +La page de résultats utilise le composant Chart pour afficher les résultats d'un sondage. Ces derniers sont récupérés grâce au service ServiceResults. + +Sondages d'un utilisateur +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Si l'utilisateur qui crée un sondage est enregistré et connecté à son compte, le sondage est relié à son compte dans la base de données. Il pourra alors ultérieurement consulter la liste des sondages qu'il a créé. Ceci lui permet de pouvoir récupérer les URL des pages de vote ou de modification s'il les a perdues. + +Listes de votants +~~~~~~~~~~~~~~~~~ + +Les listes de votants peuvent être créées à la main en renseignant les informations de chaque votant mais il est aussi possible d'importer une liste de votants à partir d'un fichier CSV. La lecture d'un fichier CSV est réalisée grâce à la librairie Java OpenCSV qui permet de définir une stratégie de mapping pour convertir directement les champs en objets. + +L'utilisateur identifié peut gérer des listes de votants. Lorsqu'il créera un sondage restreint, il pourra utiliser ses listes de votants prédéfinies plutôt que de saisir manuellement la liste de votants pour le sondage. + +Services +-------- + +Tapestry est livré avec de nombreux services qui font partie intégrante du framework, mais il est aussi possible de définir ses propres services. Dans la classe AppModule, qui contient le peu de configuration nécessaire au fonctionnement de Tapestry, on peut lier ses services en complétant la méthode *bind(ServiceBinder binder)* :: + + binder.bind(ServicePoll.class, ServicePollImpl.class); + +Une fois que Tapestry connaît l'interface et l'implémentation du service, on peut l'injecter dans les pages de l'application et l'utiliser normalement :: + + @Inject + private ServicePoll servicePoll; + +Configuration +~~~~~~~~~~~~~ + +En plus des services métiers définis dans le module pollen-business, un service propre à Pollen-UI permet d'accéder à la configuration de l'application (serveur de mails, répertoire des images...). Ce service lit la configuration dans un fichier *properties* lors de son instanciation. + +BackgroundWorker +~~~~~~~~~~~~~~~~ + +Un autre service, BackgroundWorker, permet d'effectuer des tâches en arrière-plan. Ce service est utile pour envoyer des emails à intervalle de temps régulier. Added: trunk/src/site/fr/rst/user.rst =================================================================== --- trunk/src/site/fr/rst/user.rst (rev 0) +++ trunk/src/site/fr/rst/user.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,10 @@ +Documentation utilisateur +========================= + +Vous trouverez ici toute le documentation utilisateur disponible pour Pollen. + +Vous pouvez trouver un `guide d installation`_ et un tutoriel_ pour apprendre à +créer un sondage, voter et dépouiller les résultats à la fin. + +.. _guide d installation: install.html +.. _tutoriel: tutoriel.html \ No newline at end of file Added: trunk/src/site/fr/rst/votecounting.rst =================================================================== --- trunk/src/site/fr/rst/votecounting.rst (rev 0) +++ trunk/src/site/fr/rst/votecounting.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,153 @@ +VoteCounting +============ + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2613 $ +:Date: $Date: 2009-06-30 15:32:57 +0200 (mar 30 jun 2009) $ + +Cette partie décrit l'implémentation du module VoteCounting. + +2 Interfaces existent : + +- ServiceVoteCounting : Service de gestion des dépouillements. +- ServicePollExport : Service de gestion des exports d'un sondage et de ses résultats sous un format Standard, + +ServiceVoteCounting +------------------- + +DTOVoteCounting +~~~~~~~~~~~~~~~ + +Les DTOVoteCounting (Data Transfert Object) permettent d'utiliser convenablement les interfaces proposés par le module VoteCounting. + +Il y a deux DTO racines importants : + +- PollDTO : Correspond à un sondage et tous les éléments importants pour le dépouillement. +- VoteCountingResultDTO : Le résultat du dépouillement organisé suivant les choix possibles du sondage. + +PollExportDTO a été ajouté dans le cas d'un Import, il contient un PollDTO et plusieurs VoteCountingResultDTO. + +Deux énumérations sont également disponibles et permettent la normalisation des types : + +- PollType : Type de sondage (Groupe, Libre, Restreint, ...) +- VoteCountingType : Type de dépouillement (Condorcet, Pourcentage, ...) + +A noté que le VoteCountingType sert de référence pour le dépouillement d'un sondage. + +.. image:: ../schemas/votecounting/DC_VoteCountingDTOs.png + :alt: DTO du module VoteCounting + +**PollDTO** + +Il est composé de PollChoiceDTO qui sont les choix du sondage, et de CommentDTO qui sont les commentaires du sondage. + +Il est composé de VotingGroupDTO. Ce dernier correspond à un groupe de votant dans le cas d'un sondage de type groupe. Il existera un et un seul groupe si le sondage est d'un autre type et aura des valeurs nulles à ses paramètres (weight et idGroup). + +Chaque VotingGroupDTO est composé de VotingPersonDTO correspondant aux votants liés au sondage (personnes ayant votées). Le votingID sera égal à "anonymous" dans le cas d'un sondage anonyme. + +Chaque VotingPersonDTO est composé de VoteToChoiceDTO correspondant aux votes du votant (pour chaque choix, une valeur). + +A noté qu'il n'est pas nécessaire de connaître l'ensemble des choix à l'avance au niveau du sondage. Le dépouillement se chargera de réorganiser les résultats suivant les choix possibles. + +**VoteCountingResultDTO** + +Les résultats sont donc répartis suivant les choix possibles du sondage. Un ResultDTOV est donc composé de ChoiceDTOV correpondant à ces choix. + +Nous avons donc pour un sondage donné : + +- le résultat global (VoteCountingResultDTO.choiceResult) +- le résultat par choix (ChoiceDTO.value) + +Operations +~~~~~~~~~~ + +- executeVoteCounting(poll : PollDTO) : VoteCountingResultDTO + +Cette opération permet l'exécution du dépouillement d'un sondage. + +- executeGroupCounting(poll : PollDTO) : VoteCountingResultDTO + +Cette opération permet l'exécution du dépouillement d'un sondage en fonction des groupes. + + +Implémentation +~~~~~~~~~~~~~~ + +Le Pattern Strategy est utilisé pour gérer le dépouillement. Une classe Context permet de définir quel type de stratégie employé. +La stratégie est définie dès le départ via l'attribut typeVoteCounting du PollDTO. + +Ici les stratégies sont représentés par l'interface Method qui sera implémenté par : + +- CondorcetMethod : Dépouillement selon la méthode Condorcet +- StandardMethod : Dépouillement simple +- PercentageMethod : Dépouillement selon une pondération des choix + +Chaque méthode implémente l'opération "executeMethod(choices)" qui sera appelé dans la classe Context par l'opération "execute()". +Ainsi le contexte doit connaître l'ensemble des choix et des votes pour chaque choix et par groupe. + +A l'appel du ServiceVoteCounting, un nouveau contexte sera créé et le PollDTO sera parcouru pour créer les choix, groupes et votes nécessaires au dépouillement qui sera executé. + +.. image:: ../schemas/votecounting/DC_ServiceVoteCountingImpl.png + :alt: Diagramme d'implémentation du service VoteCounting + +Execution +~~~~~~~~~ + +- Appel à executeVoteCounting +- Création du contexte dépendant de PollDTO.typeVoteCounting +- Parcours des PollChoiceDTO : Ajout des choix au contexte +- Parcours des VotingGroupDTO : Pour chaque groupe -> VoteCounting.routeGroup(VotingGroupDTO) (avec ajout du groupe au contexte Context.addGroup(idGroup, weight)) +- Parcours des VotingPersonDTO : Pour chaque personne -> VoteCounting.routePerson(VotingPersonDTO) +- Parcours du Vote : Pour chaque choix -> ajout au contexte via Context.getChoice(idChoice).getGroup(VoteCounting.currentIdGroup).addVote(value, weight) +- Execution de la méthode de dépouillement -> Context.execute() +- Création du VoteCountingResultDTO qui contient l'ensemble des choix avec leurs résultats + +.. image:: ../schemas/votecounting/Seq-executeVoteCounting.png + :alt: Diagramme de séquence de l'exécution d'un dépouillement simple (sans détails de l'algorithme) + +Dépouillement Condorcet +~~~~~~~~~~~~~~~~~~~~~~~ + +Avec un système de vote classique, le vainqueur est le candidat qui possède le plus grand nombre de voix. Avec la méthode de dépouillement Condorcet ce n'est pas forcément le cas. Le vainqueur est celui qui, comparé à chaque autre candidat, est toujours préféré. +Dans certaines situations un tel vainqueur n'existe pas, c'est ce que l'on appelle le paradoxe de Condorcet (A>B>C>A). L'algorithme choisi dans Pollen consiste à choisir le candidat qui a gagné le plus de confrontations. En cas d'ex aequo un vote doit être refait avec le groupe de tête. +Le déroulement du vote par Condorcet est le suivant : + +1. Les votants classent les candidats par ordre de préférence +2. Pour chaque vote, on compare les classements des candidats par paires et on compte le nombre de victoires de chaque candidat +3. Le gagnant est celui qui possède le plus grand nombre de victoires + +Dans Pollen, l'implémentation du vote par Condorcet comporte en plus la notion de groupes de votants. En cas de dépouillement par groupes, l'algorithme est appliqué au sein de chaque groupe. Ensuite l'algorithme est appliqué une seconde fois sur les résultats des groupes. +Lorsque les votants participent à un vote, il leur est possible de classer deux choix à égalité. Il n'est pas nécessaire de classer tous les choix, ceux qui ne sont pas classés seront considérés comme derniers à égalité. + + +ServicePollExport +----------------- + +Operations +~~~~~~~~~~ + +- executeExport(export : PollExportDTO) : String + +C'est l'opération principale qui permet l'export du sondage, l'objet passé en paramètre contien l'objet poll qui n'est que le sondage, et une liste des résultats à exporter ces résultat sont obtenus par les différents types de dépouillement. Cette méthode retourne le nom du fichier exporté. + +- executeImport(path : String) : PollExportDTO + +Cette opération importe le sondage et ces résultats qui sont dans le fichier dont le chemin est passé en paramètre, donc reconstruit l'objet PollExportDTO, qui est retourné par cette opération. + + +Implémentation de l'export +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Une simple implémentation a été faite pour cette partie, il s'avère que l'utilisation du pattern Visitor est significative pour l'implémentation de ce module vu qu'il fonctionne de la même manière que Visitor, cependant pour mettre cette possibilité en œuvre il va falloir ajouter des métodes aux classes DTOs ce qui viole leur sémantique, donc on a procédé comme montrer dans le schéma suivant. + +.. image:: ../schemas/votecounting/DC_ServiceExportImpl.png + :alt: Diagramme d'implémentation du service PollExport + + +Résultat d'un export +~~~~~~~~~~~~~~~~~~~~ + +Pour concevoir le module d'export d'un sondage géré par l'application Pollen, il a fallu qu'on spécifie le résultat souhaité, pour ce faire on est parti sur une modélisation UML afin d'extraire l'architecture en arborescence de notre export, voir le diagramme de classe suivant : + +.. image:: ../schemas/votecounting/DC_ServiceExportXML.png + :alt: Diagramme de classe de l'export d'un sondage et ces résultats Added: trunk/src/site/resources/pollen.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/pollen.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: trunk/src/site/resources/schemas/DC_Pollen.png =================================================================== (Binary files differ) Modified: trunk/src/site/resources/schemas/DC_PreventRules.png =================================================================== (Binary files differ) Modified: trunk/src/site/resources/schemas/DET_PollState.png =================================================================== (Binary files differ) Modified: trunk/src/site/resources/schemas/UC_Gestiondesvotes.png =================================================================== (Binary files differ) Modified: trunk/src/site/resources/schemas/composants.png =================================================================== (Binary files differ) Modified: trunk/src/site/resources/schemas/packages.png =================================================================== (Binary files differ) Added: trunk/src/site/resources/tutoriel/Creation-links.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Creation-links.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/tutoriel/Creation-step1.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Creation-step1.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/tutoriel/Creation-step2.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Creation-step2.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/tutoriel/Creation-step3.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Creation-step3.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/tutoriel/Creation-step4.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Creation-step4.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/tutoriel/Results.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Results.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/resources/tutoriel/Vote.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/resources/tutoriel/Vote.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Copied: trunk/src/site/rst/analyse.rst (from rev 2767, trunk/src/site/rst/developper/analyse.rst) =================================================================== --- trunk/src/site/rst/analyse.rst (rev 0) +++ trunk/src/site/rst/analyse.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,388 @@ +Analysis +======== + +:Author: Erwan NEMA <nemawan@hotmail.com> +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision$ +:Date: $Date$ + +The needs +~~~~~~~~~ + +Pollen project is aimed to create a libre poll application with a web interface +and more functionalities regarding the other similar application already existing. +The principle is : a user create a poll and then send the link to the voters. +He can then follow the poll progression online. The voters vote by filling their +name and their vote. + +The poll creation have to be easy but allow the following operations : + +- define voters lists +- chose the vote counting principle (percentage, Condorcet,...) +- allow every voter to add new choices +- vote anonymously if we use a restricted list of voters +- send reminders to people who did not vote (if restricted voters list) +- define begin and end dates for polls. +- define the number of votes possible per personne (1 choice or N choices amongst +the propositions) +- be able to add a global comment or to his vote. +- define, before the vote, the weight of each voter (if restricted voters list) +- represent graphically the poll results +- export a poll in a standard format (poll, voters lists, poll results) for +exchanges with other poll tools. + +Global concepts +~~~~~~~~~~~~~~~ + +This paragraph presents the different concepts manipulated by the poll application. +The table represents this application's data table. + +- Poll (Poll) : a poll is a survey with is taken by participants (voters). +The poll/survey can focus on a question with multi-answers, a date choice. +- Prevent rule (PreventRule) : management of poll end rules (voters quota, date before reminder, ...). +- Free poll (FreePoll) : the poll is available for anybody. +- Restricted poll (RestrictedPoll) : the poll is available only for the restricted list members. +- Group poll (GroupPoll) : the poll is available for members of more than one restricted list. +- Vote : answer from a votter to the question, this answer is stored before beeing +processed, the voters identity is then known. +- Anonymous vote (AnonymousVote) : answer from a voter to the question asked without knowing the voter's identity. +- Vote counting type (VoteCounting) : Poll results utilizing, the vote counting can be done +normally(just counting the votes), in the case of multiple choice with Condorcet +method (a preference order is attributed to choice), or by attributing a percentage +to each choice. +- Choice type (ChoiceType) : Define the question and so the answer/choice type (yes/no, hour choice, +date choice, text, picture,...) +- User (User) : People managing the poll, this person can be logged in or not. +- Voter (VotingPerson): People voting in a poll. +- Poll creator (PollAccount): Person already logged in or not, creating a poll. +- Voters predefined list (PersonList) : Voters predefined list created by a user and stored +in the system. This list can be the base for a voters restricted list. +- Voters list (VotingList) : List of voters participating in a poll. +- Voters list type (ListType) : +- Free voters list : Voters list, voters may not need to have an account on pollen. +- Restricted voters list (RestrictedVotingList): Voters restricted list, all the voters are known and +will be identified from this list. +- Voting group (VotingGroup): Restricted list of voters that might be globally balanced when counting votes (ex : developers group) +- Global comment (Comment): Comment on the poll +- Local comment (Vote.comment): Comment on a vote. + +Vote counting types ++++++++++++++++++++ + +For first versions, we implement usual vote counting : + +- Simple or free vote : this is the vote for a single answer, each answer gets votes, the +sum of the votes for each answer represent the poll results. +- Condorcet vote : the voter sort his choices by preference order (ex a>b>c), we +compare each choice to the other votes by counting the won or lost duels, +the results of this comparison represents the poll results. +- Grade balanced vote : each choice is graded (function of a scale), +the sum of the grades per answer represents the poll results. + +Balancing ++++++++++ + +Each voter may not have the same weight in a vote, so this balancing will have +consequences when counting votes. The balancing of each voter is possible in a +restricted list. +It is also possible to balance group of voters when several voters lists participate +to a poll. + +Anonymous vote +++++++++++++++ + +The application allows to vote anonymously in case of polls based on restricted +list of voters. The anonymity is guaranteed for all the voters of the list. +In this case, the vote will be counted for the voter, but the application will +not link the voter to the vote. +Giving its identity when voting anonymously can annoy the voter. So in the case +of an anonymous vote, the voter will identify himself with a anonymity number. +The voter does not know how the application works for anonymous votes, this +approach will reinsure him regarding his annonimity. + +Functionalities (Use cases) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The application use case diagram in UML 2.0 format allows to present in a easy +and concise way the different application actors and functionalities. +As a reminder, the <<includes>> stereotype precise a use case decomposition with +a mandatory consideration of included use case, the <<extends>> stereotype +precise an optional functionality extension, the <<generalize>> stereotype makes +reference to the inheritance notion. + +There are 3 actors in the system : + +- The administrator manage users and can moderate polls. +- The user can manage a poll and vote +- The voter can vote. + +.. image:: schemas/UC_Gestiondesvotes.png + :alt: Functionalities + +The use cases "create a poll" (créer un sondage), "vote" (voter) and "count a +poll's votes" (dépouiller un sondage) will be explained in the following +paragraphs. + +Create a poll ++++++++++++++ + +The detailed scenario of poll creation. + +Actor : + +the user + +Pre-conditions : + +Base scenario : + +1. The user chose to create a poll. +2. The user chose the free poll type. +3. The user fill the poll title. +4. The user fill the poll description. +5. The user fill his name. +6. The user chose a end date for the poll. +7. The user chose the textual vote option type. +8. The user fill the different options in. +9. The user chose a unique choice poll. +10. The user validate the creation. +11. 2 URLs are automatically generated by the application : + One URL to administrate the poll. + One UTL to vote. +12. The user is invited to save those URLs. +13. An email is automatically sent by the application to the administrators +(who can moderate polls). + +Variations :: + + 1a. The user authenticate himself. + 1a1. If the user is black-listed, the connexion is impossible, an error message is displayed. + 2a. The user chose a restricted type poll. + 2a1. The user chose a predefined list. + - The user can balance each voter of the list for the poll. + 2a2. The user chose several predefined lists (groups). + - The user can balance each voter of each group. + - The user can balance each group. + 2a3. The user chose to create a restricted list by filling in voters name and email adress. + The user specifies if choices can be added by voters. + The user specifies if it is an anonymous poll. + 5a. If user is blacklisted, creation is not possible, an error message is shown. + 7a. The user chose to vote for dates. + 7b. The user chose to vote for images. + 9a. The user can chose a multiple choice poll is the number of option is more than 2. + The user chose the vote counting type. + 10a. If the user is authenticated or filled his email in, the system ask if the user wants to receive an email for each vote. + 11a. If the user filled in his email, an emails with the 2 poll's URLs is automatically sent to the poll creator. + 11b. If the user is authenticated, an email with the 2 poll's URLs is automatically sent when the poll is created. + 11c. In the case of a poll on a restriucted list, an email with a link to vote and the voters login is sent to every voter of the poll. + 12a. The non authenticated user does not save the URLs : the user cannot reach the polls anymore. + 13a. If the poll is unvalidated by the administrator : the poll is deleted, the URL cannot be reached anymore. + If the user gave authentication information or is logged, he is blacklisted. + +Extensions :: + + 5a. The user gives his name and email. + 5a1. see variation 5a. + 10a. The user can write a comment before validating the poll. + +A figure of the actions based on the base scenario and its variations follows : + + +.. image:: schemas/CreerSondage.jpg + :alt: Create Poll part 1 + +.. image:: schemas/CreerSondage2.jpg + :alt: Create Poll part 2 + + +Vote +++++ + +Actor : + +Voter + +Pre-conditions : + +The voter knows the poll URL. +The poll is reachable. + +Base scenario : + +1. The voter connects to the poll from a URL. +2. The voter selects his choice(s). +3. The voter fills in his login. +4. The voter submits his vote. + +Variations :: + + 2a. If the poll is restricted and this option is autorised on the current poll, the voter can add a poll choice. The poll creator and all the participants are alerted by email of the poll modification. + 4a. If the voter did not filled in a valid login : an error message is shown, the vote is not counted. + 4b. If the voter is black listed by the poll creator, he is not allowed to vote : an error emssage is shown, the vote is not taken into account. + +Extensions :: + + 3a. The user fills in his vote login and email address. + 3b. The voter writes a comment on his vote. + 4a. The user receive a vote confirmation email. + 4b. The poll creator receives an email regarding the voter's vote. + 4c. The voter can modify his vote. + +.. image:: schemas/Voter.jpg + :alt: Vote + +Count the votes ++++++++++++++++ + +Actor + +The user + +Pre-conditions + +The poll ended. + +Base scenario : + +1. The user can connect to the poll by the URL. +2. The user chose to count the votes. +3. The application runs the vote counting algorythm. +4. The results (voters, answers) of the poll are displayed. + +Variations :: + + 1a. The user authenticate in the application and chose the poll from his polls list. + 1a1. see 1b + 1b. If the votes have already been counted, the results are displayed. + 2a. The votes are automatically counted when the poll's end date is reached. + 4a. In the case of a poll with an anonymous list of voters : the voters informations are not displayed. + +Extensions :: + + 4a. The result can be exported to XML format. + +The interactions chronology between the different entities defined in the analysis +step is presented in the following sequence diagram : + +.. image:: schemas/Depouiller.jpg + :alt: Base scenario + +.. image:: schemas/Depouiller_1a.jpg + :alt: Variation 1a + +Non functional requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The application does not need to only follow the requirements stated in the +project specifications. Several constraints have to be studied. + +Those constraints are : + +- The system have to store and restore manipulated informations : a DBMS use will +manage those needs. +- The application will not by strongly linked to any DBMS on the market : the +use of a persitence layer is mandatory. +- The application have to be service oriented, all the business layer will be +separated from the presentation layer. +- The system have to insure full security to the user for transactions done from +and to the server and in the software use itself. This implies a proper right +management at the application level. + +The business classes +~~~~~~~~~~~~~~~~~~~~ + +The analysis process gives the data part of the application's coherent class diagram. +This diagram will be the base for the implementation of the database scheme. + +.. image:: schemas/DC_Pollen.png + :alt: analysis class diagram. + +**Classes and associated comment** : + +- PollType, Poll type. +- ChoiceType, Choice type. +- VoteCounting, Vote count type. +- UserAccount, User logged in the application. +- PollAccount, Account for a poll, gather the voter and poll creator notion. +- PersonList, Predefined list of accounts. +- VotingList, Voters list. +- PersonToList, Voters from a list. +- Vote, Vote. +- Choice, Vote choice. +- VoteToChoice, Choice value when using preference order in a multichoice poll. + +**Result class** (poll results) : + +Attribute : + +- byGroup, Indicate that the votes have been counted by groups. + +**Poll class** (poll) : + +Attributes : + +- pollId, unique poll id. +- beginChoiceDate, Choice adding begin date. +- maxChoiceNb, Maximum choice number for a voter. +- choiceAddAllowed, Allow adding choices to poll. +- closed, Indicate that the poll is closed. +- anonymous, Poll with anonymous votes and voters. +- anonymousVoteAllowed, Anonymous vote allowed. +- publicResults, Indicate wether the poll's results are public or not. +- continuousResults, Indicate wether the polls results are visible while people +are voting. + +**PreventRule class** (notification rules) : + +Notification rules associated to the polls. They are used to execute actions +(message displaying, email sending,...) depending on various criteria. + +Attributes : + +- method, action to launch. +- scope, context in which the action can be launched. +- sensibility, value firing the action launch. +- active, Indicate if the rule is active +- oneTime, Indicate if the action can be launched only one time (the rule is +unactivated after its first launch). +- repeated, Indicate if the action can be launched repeatedly (an action with +sensibility 2 will be launch for values 2, 4, 6, 8, ...). + +.. image:: schemas/DC_PreventRules.png + :alt: Poll's lifecycle. + +The PreventRuleMAnager class allows to manage notifications rules. When the +*execute()* method is called, the method defined by the rule is executed if its +sensibility and context are valid. + +Example : Display a message every 100 votes :: + + // Define a rule : context : "vote", sensibility 100, repeatable + PreventRuleDTO preventRule = new PreventRuleDTO("vote", 100, true, + PreventRuleManager.PRINT_ACTION); + PreventRuleManager manager = new PreventRuleManager(preventRule); + + // We launch the execution by precising a context and a sensibility + // The manager verifies if the action have to be executed regarding the rule + // and the parameters. + manager.execute("vote",100,"un message"); // display "un message" + manager.execute("vote",200,"autre message"); // display "autre message" + + // Examples doing nothing + manager.execute("scope",100); // "scope" is not the right context + manager.execute("vote",50); // 50 is not the right sensibility + +Notifications are used in Pollen to send confirmation message when creating an +account, alert a poll creator when they are new votes or remind people they did +not vote... + +Poll's lifecycle +~~~~~~~~~~~~~~~~ + +At the beginning, a poll had only two states : open and closed, to which the +begin and end dates notion was linked. Once it was possible to add choices to a +poll, it has been necessary to add a begin and end date for choice adding and +the states describes in the following figure : + +.. image:: schemas/DET_PollState.png + :alt: Poll's lifecycle Property changes on: trunk/src/site/rst/analyse.rst ___________________________________________________________________ Added: svn:keywords + Date Author Revision Rev Id Added: svn:mergeinfo + Copied: trunk/src/site/rst/architecture.rst (from rev 2767, trunk/src/site/rst/developper/architecture.rst) =================================================================== --- trunk/src/site/rst/architecture.rst (rev 0) +++ trunk/src/site/rst/architecture.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,75 @@ +Pollen architecture +=================== + +:Author: Florian DESBOIS <florian.desbois@gmail.com> +:Revision: $Revision$ +:Date: $Date$ + +.. image:: schemas/schema-architecture.png + :alt: Global architecture + +Components +---------- + +Presentation +~~~~~~~~~~~~ + +The application is based on three distinct global components : + +- pollen-ui : application presentation layer +- pollen-business : application persistence layer +- pollen-votecounting : separated module doing vote counting + +.. image:: schemas/composants.png + :alt: Application components + +UI Component (pollen-ui) +~~~~~~~~~~~~~~~~~~~~~~~~ + +It allows data display to the user. This is our application view. +This part is made using Tapestry framework from Apache. + +Business component (pollen-business) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The business component is coumpounded of three different comonents : + +- ServicesImpl : Component that implements all the application services +- DAO : Persistent entities manipulation layer (Creation/Modification/Deletion) +- Persistence : Component gathering all the persistent entities. + +The business component offers six different interfaces/services to the presentation layer : + +- ServiceAuth : Authentication service (for users having an account) +- ServiceManagerUser : Users management service (for users having an account) +- ServiceList : Voters list management service (groups, bookmarks,...) +- ServicePoll : Poll management service : Creation/Modification/Deletion/Moderation... +- ServiceVote : votes management service (Functionalities availale for a voter) +- ServiceResults : Result management service +- ServiceComment : Comments management service. + +Vote counting component(pollen-votecounting) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The vote counting component is compounded of two different components : + +- VoteCountingExport : Component allowing polls and results exports under every file format (XML by default) +- VoteCountingExecuter : Component allowing the management of the different vote counting algorithms. + +Vote counting component offers two different interfaces/services corresponding to the components presented above : + +- ServicePollExport : result and poll export service, using a standard format. +- ServiceVoteCounting : vote counting management service. + + +Maven modules +------------- + +3 Modules are created to manage those different components : + +- UI : Presentation layer (Tapestry framework) +- Business : persistence and business layer (Use of ToPIA-Persistence framework) +- VoteCounting : separated vote counting module + + + Property changes on: trunk/src/site/rst/architecture.rst ___________________________________________________________________ Added: svn:keywords + Date Author Revision Rev Id Added: svn:mergeinfo + Copied: trunk/src/site/rst/business.rst (from rev 2767, trunk/src/site/rst/developper/business/business.rst) =================================================================== --- trunk/src/site/rst/business.rst (rev 0) +++ trunk/src/site/rst/business.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,75 @@ +Business +======== + +:Author: +:Revision: $Revision$ +:Date: $Date$ + +DTO +--- + +The dto package does the communication between the web client and the persitence +part of the application. +For maintanability and uncoupling needs, the client does not manipulate directly +database objects and so use a simplified representation of the entities located +in the persistence layer. + +The dtos class model put in place in Pollen-Business module is the following : + +.. image:: schemas/business/DC_businessDTOs.png + :alt: Pollen-Business modules's DTO + + +This modeled is based on the poll notion, by this way, in only a distant call +(in a distributed architecture) all the poll information is restored. +Moreover, to ake into account a further evolution to a fully distributed +architecture, each dto does the serializable interface allowing to serialize the +dto object created for a distant transfer (this aspect is not shown on the diagram). + +Services +-------- + +In our service oriented architecture, the services are a facade giving access to +the persitence management to the client, it shows a certain number of operations, +hidding their implementation to the client. To do so, it is based on the DTO +pattern to exchange info with it. + +This model presents the service exposed for poll management. + +.. image:: schemas/business/DC_ServicePoll.png + :alt: Poll component services + +It is necessary to transform the dtos exchanged with the client into an entity +to persist the data and perform the opposite operation to give data to the client. +Those operations are taken into account specifically for the poll by the +DataPollConverter class. + +Moreover, we can note that managing polls, the service can make calls to other +services such as choices management service, comments management services, ... + +Create a poll +~~~~~~~~~~~~~ + +The sequence diagram shows the message exchanges between Pollen-Business +component classes during a service creation. + +.. image:: schemas/business/DS_Conception_CreerSondage.jpg + :alt: Sequence diagram : poll creation + + +Persistence +----------- + +Using ToPIA-Persistence API, we have to manage a global context laoding the JDBC +connection to the dabase properties and creating sub-contexts used for +transactions to the database. + +The global persistence context for the application is managed under a singleton +form, its classes manipulating those concepts are the following : + +.. image:: schemas/business/DC_DBUtil.png + :alt: Utils classes for the database connection + +The contextUtil class also allows to load the referential tables (vote counting +type, poll type, list type, choice type) that do not have their own UI for the moment +from the pollenconfig.properties file. \ No newline at end of file Property changes on: trunk/src/site/rst/business.rst ___________________________________________________________________ Added: svn:keywords + Date Author Revision Rev Id Added: svn:mergeinfo + Added: trunk/src/site/rst/developer.rst =================================================================== --- trunk/src/site/rst/developer.rst (rev 0) +++ trunk/src/site/rst/developer.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,22 @@ +Developer documentation +======================= + +You will find here a lot of developer documentation on Pollen and its different +modules. + +All the diagram and schemes are in French but as all the explanations are +translated in english you should not have problems to understand how it works. + +You can find documentation on : + +- `analysis of what was existing and the needs`_ +- architecture_ +- `votecounting module`_ +- `business module`_ +- `UI module`_ + +.. _analysis of what was existing and the needs: analysis.html +.. _architecture: architecture.html +.. _votecounting module: votecounting.html +.. _business module: business.html +.. _UI module: ui.html \ No newline at end of file Added: trunk/src/site/rst/index.rst =================================================================== --- trunk/src/site/rst/index.rst (rev 0) +++ trunk/src/site/rst/index.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,24 @@ +Welcome to Pollen website +========================= + +What is Pollen ? +---------------- + +Pollen is web based poll/vote application. It is aimed to small entities that +want to have a way to manage votes without giving their data to someone. + +Why is Pollen cool ? +-------------------- + +- Pollen features textual, date or image vote. +- You can vote anonymously. +- You can import voters lists from CSV files or LDAP. +- You can import/export votes/polls. +- You can install Pollen on your own server to keep the control on your data + (confidential vote for exemple). +- Pollen is build as services so you can integrate it wherever you want. +- Pollen is Libre so you can modify it, improve it, adapt it to your needs. +- Pollen as a nice looking. + +.. image:: pollen.png + :alt: Pollen screenshot Copied: trunk/src/site/rst/install.rst (from rev 2767, trunk/src/site/rst/user/install.rst) =================================================================== --- trunk/src/site/rst/install.rst (rev 0) +++ trunk/src/site/rst/install.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,52 @@ +Installation guide +================== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision$ +:Date: $Date$ + +To install the application, you just need to deploy the war archive in a web +contener like Tomcat. + +By default, a H2 database is created in the */tmp* directory. To modify this +behaviour, you only need to create the */etc/pollen.properties* file and to fill +it with the following properties :: + + # database configuration + hibernate.show_sql=false + hibernate.dialect=org.hibernate.dialect.H2Dialect + hibernate.connection.username=username + hibernate.connection.password=password + hibernate.connection.driver_class=org.h2.Driver + hibernate.connection.url=jdbc:h2:file://tmp/pollen/pollen + + # transfered pictures directory + upImgDir=/tmp/pollen/uploadedImages + + # maximal size of transfered pictures (in bytes) + upload.filesize-max=1048576 + upload.requestsize-max=10485760 + + # automatic email sending configuration + email_host=smtp.free.fr + email_port=25 + email_from=bot@pollen.org + + # syndication flux directory (Atom) + feedDir=/tmp/pollen/feeds + + # site adresse (used for reminder emails) + siteUrl=http://www.site.org/pollen/ + +For example, for a PostgreSQL database, we will have :: + + hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect + hibernate.connection.driver_class=org.postgresql.Driver + hibernate.default_schema=public + +It may be necessary to redeploy the application after having modificated this +file; + +A user with administration rights is automatically added (login "admin", +password "pollen"). For safety measures, it is really important to delete this +user (or modify its password) after having created another administrator account. Property changes on: trunk/src/site/rst/install.rst ___________________________________________________________________ Added: svn:keywords + "Author Date Id Rev Revision" Added: svn:mergeinfo + Copied: trunk/src/site/rst/tutoriel.rst (from rev 2767, trunk/src/site/rst/user/tutoriel.rst) =================================================================== --- trunk/src/site/rst/tutoriel.rst (rev 0) +++ trunk/src/site/rst/tutoriel.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,101 @@ +Tutorial +======== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision$ +:Date: $Date$ + +We will see through an example, how to create a poll with Pollen. The three +necessary steps are: + +- creation +- vote +- results visualisation + +Creation +-------- + +The first step is filling in global information about the poll and its creator. +All the fields are not mandatory. The poll type is defined by one of the +following terms : + +- **Free** : everybody can participate +- **Restricted** : only a list of voters can participate +- **Group** : several lists of voters can participate + +The vote counting type corresponds to one of the following : + +- **Normal** : select 1 or n winners amongst the choices +- **Percentage** : attribute a percentage to each choice +- **Condorcet** : Rank the choices by preference order (cf `Condorcet`_ ) + +.. _Condorcet: http://en.wikipedia.org/wiki/Condorcet_method + +.. image:: tutoriel/Creation-step1.png + :alt: Creation : step 1 + +The second step allows to specify options for the poll. The questionmark shaped +icons display help on the topic : + +- Anonymous poll : Voting persons and their votes are anonymous +- Allow anonymous vote : Voting persons can be anonymous +- Continuous results : Poll results are displayed continuously during the vote +- Public results : Poll results are available for everybody +- Allow adding choices : You can add choices to the poll +- Limit the number of choices for each vote : The user can select a limited number of choices +- Receive notifications emails : An email is sent each n votes to prevent the creator +- Send reminder emails : An email is sent to remind persons who have not yet voted N hours before poll end + +.. image:: tutoriel/Creation-step2.png + :alt: Creation : step 2 + +The third step is specific to group or restricted polls. If you are logged in you +can use predefined list to fill in the groups (the selected poll is shown in grey). +Otherwise you have to fill in their names and emails. It is also possible to give +a weight to a group or a voter. + +.. image:: tutoriel/Creation-step3.png + :alt: Creation : step 3 + +The fourth step is aimed to fill in the choices for the poll. The choices can be +text, date or pictures. It is possible to fill in a description per choices. + +.. image:: tutoriel/Creation-step4.png + :alt: Creation : step 4 + +Once the poll is created, a page indicate two links. The first one is the link +to the vote page (to send to the voter, this is automatic if their email was filled in). +The second one have to stay private, this is the poll modification link (allows +to end the poll also). + +.. image:: tutoriel/Creation-step5.png + :alt: Creation : links + +Vote +---- + +The vote page contains a reminder of the poll informations and a representation +of each voter's vote. The poll creator and the voter concerned can modify a vote. +If the poll is public, it is possible to see the results. In addition to that, +the poll's news can be followed by Atom syndication and it is possible to post +comments. + +.. image:: tutoriel/Vote.png + :alt: Vote + +Results +------- + +The results page allows to see a poll's results on a diagram. It shows the poll +informations and gives the winner. Several displays are available : pie, 3D pie +and ring pie. + +.. image:: tutoriel/Results.png + :alt: Resultats + +Other functionalities +--------------------- + +A logged in other can access more functionalities. He can see a list of polls he +created or participated in. He can create voters lists manually or from LDAP url. +An administrator can manage all the polls and users. Property changes on: trunk/src/site/rst/tutoriel.rst ___________________________________________________________________ Added: svn:keywords + "Author Date Id Rev Revision" Added: svn:mergeinfo + Copied: trunk/src/site/rst/ui.rst (from rev 2767, trunk/src/site/rst/developper/ui/ui.rst) =================================================================== --- trunk/src/site/rst/ui.rst (rev 0) +++ trunk/src/site/rst/ui.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,279 @@ +UI +== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision$ +:Date: $Date$ + +The application web interface has been created with Tapestry framework from +Apache foundation. Tapestry is a development framework for Web J2EE applications +wich architecture is based on components. + +It features numerous pros : + +- few configuration thanks to annotations. +- strongly object oriented : abstraction of session, request, cookie,... notions. +- full separation of business and presentation java code. +- advanced feedback : error messages pertinent and complete. +- loading on the fly : no need to compile again the code. +- easy component development . + +Data +---- + +The data package contains the UI architecture's model elements. + +UIO +~~~ + +The UIO (User Interface Objects) are similar to business DTO for UI. The UIO +attributes are private and have getters and setters, because Tapestry framework +manipulates the objects via those UIO. +The UI manipulate directly the DTOs but there are two UIOs that inherits from +ChoiceDTO : DataChoiceUIO and ImageChoiceUIO. They are useful when creating date +or picture poll choices. + +.. image:: schemas/ui/DC_UIOs.png + :alt: UIOS class diagram + +Link +~~~~ + +The link class represents an hypertext link : it has a name attribute, which is +the string representing the link, and an address attribute, which is the address +where the link points. + +EvenOdd +~~~~~~~ + +The EvenOdd classallows to attribute a class to a table lines or to a list elements, +to display them changing their color on line over two. + +PollStep +~~~~~~~~ + +The PollStep enumeration represents the steps of the poll creation/modification +form. + +Components +---------- + +Border +~~~~~~ + +The Border component is a component present on all the pages of the application : +it is the menu, the address bar and the footer. +It takes in parameter a Link Array, that will create the address bar, and a page +type (Creation, Index, Vote or VoteCounting) that determines the logo and the page +colors. + +.. image:: schemas/ui/topIndex.png + :alt: Border Index + +.. image:: schemas/ui/topCreation.png + :alt: Border Creation + +.. image:: schemas/ui/topCount.png + :alt: Border VoteCounting + +.. image:: schemas/ui/topVote.png + :alt: Border Vote + +LoginComponent +~~~~~~~~~~~~~~ + +This component is a connexion form that is displayed when the user tries to reach +a page where he needs to be logged in. + +DateTimeField +~~~~~~~~~~~~~ + +This component is a form field type allowing to select a date and an hour. + +.. image:: schemas/ui/dateTimeField.png + :alt: DateTimeField component + +FeedBack +~~~~~~~~ + +The FeedBack component manages the user messages displaying (messages for the user). +Those messages have a look and feel different depending on their meaning. For exemple +an error message will be more aggressive than an information message. This component +allows to display those types of message when rendering the page. It is possible +to display several messages of different type at the same time. They will be +displayed only once and then deleted. This component behave quite the smae way than +the Tapestry Error component that displays form validation error messages. + +.. image:: schemas/ui/feedBack.png + :alt: FeedBack component + +To customise the messages appearance, you need to define the classes *fb-error* +and *fb-info* in the CSS file. In the template, you need to place the component +tag :: + + <t:feedback t:id="feedback"/> + +In the classes, after the component declaration, it is possible to add messages :: + + @Component(id = "feedback") private FeedBack feedback; + + feedback.addInfo("info message"); + feedback.addError("error message"); + +Image +~~~~~ + +The image component goal is to display a picture dynamically, such as picture +uploaded on the server from a form. On the face of it we do not know the +picture's file name, so we cannot use asset to display it the follpowing way:: + + <img src="${asset:context:img}/image.png" /> + +The component creates an image HTML element associating it with a +ImageStreamResponse flux :: + + <t:image src="/img/image.png" /> + +Chart +~~~~~ + +The Chart component displays a pie chart. To do so, it uses the JFreeChart +library and convert the results ina picture easily displayable on a web page :: + + <t:chart width="210" height="190" values="choice" title="title" type="1"/> + +The *values* parameter correspond to a list of strings representing the labels +and their respective values (example : {"val1", "20", "val2", "10"}). The *type* +parameter is the diagram representation type (1:PIE, 2:PIE3D, 3:RING). + +.. image:: schemas/ui/chart.png + :alt: Chart component + +Pages +----- + +The pages are at the same time view and controller for the architecture. However +each page is represented by 3 files : + +- a template .tml (the view) that contains HTML code and Tapestry components +- a Java class (the controler) that initialise the data and components, that +defines the actions associated to the components and uses the BusinessServices +class from the services package to call the business services. +- a .properties files (or several for internationalization) that contains the +messages displayed on the page. + +Poll creation +~~~~~~~~~~~~~ + +The poll creation page allows to create a poll by filling in : + +- the poll title (mandatory) +- the poll description +- begin and end dates +- the creator name (mandatory) +- the poll anonymity +- the possibility for users to add choices +- the email sending to the creator incase of votes or comments. +- the type of choices (text, image or date) +- the different choices and their description + +When choices are pictures, the files are sent to the server but the directory +they are saved in needs to be configured. +If the poll creation is successful on the database, a confirmation page is +displayed and gives the user two links : one to vote (that he can send to other +voters), and the other for poll modification or ending. + +Poll modification +~~~~~~~~~~~~~~~~~ + +The fields that can be modificated are the following ones : + +- the title +- the poll description +- the creator's name +- the dates (with conditions) +- email sending +- choice adding +- choice description + +This page take as argument the poll ToPIA id hashed with md5 concatened with the +hashed poll creator ToPIA id. +This is also on this page that he will be able to close the poll to count the votes. + +Vote +~~~~ + +This page allows a user to vote to a poll. He has to fill in his name and vote +for one or more choices. +This page allows to add comments to the poll. +This page take into argument the poll ToPIA id hashed with md5. + +The votes on pictures needs to allow pictures uploading on the server. The +Tapestry Upload component allows to do that easily by placing it into a form and by saving +the file sublited (UploadedFile) in a servers'directory. Moreover it is possible +to limit the size of the files in the AppModule class (*contibuteApplicationDefaults()* method):: + + configuration.add(UploadSymbols.FILESIZE_MAX, "500000"); + configuration.add(UploadSymbols.REQUESTSIZE_MAX, "5000000"); + +The thumbnail corresponding to the image is created once and for all when it is +submitted so that the server is not on his kees because he change the image +dimensions each time someone displays the page (image a page with 10 2Mb images). +But it is not so easy to display thos images after beacause of Tapestry's behavior. +An Image component have then be created to fulfill this need. + +Results +~~~~~~~ + +A result page use the Chart component to display a poll's results. They are +restored via the ServiceResult service. + +User's polls +~~~~~~~~~~~~ + +If the user who creates a poll is registered and logged in, the created poll is +linked to his account in the database. So he will be able to consult the list of +the polls he created. This can allow him to get back the different URLs if he +lost them. + +Voters lists +~~~~~~~~~~~~~~~~~ + +The voters lists can be created by hand filling in the info for each voter, but +it is also possible to import a list of voters from a CSV file. The reading of the +CSV files is done by the use of the JAVA OpenCSV library that allows to define a +mapping strategy to convert directly the fields into objects. + +The logged in user can manage voters lists. When he will create a restricted poll, +he will be able to use its predefined voters lists instead of manually type in +the voters list for the poll. + +Services +-------- + +Tapestry is delivered with numerous services that are a part of the framework, +but it is also possible to define its own services. In the AppModule class, that +contains the small amount of configuration needed by Tapestry to work, we can link +its services by completing the *bind(ServiceBinder binder)* method:: + + binder.bind(ServicePoll.class, ServicePollImpl.class); + +Once Tapestry knows the interface and the service implementation, we can inject +it in the application's pages and use it as usual:: + + @Inject + private ServicePoll servicePoll; + +Configuration +~~~~~~~~~~~~~ + +In addition to the business services defined in the pollen-business module, a +pollen-ui service allows to reach the application configuration (mail server, +pictures directory,...). This service reads the configuration in a *properties* +file when its instanciated. + +BackgroundWorker +~~~~~~~~~~~~~~~~ + +Another service, BackgroundWorker, allows to do tasks in background. +This service is useful to send emails at fixed time interval. Property changes on: trunk/src/site/rst/ui.rst ___________________________________________________________________ Added: svn:keywords + Date Author Revision Rev Id Added: svn:mergeinfo + Added: trunk/src/site/rst/user.rst =================================================================== --- trunk/src/site/rst/user.rst (rev 0) +++ trunk/src/site/rst/user.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,10 @@ +User documentation +================== + +You will find here all the documentation available for Pollen. + +You can find an `installation guide`_ and a `tutorial`_ to understand how to create +a poll, vote and count votes at the end. + +.. _installation guide:install.html +.. _tutorial:tutoriel.html \ No newline at end of file Copied: trunk/src/site/rst/votecounting.rst (from rev 2767, trunk/src/site/rst/developper/votecounting/votecounting.rst) =================================================================== --- trunk/src/site/rst/votecounting.rst (rev 0) +++ trunk/src/site/rst/votecounting.rst 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,190 @@ +VoteCounting +============ + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision$ +:Date: $Date$ + +This part describe the VoteCounting module implementation. + +There are 2 interfaces : + +- ServiceVoteCounting : Vote couting management service. +- ServicePollExport : Poll and results export management service. + +ServiceVoteCounting +------------------- + +DTOVoteCounting +~~~~~~~~~~~~~~~ + +The VoteCounting DTOs (Data Transfer Object) allow to use correctly the interfaces +exposed by the VoteCounting module. + +There are two important root DTOs : + +- PollDTO : Correspond to a poll and all the important elements for vote counting. +- VoteCountingResultDTO : The vote counting result organized following the poll's +choices. + +PollExportDTO have been added for exports. It conatines a PollDTO and several +VoteCountingResultDTOs. + +Two enumerations are also available and allows the types normalization : + +- PollType : Poll type (Group, Free, Restricted, ...) +- VoteCountingType : Vote counting type (Condorcet, Percentage, ...) + +Please note that the VoteCountingType is used as reference for a poll vote counting. + +.. image:: schemas/votecounting/DC_VoteCountingDTOs.png + :alt: VoteCounting module DTO + +**PollDTO** + +It is coumpounded of PollChoiceDTO (the poll's choices) and Comment DTO +(the poll's comments). + +It is compounded of VotingGroupDTO. This one correspond to group of voters in +case of a group typed poll. In case of another type, there will be one and only +one VotingGroupDTO with null values (weight and idGroup). + +Each VotingGroupDTO is compounded of VotingPersonDTO corresponding to voters +linked to the poll (people who have already voted). The votingID will be +"anonymous" in case of an anonymous poll. + +Each VotingPersonDTO is compounded of VoteToChoiceDTOs corresponding to the +voter's votes (for each choice a value). + +It is not necessary to know all the choices in advance at the poll's level. The +vote counting will manage the organization of the results regarding the choices. + +**VoteCountingResultDTO** + +The results are shared out according to the poll's choices. A ResultDTOV is +compouded of ChoiceDTOVs corresponding to those choices. + +So for a poll we have : + +- the global result (VoteCountingResultDTO.choiceResult) +- the result per choice (ChoiceDTO.value) + +Operations +~~~~~~~~~~ + +- executeVoteCounting(poll : PollDTO) : VoteCountingResultDTO + +This operation allows to execute a poll's vote counting. + +- executeGroupCounting(poll : PollDTO) : VoteCountingResultDTO + +This operation allows the execution of a poll's vote counting functions of groups. + + +Implementation +~~~~~~~~~~~~~~ + +The Strategy Pattern is used to manage the vote counting. A Context class allows +to define which strategy type to use. +The strategy is defined at the beginning with PollDTO's typeVoteCounting attribute. + +Here the strategies are represented by the Method interface that will be implemented +by : + +- CondorcetMethod : Vote counting using the Condorcet criterion. +- StandardMethod : Normal vote counting. +- PercentageMethod : Vote counting using choices balancing. + +Each method implements the "executeMethod(choices)" operation that will be called +in the Context class by the "exectute()" method. +So the context needs to know all the choices and the votes by choice and by group. + +When calling for ServiceVoteCounting, a new context will be created and the +PollDTO will be scanned to create the choices, groups and votes needed for the +vote counting. + +.. image:: schemas/votecounting/DC_ServiceVoteCountingImpl.png + :alt: VoteCounting service implementation diagram. + +Execution +~~~~~~~~~ + +- Call to executeVoteCounting +- Context creation depending on PollDTO.typeVoteCounting +- Scan PollChoiceDTOs : Add the choices to the context. +- Scan VotingGroupDTOs : For each group -> VoteCounting.routeGroup(VotingGroupDTO) +(with group adding to the context Context.addGroup(idGroup, weight)) +- Scan VotingPersonDTO : For each people -> VoteCounting.routePerson(VotingPersonDTO) +- Scan Vote : For each choice -> add it to the context via +Context.getChoice(idChoice).getGroup(VoteCounting.currentIdGroup).addVote(value, weight) +- Execute the vote counting method -> Context.execute() +- Create the VoteCountingResultDTO that contains all the choices with their results. + +.. image:: schemas/votecounting/Seq-executeVoteCounting.png + :alt: Sequence diagram of a normal vote counting (without algorithm details) + +Condorcet vote counting +~~~~~~~~~~~~~~~~~~~~~~~ + +With a classical vote counting, the winner is the one that has the biggest number +of voices. With the Condorcet method that is not necessarily the case. The winner +is the one that, compared to each other candidate, is always prefered. +In certain situations, such a winner does not exist, this is what we call the +Condorcet paradox (A>B>C>A). The algorithm chosen in Pollen consit in chosing +the candidate that won more duels. In case of deuce a vote needs to be done +between the leading group. + +A condorcet vote sequence is the following : + +1. The voters sort the candidates by preference order +2. For each vote, we compare the condidtaes rankings by pairs and we count the +number of wins of each candidate +3. The winner is the one that have the greatest number of victories. + +In Pollen, the implementation of Condorcet vote has in addition the notion of +voters groups. In cas of vote counting by groups, the algorithm is applied for +each groups, and then applied a second time between the results of each group. +When the voters vote in a poll, they can make two choices equals. It is not +necessary to sort all the choices, those which are not ranked will be all last. + +ServicePollExport +----------------- + +Operations +~~~~~~~~~~ + +- executeExport(export : PollExportDTO) : String + +This is the main operation that allows the poll export, the object given in +parameter contains the poll object and a list of the results to export. Those +results are obtained by the different vote counting methods. This methods +returns the name of the exported file. + +- executeImport(path : String) : PollExportDTO + +This operation imports the poll and its results from the file which path is +given in parameter, so it builds the PollExportDTO return by this method. + + +Export implementation +~~~~~~~~~~~~~~~~~~~~~ + +An easy implementation have been made for this part. Itturns out that the Visitor +pattern use is significant for this module implementation as it works the same +way that the Visitor pattern, but to do so, we need to add methods to the DTO +classes that violates their semantics, so we proceeded as shown in the following +diagram. + +.. image:: schemas/votecounting/DC_ServiceExportImpl.png + :alt: PollExport service implementation diagram. + + +Export result +~~~~~~~~~~~~~ + +To conceive Pollen's poll export module, we needed to specify the wanted result. +To do so we have done an UML modelisation to extract the tree architecture of our +export. Have a look to the following class diagram : + +.. image:: schemas/votecounting/DC_ServiceExportXML.png + :alt: Class diagram of a poll and its reults export Property changes on: trunk/src/site/rst/votecounting.rst ___________________________________________________________________ Added: svn:keywords + Date Author Revision Rev Id Added: svn:mergeinfo + Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-04 15:19:14 UTC (rev 2769) +++ trunk/src/site/site.xml 2009-09-04 15:22:49 UTC (rev 2770) @@ -20,9 +20,9 @@ </bannerRight> <poweredBy> - <logo href="http://maven.apache.org" name="Maven" img="http://jrst.labs.libre-entreprise.org/jrst/images/logos/maven-feather.png"/> - <logo href="http://jrst.labs.libre-entreprise.org" name="JRst" img="http://jrst.labs.libre-entreprise.org/jrst/images/jrst-logo.png"/> - <logo href="http://docutils.sourceforge.net/rst.html" name="ReStructuredText" img="http://jrst.labs.libre-entreprise.org/jrst/images/restructuredtext-logo.png"/> + <logo href="http://maven.apache.org" name="Maven" img="http://maven-site.nuiton.org/jrst/images/logos/maven-feather.png"/> + <logo href="http://jrst.labs.libre-entreprise.org" name="JRst" img="http://maven-site.nuiton.org/jrst/images/jrst-logo.png"/> + <logo href="http://docutils.sourceforge.net/rst.html" name="ReStructuredText" img="http://maven-site.nuiton.org/jrst/images/restructuredtext-logo.png"/> </poweredBy> <body> @@ -30,22 +30,40 @@ <breadcrumbs> <item name="${project.name}" href="${project.url}" /> </breadcrumbs> - - <menu name="Utilisateur"> - <item name="Installation" href="user/install.html"/> - <item name="Tutoriel" href="user/tutoriel.html"/> + + <links> + <item name="Libre-Entreprise" href="http://www.libre-entreprise.org/" /> + <item name="[fr" href="fr/index.html" /> + <item name="en]" href="index.html" /> + </links> + + + <menu name ="Documentation"> + <item name="User" href="user.html"> + <item name="Install" href="install.html"/> + <item name="Tutorial" href="tutoriel.html"/> + </item> + + <item name="Developer" href="developer.html"> + <item name="Analysis" href="analyse.html"/> + <item name="Architecture" href="architecture.html"/> + <item name="Conception"> + <item name="Business" href="business.html"/> + <item name="VoteCounting" href="votecounting.html"/> + <item name="UI" href="ui.html"/> + </item> + </item> </menu> + - <menu name="Développeur"> - <item name="Analyse" href="developper/analyse.html"/> - <item name="Architecture" href="developper/architecture.html"/> - <item name="Conception"> - <item name="Business" href="developper/business/business.html"/> - <item name="VoteCounting" href="developper/votecounting/votecounting.html"/> - <item name="UI" href="developper/ui/ui.html"/> - </item> + <menu name ="Download"> + <item name="Download" href="http://www.chorem.org/projects/list_files/pollen"/> </menu> + <menu name="Demo"> + <item name="Demo" href="http://pollen.chorem.org/"/> + </menu> + <menu ref="parent"/> <!-- <menu ref="modules"/> --> <menu ref="reports"/> Added: trunk/src/site/site_fr.xml =================================================================== --- trunk/src/site/site_fr.xml (rev 0) +++ trunk/src/site/site_fr.xml 2009-09-04 15:22:49 UTC (rev 2770) @@ -0,0 +1,72 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project name="${project.name}"> + + <publishDate format="dd/MM/yyyy"/> + + <skin> + <groupId>org.nuiton</groupId> + <artifactId>maven-nuiton-skin</artifactId> + <version>1.0.0</version> + </skin> + + <bannerLeft> + <name>${project.name}</name> + <href>index.html</href> + </bannerLeft> + + <bannerRight> + <src>http://www.codelutin.com/images/lutinorange-codelutin.png</src> + <href>http://www.codelutin.com</href> + </bannerRight> + + <poweredBy> + <logo href="http://maven.apache.org" name="Maven" img="http://maven-site.nuiton.org/jrst/images/logos/maven-feather.png"/> + <logo href="http://jrst.labs.libre-entreprise.org" name="JRst" img="http://maven-site.nuiton.org/jrst/images/jrst-logo.png"/> + <logo href="http://docutils.sourceforge.net/rst.html" name="ReStructuredText" img="http://maven-site.nuiton.org/jrst/images/restructuredtext-logo.png"/> + </poweredBy> + + <body> + + <breadcrumbs> + <item name="${project.name}" href="${project.url}" /> + </breadcrumbs> + + <links> + <item name="Libre-Entreprise" href="http://www.libre-entreprise.org/" /> + <item name="[fr" href="index.html" /> + <item name="en]" href="../index.html" /> + </links> + + <menu name ="Documentation"> + <item name="Utilisateur" href="user.html"> + <item name="Installation" href="install.html"/> + <item name="Tutoriel" href="tutoriel.html"/> + </item> + + <item name="Développeur" href="developer.html"> + <item name="Analyse" href="analyse.html"/> + <item name="Architecture" href="architecture.html"/> + <item name="Conception"> + <item name="Business" href="business.html"/> + <item name="VoteCounting" href="votecounting.html"/> + <item name="UI" href="ui.html"/> + </item> + </item> + </menu> + + <menu name ="Téléchargement"> + <item name="Téléchargement" href="http://www.chorem.org/projects/list_files/pollen"/> + </menu> + + <menu name="Demo"> + <item name="Demo" href="http://pollen.chorem.org/"/> + </menu> + + <menu ref="parent"/> + <!-- <menu ref="modules"/> --> + <menu ref="reports"/> + + </body> + +</project> +