Rebag Ware

From REBAG

Contents 1 Introduction 1.1 What is Rebag Ware? 2 System requirements 2.1 Functional Requirements 2.2 Architectural Requirements 3 System analysis 3.1 System Model 3.2 Principal Entities 4 System planning 4.1 Voice activities 4.2 Policy life 4.3 Corporations' History 5 Implementation 5.1 The Architecture 5.1.1 Model-View-Controller (MVC) 5.1.2 Rebag-Ware's architecture 5.2 Rebag-Ware Database 5.2.1 Rebag-Ware's Database ER Diagrams 5.3 Java Source 5.3.1 Main Classes 5.3.2 Servlets 5.3.3 Managers and main functions 5.3.4 Documentation 5.4 Rebag-Ware User Interface 5.5 How to Set Up The Development Environment 5.5.1 Install the development environment 5.5.2 Import the project from the CVS repository in Eclipse 5.5.3 Add the log4j.jar library to your Apache Tomcat Application Server 5.5.4 Configure the database 5.5.5 Configure the logger 5.5.6 Rebuild and run 5.6 Common Tasks 5.7 Open Issues 6 Resources 7 References

Introduction

What is Rebag Ware?

Rebag-Ware is an Internet-based Reputation System (IBRS), freely available under the 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 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:

Policy management:
All the activities involved to and with policies; these include, policy definition, policy authorization, policy application and policy evaluation.

Actors management:

All the activities needed to support Rebag Ware users. Rebag user nature spreads from citizens, to organizations and to public/private authorities (politicians, firms).

Participatory design:

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...)

Voice activities:

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.

Budgeting:

Rebag Ware should provide financial informations about policies. The desired budget reports are:
1. aggregated financial report: it should be...
2. 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...

Publishing:

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:
1. Total cost of policies grouped by province
The retrieved informations are shown in a friendly way through a GUI.

Architectural Requirements

Modularity
Rebag Ware should have a modular structure in order:
1. to be flexible
2. to be extended easily

System analysis

System Model

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

It manages actors. Administrators can add them, modify their characterstics, visualize them.

• constituency manager

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.

• Policies

• Policies manager

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).

• Policy application manager

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.

• Policy authorization manager

It manages the process that leads to the formal authorization of a project or program, eventually allowing for forms of participatory design.

• Voice manager

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.

• Publisher

The publisher publishes on the Web summary information on Actors and Policies. Moreover It may also provides geographical representation of the data and statistical information and analysis.

• Budgeting

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.

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:

• Quality of performance
• Cost performance
• Timeliness of Performance
• Business relation

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:

• 0 Unsatisfactory
• 1 Poor
• 2 Fair
• 3 Good
• 4 Excellent
• 5 Outstanding

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.

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.

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:

• Database: the Rebag-Ware database has been implemented using MySQL (Server Version 5.0.19)
• Business logic: Java (Version 1.5)
• The view: JSP + JSTL

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 Designing Enterprise Applications with the J2EE Platform, Second Edition):

• 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;
• 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;
• 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.

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

Figure 4: The Model-View-Controller Architecture (from 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.

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.

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.

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 ormunicipality. 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).

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 ormunicipality.

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).

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).

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

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:

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:

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.

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.

public static void findAdministrationPolicy(Administration administration): finds administration's project and for each project the involved firms and their partecipation

public static void findFirmPolicy(Firm firm): finds firm's project and for each project the involved administrations and their partecipation

public static void findPolicyResponsibleAdministration(Policy policy, int firmId): retrieves the responsible administrations (and their partecipation) of a policy in relation to a firm

public static void findPolicyResponsibleFirm(Policy policy, int admId): retrieves the responsible firm (and their partecipation) of a policy in relation to an administration

• AssessmentManager: it manages the aggregation assessment data processes for the first phase of Rebag-Ware Reputatin Computation:

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

public static void assessmentAdmRoleWithinPolicy(int admId, int policyId): computes the assessment to the administration's role in policy execution

• private static void weightedAggregation(int sectorId, int targetId, int policyId): aggregates administration's or firm's assessments
• private static void overallAggregation(int sectorId, int targetId, int policyId): computes the overall administration's or firm's role policy outcome

public static void assessmentFirmRoleWithinPolicy(int firmId, int policyId): computes the assessment to the firm's role in policy execution

• private static void weightedAggregation(int sectorId, int targetId, int policyId): aggregates administration's or firm's assessments
• private static void overallAggregation(int sectorId, int targetId, int policyId): computes the overall administration's or firm's role policy outcome

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

public static void constituencyPolicy(int actorId, ActorProfile actorprofile): retrieves the Policies to which a citizen has associated

public static ConstituencyPolicy[] recommendedpolicyToAssociate(Constituency c): retrieves a list of recommended policies for a citizen

• LoginManager: it is responsible for user authentication and registration

public static Actor checkCredential(String user, String passwd): checks username and password of an Actor attempting to log in Rebag-Ware

public static boolean checkUsername(String username): checks if the chosen username is valid in a new Actor registration

• PublisherManager: it is responsible to retrieve some responsabilities information

public static VoiceActivity[] getVoiceActivity(String queryFilter): retrieves voice activities from database according to the query filter.

