View source

== Introduction ==
=== What is Rebag Ware? ===
Rebag-Ware is an Internet-based Reputation System (IBRS), freely available under the [http://www.gnu.org/copyleft/gpl.html GPL license], 
to show the practical feasibility of Reputation-based governance. Rebag-Ware is the deliverable of Work Package n. 3
of the project (see the [[The Project Management Plan]]). Its realization is outsourced to [http://www.elearninglab.it E-Learning Lab].

== System requirements ==
This section covers the functional and architectural requirements of Rebag Ware. Rebag Ware functional requirements reflect Rebag issues, listed in [[Reputation-Based Governance: a Primer]].

=== Functional Requirements ===
From a first analysis of requirements, Rebag Ware supported tasks are:

<ul>
'''Policy management''':
<ul>All the activities involved to and with policies; these include, policy definition, [[policy authorization]], [[policy application]] and [[policy evaluation]].
</ul>

'''Actors management''':
<ul>All the activities needed to support Rebag Ware users. Rebag user nature spreads from citizens, to organizations and to public/private authorities (politicians, firms).  
</ul>

'''[[Participatory design]]''':
<ul>In case of a call for proposals, Rebag should keep track of received proposals and they should be somehow accessible by referencing the Policy to which they are bound (to be defined better...)
</ul>

'''[[voice|Voice activities]]''':
<ul>As Rebag Ware aims to be an Internet based Reputation System, it should offer the functionality to enable users, in general Rebag [[Actors]], to express comments about [[Policies]] and about [[Actors]]. Voice activities, adequately structured, may allow for forms of [[participatory design]] and [[participatory budgeting]].
</ul>

'''Budgeting''':
<ul>Rebag Ware should provide financial informations about policies. The desired budget reports are:
#aggregated financial report: it should be...
#policy specific report: it should provide specific informations about a policy and its relative "backers", the quantity of money and resources involved related to a timespan etc...
</ul>

'''[[publisher|Publishing]]''':
<ul>A [[publisher]] shows reports about data collected in the system. Thus it should offer a number of reports about Actors and Policies with some degree of customisation and some facilities to group together related entities. The publisher acts as information filter with respect to the profile of the requesters (citizens, politicians, administrators etc.). Moreover it should provide:

*  [[Policy georeferentiation]]: Rebag Ware should offer a view of existing policies based on maps, where georeferenced data can be shown

*  [[Statistical information]]: Rebag Ware should provide statistics data grouped by a number of criteria. A provisional list may be: 
#Total cost of policies grouped by province

The retrieved informations are shown in a friendly way through a GUI.
</ul>
</ul>

=== Architectural Requirements ===

<ul>
'''Modularity'''
<ul>
Rebag Ware should have a modular structure in order:
#to be flexible
#to be extended easily
</ul>


</ul>



== System analysis ==

=== System Model ===

[[Image:RebagWareModello.jpg]]

'''Figure 1''': Rebag-Ware conceptual model

The figure shows the conceptual model of Rebag-Ware after the first brainstorming session. Rectangles represent entities of the system and rumbles represent managers.
Entities are connected to manager (modules) whenever they may be in relation. For example relations between policy and actors and between actors through voicing say that actors can voice both actors and policies.

===Principal Entities===

* [[Actors]]

* [[Actors manager]] 
<ul> It manages [[actors]]. Administrators can add them, modify their characterstics,
visualize them.
</ul>

* [[constituency manager]]
<ul> Used to determine the constituencies of a policy, i.e. actors that are influenced by a policy. It's important to notice that the constituency manager deals with dynamic creation of constituencies groups and solves overlapping group generation. 
</ul>

* [[Policies]]

* [[Policies manager]]
<ul> It records and manages [[policies]] and their relations. 
If [[participatory design]] of policies is allowed, it also records alternative policy plans, i.e., policy proposals
that need to be evaluated and, eventually, selected. These can be "alternative project plan" or "alternative 
program plan" according to their nature. Alternative policy plans also may be related with one another (and
with policies that have already been selected).
</ul>

* [[Policy application]] manager

<ul> The policy application manager is defined in general terms. A [[policy application]] manager refers to the details of a
given policy domain (Ex., public works in Italy). There is one policy application manager for each application 
field. In this stage of development, Rebag Ware will include only the Policy Application Manager for public works.

</ul>

* [[Policy authorization]] manager

<ul> It manages the process that leads to the formal [[policy authorization|authorization]] of a project or program,
eventually allowing for forms of [[participatory design]].
</ul>

* [[Voice]] manager

<ul> [[Voice]] activities can be addressed to policies or programs and to actors. Voice activities, adequately structured, may allow for forms of [[participatory design]] and [[participatory budgeting]].
</ul> 

* [[Publisher]]

<ul> The [[publisher]] publishes on the Web summary information on [[Actors]] and [[Policies]]. Moreover It may also provides [[Policy georeferentiation|geographical representation]] of the data and [[statistical information]] and analysis.
</ul>

* [[Budgeting]]

<ul> It manages the [[budgeting]] of the project or program and, in the aggregate,
the general administration's budget (imagining that all expenses are either projects
or programs). In the latter case, it allows for the management of the yearly budget law.
</ul>

