Author: glorieux Date: 2009-11-24 15:25:54 +0100 (Tue, 24 Nov 2009) New Revision: 2802 Added: trunk/src/site/en/ trunk/src/site/en/resources/ trunk/src/site/en/resources/pollen.png trunk/src/site/en/resources/schemas/ trunk/src/site/en/resources/schemas/CreerSondage.jpg trunk/src/site/en/resources/schemas/CreerSondage2.jpg trunk/src/site/en/resources/schemas/DC_Pollen.png trunk/src/site/en/resources/schemas/DC_PreventRules.png trunk/src/site/en/resources/schemas/DET_PollState.png trunk/src/site/en/resources/schemas/Depouiller.jpg trunk/src/site/en/resources/schemas/Depouiller_1a.jpg trunk/src/site/en/resources/schemas/UC_Gestiondesvotes.png trunk/src/site/en/resources/schemas/Voter.jpg trunk/src/site/en/resources/schemas/business/ trunk/src/site/en/resources/schemas/business/DC_BusinessDTOs.png trunk/src/site/en/resources/schemas/business/DC_DBUtil.png trunk/src/site/en/resources/schemas/business/DC_ServicePoll.png trunk/src/site/en/resources/schemas/business/DC_ServiceResults.png trunk/src/site/en/resources/schemas/business/DC_ServiceUser.png trunk/src/site/en/resources/schemas/business/DC_ServiceVote.png trunk/src/site/en/resources/schemas/business/DS_Conception_CreerSondage.jpg trunk/src/site/en/resources/schemas/composants.png trunk/src/site/en/resources/schemas/packages.png trunk/src/site/en/resources/schemas/pollen_logo.jpg trunk/src/site/en/resources/schemas/schema-architecture.png trunk/src/site/en/resources/schemas/ui/ trunk/src/site/en/resources/schemas/ui/DC_UIOs.png trunk/src/site/en/resources/schemas/ui/chart.png trunk/src/site/en/resources/schemas/ui/dateTimeField.png trunk/src/site/en/resources/schemas/ui/feedBack.png trunk/src/site/en/resources/schemas/ui/topCount.png trunk/src/site/en/resources/schemas/ui/topCreation.png trunk/src/site/en/resources/schemas/ui/topIndex.png trunk/src/site/en/resources/schemas/ui/topVote.png trunk/src/site/en/resources/schemas/votecounting/ trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExport.png trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExportImpl.png trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExportXML.png trunk/src/site/en/resources/schemas/votecounting/DC_ServiceVoteCounting.png trunk/src/site/en/resources/schemas/votecounting/DC_ServiceVoteCountingImpl.png trunk/src/site/en/resources/schemas/votecounting/DC_VoteCountingDTOs.png trunk/src/site/en/resources/schemas/votecounting/Seq-executeVoteCounting.png trunk/src/site/en/resources/tutoriel/ trunk/src/site/en/resources/tutoriel/Capture-1.png trunk/src/site/en/resources/tutoriel/Capture-2.png trunk/src/site/en/resources/tutoriel/Capture-3.png trunk/src/site/en/resources/tutoriel/Capture-4.png trunk/src/site/en/resources/tutoriel/Capture-5.png trunk/src/site/en/resources/tutoriel/Capture-6.png trunk/src/site/en/resources/tutoriel/Capture.png trunk/src/site/en/resources/tutoriel/Creation-links.png trunk/src/site/en/resources/tutoriel/Creation-step1.png trunk/src/site/en/resources/tutoriel/Creation-step2.png trunk/src/site/en/resources/tutoriel/Creation-step3.png trunk/src/site/en/resources/tutoriel/Creation-step4.png trunk/src/site/en/resources/tutoriel/Results.png trunk/src/site/en/resources/tutoriel/Vote.png trunk/src/site/en/rst/ trunk/src/site/en/rst/analyse.rst trunk/src/site/en/rst/architecture.rst trunk/src/site/en/rst/business.rst trunk/src/site/en/rst/developer.rst trunk/src/site/en/rst/index.rst trunk/src/site/en/rst/install.rst trunk/src/site/en/rst/tutoriel.rst trunk/src/site/en/rst/ui.rst trunk/src/site/en/rst/user.rst trunk/src/site/en/rst/votecounting.rst Log: add en site directory. Added: trunk/src/site/en/resources/pollen.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/pollen.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/CreerSondage.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/CreerSondage.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/CreerSondage2.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/CreerSondage2.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/DC_Pollen.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/DC_Pollen.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/DC_PreventRules.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/DC_PreventRules.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/DET_PollState.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/DET_PollState.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/Depouiller.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/Depouiller.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/Depouiller_1a.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/Depouiller_1a.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/UC_Gestiondesvotes.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/UC_Gestiondesvotes.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/Voter.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/Voter.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DC_BusinessDTOs.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DC_BusinessDTOs.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DC_DBUtil.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DC_DBUtil.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DC_ServicePoll.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DC_ServicePoll.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DC_ServiceResults.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DC_ServiceResults.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DC_ServiceUser.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DC_ServiceUser.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DC_ServiceVote.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DC_ServiceVote.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/business/DS_Conception_CreerSondage.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/business/DS_Conception_CreerSondage.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/composants.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/composants.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/packages.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/packages.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/pollen_logo.jpg =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/pollen_logo.jpg ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/schema-architecture.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/schema-architecture.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/DC_UIOs.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/DC_UIOs.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/chart.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/chart.png ___________________________________________________________________ Added: svn:executable + * Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/dateTimeField.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/dateTimeField.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/feedBack.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/feedBack.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/topCount.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/topCount.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/topCreation.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/topCreation.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/topIndex.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/topIndex.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/ui/topVote.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/ui/topVote.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExport.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExport.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExportImpl.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExportImpl.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExportXML.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceExportXML.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceVoteCounting.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceVoteCounting.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceVoteCountingImpl.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/DC_ServiceVoteCountingImpl.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/DC_VoteCountingDTOs.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/DC_VoteCountingDTOs.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/schemas/votecounting/Seq-executeVoteCounting.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/schemas/votecounting/Seq-executeVoteCounting.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture-1.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture-1.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture-2.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture-2.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture-3.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture-3.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture-4.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture-4.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture-5.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture-5.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture-6.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture-6.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Capture.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Capture.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Creation-links.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Creation-links.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Creation-step1.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Creation-step1.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Creation-step2.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Creation-step2.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Creation-step3.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Creation-step3.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Creation-step4.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Creation-step4.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Results.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Results.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/resources/tutoriel/Vote.png =================================================================== (Binary files differ) Property changes on: trunk/src/site/en/resources/tutoriel/Vote.png ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: trunk/src/site/en/rst/analyse.rst =================================================================== --- trunk/src/site/en/rst/analyse.rst (rev 0) +++ trunk/src/site/en/rst/analyse.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,388 @@ +Analysis +======== + +:Author: Erwan NEMA <nemawan@hotmail.com> +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2773 $ +:Date: $Date: 2009-09-09 12:05:20 +0200 (mer., 09 sept. 2009) $ + +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 person (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 voter 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 anonymity. + +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 connection 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 address. + 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 restricted 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 authorised 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 message 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 algorithm. +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 persistence 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 Added: trunk/src/site/en/rst/architecture.rst =================================================================== --- trunk/src/site/en/rst/architecture.rst (rev 0) +++ trunk/src/site/en/rst/architecture.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,75 @@ +Pollen architecture +=================== + +:Author: Florian DESBOIS <florian.desbois@gmail.com> +:Revision: $Revision: 2773 $ +:Date: $Date: 2009-09-09 12:05:20 +0200 (mer., 09 sept. 2009) $ + +.. 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 available 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 + + + Added: trunk/src/site/en/rst/business.rst =================================================================== --- trunk/src/site/en/rst/business.rst (rev 0) +++ trunk/src/site/en/rst/business.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,75 @@ +Business +======== + +:Author: +:Revision: $Revision: 2773 $ +:Date: $Date: 2009-09-09 12:05:20 +0200 (mer., 09 sept. 2009) $ + +DTO +--- + +The dto package does the communication between the web client and the persistence +part of the application. +For maintainability 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 persistence 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 loading the JDBC +connection to the database 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 Added: trunk/src/site/en/rst/developer.rst =================================================================== --- trunk/src/site/en/rst/developer.rst (rev 0) +++ trunk/src/site/en/rst/developer.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -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/en/rst/index.rst =================================================================== --- trunk/src/site/en/rst/index.rst (rev 0) +++ trunk/src/site/en/rst/index.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -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 example). +- 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 Added: trunk/src/site/en/rst/install.rst =================================================================== --- trunk/src/site/en/rst/install.rst (rev 0) +++ trunk/src/site/en/rst/install.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,74 @@ +Installation guide +================== + +.. Author: Nolwenn Rannou <rannou@codelutin.com> +.. Revision: $Revision: 2779 $ +.. Date: $Date: 2009-10-12 14:29:43 +0200 (lun., 12 oct. 2009) $ + +.. contents:: + +Web container +------------- + +To install the application, you just need to deploy the war archive in a web +container 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 modified 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. + +Embedded container +------------------ + +Since pollen-1.1.1, the war bundle embed a servlet container based on winstone. +To run it, just launch with following command : + +:: + + java -jar pollen-x.x.x.war + + +Then open a browser to address : http://localhost:8080/. + +You can also use command line option to configure launch : http://winstone.sourceforge.net/#commandLine + +.. _Tomcat: http://tomcat.apache.org/ \ No newline at end of file Added: trunk/src/site/en/rst/tutoriel.rst =================================================================== --- trunk/src/site/en/rst/tutoriel.rst (rev 0) +++ trunk/src/site/en/rst/tutoriel.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,101 @@ +Tutorial +======== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2773 $ +:Date: $Date: 2009-09-09 12:05:20 +0200 (mer., 09 sept. 2009) $ + +We will see through an example, how to create a poll with Pollen. The three +necessary steps are: + +- creation +- vote +- results visualization + +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. Added: trunk/src/site/en/rst/ui.rst =================================================================== --- trunk/src/site/en/rst/ui.rst (rev 0) +++ trunk/src/site/en/rst/ui.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,279 @@ +UI +== + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2773 $ +:Date: $Date: 2009-09-09 12:05:20 +0200 (mer., 09 sept. 2009) $ + +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 submitted (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 those images after because 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. Added: trunk/src/site/en/rst/user.rst =================================================================== --- trunk/src/site/en/rst/user.rst (rev 0) +++ trunk/src/site/en/rst/user.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -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 Added: trunk/src/site/en/rst/votecounting.rst =================================================================== --- trunk/src/site/en/rst/votecounting.rst (rev 0) +++ trunk/src/site/en/rst/votecounting.rst 2009-11-24 14:25:54 UTC (rev 2802) @@ -0,0 +1,190 @@ +VoteCounting +============ + +:Author: Nolwenn Rannou <rannou@codelutin.com> +:Revision: $Revision: 2773 $ +:Date: $Date: 2009-09-09 12:05:20 +0200 (mer., 09 sept. 2009) $ + +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 "execute()" 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 results export