public static void printAdmDptPolicyList(Administration[] admL, JspWriter out, boolean getResponsability): prints the list of responsible Administrations of a Policy and their relative weights

public static void printFirmPolicyList(Firm[] firmL, JspWriter out, boolean getResponsability): prints the list of responsible Firms of a Policy and their relative weights

• ReputationManager: it manages the aggregation assessment data processes for the second phase of Rebag-Ware Reputatin Computation:

public static void computeReputation(Administration adm, Firm firm, int method): computes the reputation of a Firm or an Administration
• 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:
  • public static void assessmentPolicyOutcome(int policyId): computes the assessment to a policy outcome by constituency (common for administrations and firms, belongs to AssessmentManager)
  • 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)
  • 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)
  • 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)
  • 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)
• private static void computeAdmReputation(Administration adm): computes Administration's Reputation and uses:
  • private static void admReputationPerYear(Administration adm): computes the Administration's Reputation per year
  • private static void admOverallReputation(Administration adm): computes the overall Administration's Reputation as weighted average of Year Reputation
• private static void computeFirmReputation(Firm firm): computes Firm's Reputation
  • private static void firmReputationPerYear(Firm firm): computes the Firm's Reputation per year
  • private static void firmOverallReputation(Firm firm): computes the overall Firm's Reputation as weighted average of Year Reputation

• VoiceManager: it is responsible of Rebag-Ware voice related tasks:

public static int addVoiceActivity(VoiceActivity voice): adds an expressed voice to Rebag-Ware database

public static void closeVoiceOverPolicy(int polId, int actorId): closes the voice when an Actor voiced over all the possible dimensions

public static void finalizedVoiceActivity(int voiceId): closes an Administration or Firm's voice after a rebuttal

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

Documentation

To have a look into Rebag-Ware classes you can download the browsable Rebag-Ware Java implementation. (doc.zip)

Rebag-Ware User Interface

Figure 14 shows Rebag-Ware UI navigation map.

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.

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:

• administration
  • addadministration.jsp: to add an administration or a department
  • addpolicy.jsp: to add a new project
  • addprojecttypology.jsp: to edit policy's categories
  • addwp2policy.jsp: to add work packages to a policy (followes addpolicy.jsp)
  • administrationhome.jsp: the home page of the administration
  • administrationvoices.jsp: to show the expressed and received administration's assessments (either about a specific policy or about all its policies)
  • admmenu.jsp: the menu for the administrations (included in administrationhome.jsp)
  • constituency2typology.jsp: to change policy categories' voice dimensions and sub-constituencies
  • edit.jsp: to edit a project or an administration or a department
  • summarybox.jsp: the top left box of the administration's home page (included in administrationhome.jsp), it shows summary informations
  • timediscount4policy.jsp: to change time discount values
• constituency
  • constituencyhome.jsp: the home page of citizens
  • constituencymenu.jsp: the menu for the home page of citizens
  • constituencypolassociation.jsp: to join the sub-constituencies of policies
  • constituencyvoices.jsp: to show the expressed assessments over associated policies
  • editassociation.jsp: to leave the sub-constituency of a policy
  • recommendedpolbox.jsp: to show a set of system recommended policies (included in constituencyhome.jsp)
  • summarybox.jsp: the top left box of citizen's home page, it shows summary informations (included in constituencyhome.jsp)
• firm
  • firmhome.jsp: the home page of a firm
  • firmmenu.jsp: the menu for the firm's home page
  • firmvoices.jsp: to show the expressed and received firm's assessments (either about a specific policy or about all its policies)
  • sunmmarybox.jsp: the top left box of the firm's home page (included in firmhome.jsp), it shows summary informations
• admdetail.jsp: to show details about an administration or department
• firmdetail.jsp: to show details about a firm
• footer.jsp: the footer of Rebag-Ware (included in every page)
• header.jsp: the header of Rebag-Ware (included in every page)
• loggedout.jsp
• login.jsp
• policycommentt.jsp: to show comments about a policy
• policydetail.jsp: to show the details of a policy
• register.jsp: to register a new citizen or firm
• report.jsp: to report disaggregated assessments for administrations and firms
• searchresult.jsp: to search and to show results
• voice.jsp: to vote policies
• voiceactions.jsp: to rebut a voice, to change an expressed voice (by a citizen)

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 [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.

1. Create a new project, selecting "other->CVS->Checkout projects from CVS". You should be prompted with the checkout from CVS dialog.
2. 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 write to us to get username)
   • In the Password field, type the password ((Please 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
3. 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.
4. Click Finish.
5. 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 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 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:

Rebag-Ware is planned to be a multi-language application. The application exploits Java internationalization facilites (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 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.

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 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:

  <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>

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).

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

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).

• Deploying the application:

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 (Web Application Installation)

• Understanding the control flow of the application

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.

   <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>

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 contact us.

Resources

• "Towards Rebag Ware", some slides (.ppt).
• Some MOCK-UPs (pdf) related to voice activities in the application.
• Rebag-Ware database: Rebag-Ware DB
• Rebag-Ware software: Rebag-Ware 1.0

References

• Designing Enterprise Applications with the J2EE Platform, Second Edition. [1], last accessed 21st February 2006.
• NACE classification. [2].
• NACE classifciation 2nd site. [3]