== System planning ==
Rebag-Ware is a Java Web application that implements an Internet based Reputation system (IBRS). The system records public works, administration and contracting firms. One features of Rebag-Ware is its policy and administration evaluation through voice activities. Voice activities allow the public (citizens) to assess completed public works, administrators to express opinions on the contracting firms, and firms to assess administrators. 

=== Voice activities ===

Voice activities consist in numerical rating and supporting narratives (both at aggregated and/or at deliverable level). 
Administrations and firms are expected to voice over different dimension than the ones for citizens. In fact they should be able to 
voice each other over management aspects, some of them may be:
<ul>
<li>''Quality of performance''</li>
<li>''Cost performance'' </li>
<li>''Timeliness of Performance'' </li>
<li>''Business relation''</li>
</ul>
As far as citizens' voice activities are concerned, citizens are expected to voice the output of policies (as an example a bridge, a hospital). Thus voice dimension will depend on policy classification.
Evaluation on this four ''dimensions'' are in terms of numeric scores. Rebag-Ware provides the following rate scale for each dimension:
<ul>
<li>0 Unsatisfactory</li>
<li>1 Poor</li>
<li>2 Fair</li>
<li>3 Good</li>
<li>4 Excellent</li>
<li>5 Outstanding</li>
</ul>
We can represent a voice activity by a tuple such as:

''Voice = < voice_source, voice_target, dimension, rate, [comments] >''

where:

* ''voice_source'' can be Administrations, Firms, and Citizens who belong to policies' constituencies;
* ''voice_target'' can be Policies, or the role of Adminitrations and Firms in policy execution; 
* the ''dimension'' depends on the voice_source scope over the voice activity;
* the rate value is included in the range [0,5];
* comments are optional;

Expressed voice activities are used to compute aggregated values in the process of reputation computation.

=== Policy ''life'' ===

Policies evaluation and "life" status can be represented by ''states'';  ''state transitions'' trigger states changes. The state-based model will be used in the application to facilitate the management of the policies.

[[Image:PoliciesStates.jpg]]

'''Figure 2''': Rebag Ware state-based policy model

=== Corporations' History ===

Corporations are subject to changes. They can terminate, be renamed, be merged, and split. 
The figure shows changes we are interested in.

[[Image:RebagCorporationHistory.jpg]]

'''Figure 3''': Relevant changes in Rebag Corporations

From the corporation's reputation point of view such changes are in fact crucial to be able to compute the reputation of a corporation in a given period of time. Such changes involve Administrations, Firms, Political Parties and actor Roles and the system have to save them.

== Implementation ==

Rebag-Ware is a Java Web application designed according to MVC pattern. 
The technologies involved in Rebag Ware development are:
<ul>
  <li>Database: the Rebag-Ware database has been implemented using MySQL (Server Version 5.0.19)</li>
  <li>Business logic: Java (Version 1.5)</li>
  <li>The view: JSP + JSTL</li>
</ul>
Rebag-Ware users interact through a Web-based interface. The interface is XHTML W3C compliant and fully design through CSS. The application can be hosted by any machine which runs java, apache tomcat and mysql server. 


===The Architecture===
Rebag's architecture aims at reflecting the Model-View-Controller architectural design pattern.

==== Model-View-Controller (MVC) ====
 
The Model View Controller is a recommended architectural design pattern for interactive applications. Each layer handles specific tasks and has specific responsibilities to the other areas. The MVC architecture separates the application's data model, user interface, and control logic into three distinct components so that modifications to one component can be made with minimal impact to the others. 

Roughly speaking, constructing an application using an MVC architecture involves defining three classes of modules (from [[#J2EE|Designing Enterprise Applications with the J2EE Platform, Second Edition]]):
<ul>
<li>'''Model''': the model represents data and business rules (logic) that govern access to and updates of this data. It serves as a ''software approximation'' to a real-world process, thus it will contain Rebag entities and Rebag business rules;</li>
<li>'''View''': the view renders the contents of a model. It accesses data through the model and specifies how that data should be presented. It is the view's responsibility to maintain consistency in its presentation when the model changes;</li>
<li>'''Controller''': the controller dispatches requests and control flow; it translates interactions with the view into actions to be performed by the model. In a stand-alone GUI client, user interactions could be button clicks or menu selections, whereas in a Web application, they appear as GET and POST HTTP requests. The actions performed by the model include activating business processes or changing the state of the model. Based on the user interactions and the outcome of the model actions, the controller responds by selecting an appropriate view.</li>
</ul>

The figure depicts the relationships between the model, view, and controller layers of an MVC application.

[[Image:ModelViewConrtrollerRebagArch.jpg]]

'''Figure 4''': The Model-View-Controller Architecture (from [[#J2EE|Designing Enterprise Applications with the J2EE Platform, Second Edition]])

Separating responsibilities among model, view, and controller objects reduces code duplication and makes applications easier to maintain. It also makes handling data easier, whether adding new data sources or changing data presentation, because business logic is kept separate from data. 
Thus the MVC design pattern provides a host of design benefits and therefore we can achieve modularity and flexibility in the Rebag Ware application.

==== Rebag-Ware's architecture ====
The figure shows Rebag-Ware's architecture according to the MVC pattern.

[[Image:RebagArchitecture.jpg]]

'''Figure 5''': Architecture of Rebag-Ware 1.0

Users such as Administrations, Firms and Citizens interact with the system through a Web-based interface. User requests are handled by the 
controller which dispatches them to the appropriate servlet according to Rebag-Ware execution flow. The controller accesses the Rebag-Ware model and interacts with Rebag-Ware database while processing the requests. When the request has been processed, a response is generated by the View and sent back to users.

=== Rebag-Ware Database ===

==== Rebag-Ware's Database ER Diagrams ====
The following ER diagrams represent Rebag-Ware's database for version 1.0. For presentation issues the diagram has been split in several subdiagrams, each of which highlights the main relations between the entities. 
 

[[Image:RebagWareER.jpg]]

'''Figure 6''': ER diagram representing main entities and relations in Rebag-Ware DB

Figure 6 represents the relations between the actors in the system (Administrations, Firms, Citizens) and Policies. An ''actor'' belongs 
either to an ''administration'', a ''firm'' or to a ''constituency'' of a ''policy''. 
Administrations are related to policies through ''administration2policy'' relations which models several administrative details such as 
costs, dates responsability and the administration's partecipation in policy's execution.
Firms are related to policies through ''firm2policy'' relations which models details such as costs, dates responsability and firm's 
partecipation in policy's execution.
Citizens associate to policies through ''constituencypolicyassociation'' relations, and become part of policies ''constituency'' and relative ''subconstituency''.

[[Image:RebagWareERPolicies.jpg]]

'''Figure 7''': ER diagram representing entities and relations for Rebag-Ware policies.

Figure 7 represents entity and relations for describing policies in Rebag-Ware. A ''policy'' is classified against some criteria such as 
''type'' (projects right now), ''application'' (public works right now), ''category'', and ''type of good''. Moreover policies belongs to 
a specific geografic area, ''policiesjurisdiction'' which can span from ''country'', to ''region'', ''province'' or''municipality''. 
A policy may have subprojects while definetely has one or deliverables that defines its workbreakdown structure according to the Project Management Plan perspective (''nested_in'').

[[Image:RebagWareERAdm.jpg]]

'''Figure 8''': ER diagram representing entities and relations for Rebag-Ware administrations involved in policies.

Figure 8 represents entity and relations for describing administrations in Rebag-Ware. An ''administration'' can be either 
an Administration or a Department (''administrationType'') which are gerarchically related.
Administrations jurisdiction ''administrationjurisdiction'' belongs to 
a specific geografic area, which can span from ''country'', to ''region'', ''province'' or''municipality''.

[[Image:RebagWareERFirm.jpg]]

'''Figure 9''': ER diagram representing entities and relations for Rebag-Ware firms involved in policies.

Figure 9 represents entity and relations for describing firms in Rebag-Ware. A ''firm'' belongs to one or more sectors (''firm2sector''). 
In the execution of policies a firm may have subcontractors (''subcontractingfirms'') and/or belong to a consortium (''firm2consortium'').


[[Image:RebagWareERVoice.jpg]]

'''Figure 10''': ER diagram representing entities and relations for actors's voice activities.

Figure 10 represents entity and relations for describing voice activities in Rebag-Ware. Rebag-Ware actors are involved in voice 
activities. Citizens can vote policies after they have associated to them (''constituencypolassociation''). Administration can 
voice firms to which they have been related in the execution of policies and vice-versa (''adm2firm2policy''). A ''voiceactivity'' is 
caracterized by source and target voice actors, the policy to which the voice is related, a voice dimension, a voice rate and optionally 
a comment. Voice dimension values depends on which sector the source actor belongs. According to it administrators, firm's officials and 
citizen can voice specific dimension. 
For example actors, such as administrators and firm's official may voice over different dimension (''voicedimension2actorsector'') compare to citizen who may be 
interested only in voicing aestethic quality of the policy rather than aspects of quality of management of it. Citizens' voice dimensions 
depends moreover on the classification of a policy. As an example voice dimensions over a public building are different from those specific for a road (please consider ''polclass2subconst2voicedim'' instead of ''polclassification2voicedimension'' table as shown).


[[Image:RebagWareERRep.jpg]]

'''Figure 11''': ER diagram representing entities and relations for administrations' and firms' reputation.

Figure 11 represents entity and relations involved in step-by-step process for the computation of administrations and firms (administrators 
develops their own reputation as they may change administrations over time, not represented in the diagram).
For understanding deeply how the reputation is computed, please refer to Rebag Documentation. Nevertheless it should already clear from 
the diagram that the reputation derives (''admperyearreputation'',''firmperyearreputation'') from an aggregation of an overall policy outcome (''overallpolicyoutcome'') and overall administrations' and firms' outcome of assessements of their role in the 
execution of a policy (''overalladmassessment'',''overallfirmassessment''). In the aggregation several weights (<=1) are used to create aggregate values. As an example weights such as 
administrations' and firm's policy weights, derived from their partecipation in policy execution are used to compute weighted averages of 
the values of the singular assessments (''voice activities'')

=== Java Source ===

==== Main Classes ====

[[Image:RebagWareUML.jpg]]

'''Figure 12: UML Rebag-Ware class diagram 

Fugure 12 represents the UML model implemented for Rebag-Ware. Java classes model the db entities defined in the previous section. For 
representability reasons classes' member and operators are not shown. The UML representation depicts main relations between Java classes.

==== Servlets ====
Several servlets handle the execution flow of Rebag-Ware. The implementation code can be found in the package '''rebagware.servlet''' 

*''LoginServlet'': responsible for actors' authentication and  actors' registration
*''ActorServlet'': responsible for administrations' and firms' requests, and some specific actions such as the search
*''ConstituencyServlet'': responsible for citizens' requests
*''PublisherServlet'': responsible for preparing the data an actor can see according to his or her profile
*''PolicyServlet'': responsible for policy's related task such as adding, editing or deleting a policy
*''VoiceServlet'': responsible for the voice process 

Servlets interact for the fullfillment of users' task. The next figure shows an example:

[[Image:RebagWareServletExample.jpg]]

'''Figure 13: Rebag-Ware Servlet interaction example

The task represented is the voice of a policy by a citizen. After the citizen has logged in the system successfully, (the check of his or her 
credentials are handled by the Login Servlet) his profile is built by the Constituency Servlet which retrieved his policies. 
The actor voice is dispatched to the Voice Servlet that after storing it in the database forwards a request to the Publisher which is 
responsible to deliver the voice information to the voice originating actor.

==== Managers and main functions ====
Several managers implement the business logic of the application. The implementation code of the managers can be found in package '''rebagware.manager'''. Here we provide an overview of the most important functions.

*''ActorManager'': it is responsible for collecting administration's and firm's data and retrieves policy responsabilities:
<ul>
'''public static Administration''' collectAdmData('''int''' admId): retrieves the data about an administration after its administrator has logged in the system. The data are policies of which the administration has been responsible, the related firms.
</ul>
<ul>
'''public static Firm''' collectFirmData('''int''' firmId): retrieves the data about a firm after its official has logged in the system. The data are policies of which the firm has been responsible, the related administrations.
</ul>
<ul>
'''public static void''' findAdministrationPolicy('''Administration''' administration): finds administration's project and for each project the involved firms and their partecipation
</ul>
<ul>
'''public static void''' findFirmPolicy('''Firm''' firm): finds firm's project and for each project the involved administrations and their partecipation
</ul>
<ul>
'''public static void''' findPolicyResponsibleAdministration('''Policy''' policy, '''int''' firmId): retrieves the responsible administrations (and their partecipation) of a policy in relation to a firm 
</ul>
<ul>
'''public static void''' findPolicyResponsibleFirm('''Policy''' policy, '''int''' admId): retrieves the responsible firm (and their partecipation) of a policy in relation to an administration
</ul>


*''AssessmentManager'': it manages the aggregation assessment data processes for the first phase of Rebag-Ware Reputatin Computation:
<ul>

'''public static void''' assessmentPolicyOutcome('''int''' policyId): computes the assessment to a policy outcome by constituency
<ul>
<li>
'''private static void''' medianAggregation('''int''' policyId): aggregates the median values of sub-Constituency voices per voice dimension
</li>
<li>
'''private static void''' weightedDimensionAggregation('''int''' policyId): aggregates the assessements of sub-Constituencies in assessment of Constituency
</li>
<li>
'''private static void''' overallAggregation('''int''' policyId): computes the overall policy outcome
</li>
</ul>

'''public static void''' assessmentAdmRoleWithinPolicy('''int''' admId, '''int''' policyId): computes the assessment to the administration's role in policy execution
<ul>
<li>
'''private static void''' weightedAggregation('''int''' sectorId, '''int''' targetId, '''int''' policyId): aggregates administration's or firm's assessments
</li>
<li>
'''private static void''' overallAggregation('''int''' sectorId, '''int''' targetId, '''int''' policyId): computes the overall administration's or firm's role policy outcome
</li>
</ul>

'''public static void''' assessmentFirmRoleWithinPolicy('''int''' firmId, '''int''' policyId): computes the assessment to the firm's role in policy execution
<ul>
<li>
'''private static void''' weightedAggregation('''int''' sectorId, '''int''' targetId, '''int''' policyId): aggregates administration's or firm's assessments
</li>
<li>
'''private static void''' overallAggregation('''int''' sectorId, '''int''' targetId, '''int''' policyId): computes the overall administration's or firm's role policy outcome
</li>
</ul>


</ul>

*''ConstituencyManager'': it is responsible for citizen's Rebag-Ware tasks such as Policy Association

<ul>
'''public static void''' constituencyPolicy('''int''' actorId, '''ActorProfile''' actorprofile): retrieves the Policies to which a citizen has associated
</ul>
<ul>
'''public static ConstituencyPolicy[]''' recommendedpolicyToAssociate('''Constituency''' c): retrieves a list of recommended policies for a citizen
</ul>


*''LoginManager'': it is responsible for user authentication and registration
<ul>
'''public static Actor'''  checkCredential('''String''' user, '''String''' passwd): checks username and password of an Actor attempting to log in Rebag-Ware
</ul>
<ul>
'''public static boolean''' checkUsername('''String''' username): checks if the chosen username is valid in a new Actor registration
</ul>


*''PublisherManager'': it is responsible to retrieve some responsabilities information
<ul>
'''public static VoiceActivity[]''' getVoiceActivity('''String''' queryFilter): retrieves voice activities from database according to the query filter. 
</ul>
<ul>
'''public static void''' printAdmDptPolicyList('''Administration[]''' admL, '''JspWriter''' out, '''boolean''' getResponsability): prints the list of responsible Administrations of a Policy and their relative weights 
</ul>
<ul>
'''public static void''' printFirmPolicyList('''Firm[]''' firmL, '''JspWriter''' out, '''boolean''' getResponsability): prints the list of responsible Firms of a Policy and their relative weights 
</ul>


*''ReputationManager'': it manages the aggregation assessment data processes for the second phase of Rebag-Ware Reputatin Computation:
<ul>
'''public static void''' computeReputation('''Administration''' adm, '''Firm''' firm, '''int''' method): computes the reputation of a Firm or an Administration
<ul>
<li>
'''private static void''' collectAndAggregateAssessment('''int''' sectorId, '''int''' targetId, '''Policy[]''' polList): collects and aggregates the administration's or firm's assessments with policy outcome and uses:
<ul>
<li>
'''public static void''' assessmentPolicyOutcome('''int''' policyId): computes the assessment to a policy outcome by constituency (common for administrations and firms, belongs to ''AssessmentManager'')
</li>
<li>
'''public static void''' assessmentAdmRoleWithinPolicy('''int''' admId, '''int''' policyId): computes the assessment to the administration's role in policy execution (related to administrations, belongs to ''AssessmentManager'')
</li>
<li>
'''public static void''' policyOutcomeAdmRoleAggregation('''int''' admId, '''int''' policyId): aggregates the outcome of the administration's role with the policy outcome (related to administrations, belongs to ''AssessmentManager'')
</li>
<li>
'''public static void''' assessmentFirmRoleWithinPolicy('''int''' firmId, '''int''' policyId): computes the assessment to the firm's role in policy execution (relate to firms, belongs to ''AssessmentManager'')
</li>
<li>
'''public static void''' policyOutcomeFirmRoleAggregation('''int''' firmId, '''int''' policyId): aggregates the outcome of the firm's role with the policy outcome (related to firms, belongs to ''AssessmentManager'')
</li>
</ul>
</li>

<li>
'''private static void''' computeAdmReputation('''Administration''' adm): computes Administration's Reputation and uses:
<ul>
<li>
'''private static void''' admReputationPerYear('''Administration''' adm): computes the Administration's Reputation per year
</li>
<li>
'''private static void''' admOverallReputation('''Administration''' adm): computes the overall Administration's Reputation as weighted average of Year Reputation
</li>
</ul>
</li>

<li>
'''private static void''' computeFirmReputation('''Firm''' firm): computes Firm's Reputation
<ul>
<li>
'''private static void''' firmReputationPerYear('''Firm''' firm): computes the Firm's Reputation per year
</li>
<li>
'''private static void''' firmOverallReputation('''Firm''' firm): computes the overall Firm's Reputation as weighted average of Year Reputation
</li>
</ul>
</li>
</ul>
</ul>


*''VoiceManager'': it is responsible of Rebag-Ware voice related tasks:
<ul>
'''public static int''' addVoiceActivity('''VoiceActivity''' voice): adds an expressed voice to Rebag-Ware database
</ul>
<ul>
'''public static void''' closeVoiceOverPolicy('''int''' polId, '''int''' actorId): closes the voice when an Actor voiced over all the possible dimensions
</ul>
<ul>
'''public static void''' finalizedVoiceActivity('''int''' voiceId): closes an Administration or Firm's voice after a rebuttal
</ul>
<ul>
'''public static''' int stillToVoice('''int''' polId,'''int''' actorId,'''int''' sectorId,'''Administration[]''' admToVoice, '''Firm[]''' firmToVoice): retrieves a positive Id if the policy can still be voiced
</ul>

==== Documentation  ====
To have a look into Rebag-Ware classes you can download the browsable Rebag-Ware Java implementation. [[Media:Doc.zip|(doc.zip)]]

=== Rebag-Ware User Interface === 
Figure 14 shows Rebag-Ware UI navigation map. 

[[Image:RebagWareSiteMap.jpg]]

'''Figure 14''': UI Navigation Map of Rebag-Ware 1.0 

After the log in page, the user is redirected to his or her home page depending on her profile. There are three home templates, one for each actors' sectors (Administration, Citizen and Firm). Everyone can browse to detail pages over administrations, firms and policies and voices. Administrations and firms can browse reports about their reputations (basically where they can see the disaggregated informations that lead to their reputations). Administrations can access several administrative pages to add/edit administrations, modify time discount values, policy categories' properties and voice dimensions. Citizens join (or leave) Sub-constituencies of Policies in an association page. Every actors vote policies in the voice page.


[[Image:RebagWareContent.jpg]]

'''Figure 15''': Rebag-Ware WebContent


The Web content for Rebag-Ware is located in the WebContent folder. The figure shows the content three. It can be noticed how common pages are separated by actor specific ones. The latters are contained in three sub-folders. In the following we explain what each page is planned for:
<ul>
<li>'''administration'''
<ul>
<li>
addadministration.jsp: to add an administration or a department
</li>
<li>
addpolicy.jsp: to add a new project
</li>
<li>
addprojecttypology.jsp: to edit policy's categories
</li>
<li>
addwp2policy.jsp: to add work packages to a policy (followes addpolicy.jsp)
</li>
<li>
administrationhome.jsp: the home page of the administration
</li>
<li>
administrationvoices.jsp: to show the expressed and received administration's assessments (either about a specific policy or about all its policies)
</li>
<li>
admmenu.jsp: the menu for the administrations (included in administrationhome.jsp)
</li>
<li>
constituency2typology.jsp: to change policy categories' voice dimensions and sub-constituencies
</li>
<li>
edit.jsp: to edit a project or an administration or a department
</li>
<li>
summarybox.jsp: the top left box of the administration's home page (included in administrationhome.jsp), it shows summary informations
</li>
<li>
timediscount4policy.jsp: to change time discount values
</li>
</ul>
</li>

<li>'''constituency'''
<ul>
<li>
constituencyhome.jsp: the home page of citizens
</li>
<li>
constituencymenu.jsp: the menu for the home page of citizens
</li>
<li>
constituencypolassociation.jsp: to join the sub-constituencies of policies
</li>
<li>
constituencyvoices.jsp: to show the expressed assessments over associated policies
</li>
<li>
editassociation.jsp: to leave the sub-constituency of a policy
</li>
<li>
recommendedpolbox.jsp: to show a set of system recommended policies (included in constituencyhome.jsp)
</li>
<li>
summarybox.jsp: the top left box of citizen's home page, it shows summary informations (included in constituencyhome.jsp)
</li>
</ul>
</li>

<li>'''firm'''
<ul>
<li>
firmhome.jsp: the home page of a firm
</li>
<li>
firmmenu.jsp: the menu for the firm's home page
</li>
<li>
firmvoices.jsp: to show the expressed and received firm's assessments (either about a specific policy or about all its policies)
</li>
<li>
sunmmarybox.jsp: the top left box of the firm's home page (included in firmhome.jsp), it shows summary informations
</li>
</ul>
<li>

<li>admdetail.jsp: to show details about an administration or department</li>
<li>firmdetail.jsp: to show details about a firm</li>
<li>footer.jsp: the footer of Rebag-Ware (included in every page)</li>
<li>header.jsp: the header of Rebag-Ware (included in every page)</li>
<li>loggedout.jsp</li>
<li>login.jsp</li>
<li>policycommentt.jsp: to show comments about a policy</li>
<li>policydetail.jsp: to show the details of a policy</li>
<li>register.jsp: to register a new citizen or firm</li>
<li>report.jsp: to report disaggregated assessments for administrations and firms </li>
<li>searchresult.jsp: to search and to show results</li>
<li>voice.jsp: to vote policies</li>
<li>voiceactions.jsp: to rebut a voice, to change an expressed voice (by a citizen)</li>

</ul>

=== How to Set Up The Development Environment ===
To set up properly the delevelopment environment please follow these guidelines.

==== Install the development environment ====
The environment used for the development of Rebag-Ware is Eclipse 3.2. You can start from 
[[http://ei.unibo.it/elab-update/index.php/Sviluppare_un_client_per_un_servizio_Web_con_Eclipse_SDK#Installare_Eclipse here]] to install 
it.

====Import the project from the CVS repository in Eclipse====

The project code sources are hosted in a cvs repository, and can be imported easily in Eclipse IDE to get start with.
It is supposed that you have already run step 1, thus that you already are familiar with Eclipse. 

#Create a new project, selecting "other->CVS->Checkout projects from CVS". You should be prompted with the checkout from CVS dialog.
# Enter the information required to identify and connect to the repository location: 
#* In the Host field, type the address of the host: ''ei.unibo.it''
#* In the Repository path field, type the path to the repository on the host:  ''/cvsroot/rebag'' 
#* In the User field, type the user name (Please [http://www.rebag.it/rebag/index.php/Contacts write to us] to get username)
#* In the Password field, type the password ((Please [http://www.rebag.it/rebag/index.php/Contacts write to us] to get password))
#* From the Connection Type list, select the authentication protocol of the CVS server.  There are three connection methods that come with the Eclipse CVS client: 
#**pserver - a CVS specific connection method. 
#**''extssh'' - an SSH 2.0 client included with Eclipse (the one for Rebag-Ware)
#**ext - the CVS ext connection method which uses an external tool such as SSH to connect to the repository. The tool used by ext is configured in the Team > CVS > EXT Connection Method preference page. 
#* Use default port
# Select Save Password if you want to save the password in the Eclipse keyring file so you do not have to enter the password again the next time you start Eclipse. The keyring file is stored on your local drive and does not use strong encryption so you should not enable this option for sensitive passwords. 
# Click Finish.
# Follow the importation wizard, select the module ''RebagWare'' and this will lead you to check out the project's in a straightforward way.

====Add the log4j.jar library to your Apache Tomcat Application Server ====

Rebag-Ware's main activities are logged through a Logger, built exploiting log4j library. To let your installation compile you are 
supposed to add the log4j library which you can download from [http://logging.apache.org/log4j/docs/download.html here], to the 
libraries of your local Apache Tomcat Server. To accomplish this, extract the log4j.jar file from the dowloaded file and copy it into 
''common/lib'' folder of your Tomcat's folder installation.

====Configure the database ====
First you should have already installed on your system MySQL server technology. 
Then you can get Rebag-Ware's database creation script [http://www.rebag.it/rebag/index.php/Contacts writing to us]. The file is a raw copy of Rebag-Ware database, which means 
that you have to create your local copy on your MySQL server. For doing this you can just run the mysql command ''mysql'' according to this syntax:

  mysql -u ''user'' -p < rebagware.sql


where user should be your username to access the database server. After that you should have a copy of rebagware's database.
The default credentials to access the database are set to be rebagwaredb, rebagwaredb. You should create a user with these credential with 
access priviliges to rebagware database. As alternative you can specify another user but you should change the credentials (at the moment built-in) of the application. You find all informations regarding Rebag-Ware' db access in '''RebagDatabase.java''' class of '''rebagware.utils''' package.
Here you find the following properties and default values:
*dbLocation = the name of the database: "rebagwaredb";
*dbURL = "jdbc:mysql://";
*dbHost = the ip of the machine where MySQL server is running, "localhost";
*dbPort = the connection port to MySQL server "3306";
*driverName = "com.mysql.jdbc.Driver";
*userdb = "rebagwaredb";
*pwddb	= "rebagwaredb";
*option = "?autoReconnect=true", (apparently) needed to solve some server reconnection problems

==== Configure the logger ====

To Logger is configured though a property file named ''log4j.properties'', which you can find under the WEB-INF folder of your rebagware 
local installation.
To configure the access to this file from the application you should update the default file path to your local path to the file. Once 
again you have to modify a class of the application, named '''RebagWareLogger.java''' which is contained in the package '''rebagware.utils'''.

  PropertyConfigurator.configure("path_to_log4j.properties");

The logged output activities will be recorded in your ''${catalina.home}/logs/rebagware.log''. You can modify the Logger configuration changing 
log4j.properties file.

 (1) log4j.rootLogger=INFO, R 
 (2) log4j.appender.R=org.apache.log4j.RollingFileAppender 
 (3) ''log4j.appender.R.File=${catalina.home}/logs/rebagware.log''
 (4) log4j.appender.R.MaxFileSize=10MB
 (5) log4j.appender.R.MaxBackupIndex=10
 (6) log4j.appender.R.layout=org.apache.log4j.PatternLayout
 (7) log4j.appender.R.layout.ConversionPattern=%d [%t] %-5p %c %l - %m%n
 (8) log4j.logger.rebag=INFO, R

==== Rebuild and run ====

From the top menu select clean project (Rebag-Ware) and rebuild it. It will take a while depending on your machine. After this go on 
RebagWare project and choose Run As ->  Run on Server. The application should be deployed automatically and run.
Try it connecting to 

  http://localhost:your_tomcatport/rebagware


if something went wrong probably some library problems happened. Be sure that your local installation found all libraries. A reconfiguration 
of your build path can overcome some of these problems (reinstalling the server runtime for example).

=== Common Tasks ===

How to perform the most natural maintenance/enhancement operations. 

* Adding a language file:
<ul> Rebag-Ware is planned to be a multi-language application. The application exploits Java internationalization facilites ([http://java.sun.com/developer/technicalArticles/Intl/MultilingualJSP/ view]). According to it text translation is accessed by the application through dictionary files named in a conventional way. Files contain '''key = value''' pairs, where ''key'' is the identification label and ''value'' is the translation of a text. Files name are supposed to finish in '''_languageID.properties''' where ''languageID'' is the identification for a language (English = en, Italian = it, check [http://java.sun.com/developer/technicalArticles/Intl/MultilingualJSP/ here] for more codes). There a two types of files in the application. One for user interface and one for db terms translation.
The table shows files folder, name and use.
{| border=1
!File name
!File folder
!Dictionary
!
|----
|application_en.properties
|${RebagWareInstallationFolder}\WebContent\WEB-INF\classes\dictionaries\application
|contains the english dictionary used by the interface
|
|----
|application_it.properties
|${RebagWareInstallationFolder}\WebContent\WEB-INF\classes\dictionaries\application
|contains the italian dictionary used by the interface
|
|----
|miscellaneous_en.properties
|${RebagWareInstallationFolder}\WebContent\WEB-INF\classes\dictionaries\db
|contains the english dictionary for db terms translation
|
|----
|miscellaneous_it.properties
|${RebagWareInstallationFolder}\WebContent\WEB-INF\classes\dictionaries\db
|contains the italian dictionary for db terms translation
|
|}


The interface fully supports UTF-8 character representation, in order to represent so many languages as possible. If you plan to edit or add a dictionary file, dictionary files have to be edited or created in UTF-8 encoding. To add the new dictionary to the application, just copy and name a new file according to the language you're going to provide. Translate it and complete the enconding running the command [http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/native2ascii.html native2ascii] located in your Java JDK installation folder ''/bin'':  

   native2ascii -encoding utf-8 inputfile outputfile


Copy the output file into your Rebag-Ware folder under WEB-INF/classes/dictionaries/application or WEB-INF/classes/dictionaries/db.
Add to the login.jsp page the new language choice inserting a new list element to div head according to the syntax shown:

<pre>
  <div id="head">
      <h1>Reputation-based Governance of Public Works</h1>
        <ul id="nav">
         <%-- Offer locale choice to user --%>
	 <li>| <a href="login.jsp?locale=en-US">English</a></li>
	 <li>| <a href="login.jsp?locale=it-IT">Italiano</a></li>
         
         <li>| <a href="login.jsp?locale=xx-XX">NewLanguage</a></li>
        
       </ul>  
  </div>
</pre>
xx and XX are language codes.
Jsp pages refers to translated text of the dictionaries through JSTL formatting tag libraries. To access a key in the dictionary, first declare the dictionary (1),(3) and then refer to the key (2).

<pre>
 (1)  <fmt:bundle basename="dictionaries.application.application" >
 (2)	<fmt:message key="welcome" />
 (3)  </fmt:bundle>

</pre>

In this case the dictionary file is located under WEB-INF/classes/dictionaries/application and it is called application_xx.properties (where xx is the id for the language).

</ul>

* Deploying the application:
<ul>
Whenever you make any changes and you want to release a new version of Rebag-Ware you should deploy the new application to Tomcat. The easiest deployment method is to create the Web Application Archive  (.war) of Rebag-Ware from Eclipse (this can be done by exporting a project) and deploy it to Tomcat through the Tomcat Manager interface (http://localhost:your_tomcat_port). To deploy the Web application from command line please refer to Apache Tomcat Official Web Site ([http://tomcat.apache.org/tomcat-5.5-doc/deployer-howto.html#Installation Web Application Installation])
</ul>

* Understanding the control flow of the application
<ul>
As explained in the architecture section, the control flow of the application is handled by Rebag-Ware servlets. Specific requests are dispatched to the appropriate servlet according to the servlet-url mapping specified in Rebag-Ware descriptor (web.xml). According to these mapping only requests that match the mapping are forwarded to the right servlet. As an example ''login.do'' requests are forwarded to the ''LoginServlet''. Thus part of the control flow of the application can be understood by checking the web.xml of Rebag-Ware.
<pre>
   <servlet>
     <description>
	The LoginManager handles the login,logout and registration RebagWare procedures
     </description>
     <display-name>
	Login
     </display-name>
     <servlet-name>
	LoginManager
     </servlet-name>
     <servlet-class>
	rebagware.servlet.LoginServlet
     </servlet-class>
  </servlet>	
  <servlet-mapping>
     <servlet-name>LoginManager</servlet-name>
     <url-pattern>/login.do</url-pattern>
  </servlet-mapping>
  <servlet-mapping>
     <servlet-name>LoginManager</servlet-name>
     <url-pattern>/register.do</url-pattern>
  </servlet-mapping>
</pre> 
</ul>

=== Open Issues ===
In Rebag-Ware 1.0 release there are several open issues:
* life over time: corporations are subject to changes over time. ''historytype'', ''historysectors'' and ''historydata'' tables may be used to store such changes
* policy relations: at the moment only nested relations related to a project and its deliverables exist. However policies can be related to each other through '''connecting''' and  '''consequential''' relations. ''policyrelation'' and ''policyrelationtypes'' Tables can store such informations.
* project towards subcontracting firms and consortium: though the db supports the storing of such informations, the interface does not. Administrations can specify responsible firms of each project's work packages but they can't specify such relations. A more complex interface for this task should be available in the next version of Rebag-Ware
*political parties and administrations: administrations are usually related to political parties; administrators in fact may belong to specific political coalitions. The db and application should be extended in order to support the storing of such informations.

For suggestions, please [http://www.rebag.it/rebag/index.php/Contacts contact] us.

== Resources ==

* <span id="RebagOverview"></span> "Towards Rebag Ware", some [[Media:RebagOverview15-04-2006.ppt| slides]] (.ppt).
* Some [[Media:RebagMockUpsPartII.pdf|MOCK-UPs]] (pdf) related to voice activities in the application.
* Rebag-Ware database: [[Media:rebagwaredb.sql| Rebag-Ware DB]]
* Rebag-Ware software: [http://fire.ei.unibo.it:8080/rebagware Rebag-Ware 1.0]

== References ==
* <span id="J2EE"></span> Designing Enterprise Applications with the J2EE Platform, Second Edition. [http://java.sun.com/blueprints/guidelines/designing_enterprise_applications_2e/DEA2eTOC.html], last accessed 21st February 2006.
* NACE classification. [http://www.fifoost.org/database/nace/nace-en_2002AB.php].
* NACE classifciation 2nd site. [http://www.lisproject.org/les/nace.htm]