2014 Reengineering Project - JabRef

Context

JabRef is a desktop application for managing bibliographical data. The tool is used to handle BibTeX files, the standard format for writing documents in LaTeX. Academics, researchers, etc., use these tools to write scientific documents, technical manuals, etc. They maintain LaTeX files where they write their documents, and BibTeX files where they store the references and citations that are to be included in the main documents. Some like to maintain their full personal library in a single big BibTeX file, while in some cases it is more convenient to have separate smaller files with just the references for each single project or article (for sharing and collaboration purposes, for example). Managing a bibliographical database split across several bibTeX files and syncing them all could be time consuming and error prone: inconsistent data, missing entries, etc. We would like you to reengineer JabRef to support bibliographical databases composed of a "master" library file linked to any number of "child" files that will contain a subset of the master file. JabRef is written in Java and runs on the Java VM (version 1.6 or newer). It is open source and its source code can be download from the project’s web site.

Assignment

The current version of JabRef can only handle one BibTeX file at a time. As a reengineering team, you are asked to restructure the JabRef so it can accommodate the following improvement. The tool should support to manage a bibliographical library comprised of several BibTeX files: one master library file and any number of child files. This way, writers will be able to maintain a single master file containing their full personal library and one reference file for each one of their projects or articles. Some intended usage scenarios for this functionality are described below.

Scenario1 :

The user wants to start writing a new article. She selects some references from her current library.

The user requests JabRef to create from the existing BibTeX file - Main - a child version containing only the selected references. This second version - Child1 - can be stored in another directory. JabRef asks for a name and a path for Child1. JabRef opens up Child1.

The user introduces a NEW reference in Child1.

JabRef updates the main BibTeX file introducing the new reference from Child1.

Scenario 2:

From the Main BibTex the user creates a new BibTex file - Child2 - where a new subset of references are copied. This version - Child2 - has some common references with Child1.

One reference in Child2 is modified.

The system updates the reference in the Main BibTex file

The system propagates the reference update (if necessary) from main BibTeX to all its children (Child1 - Child2)

Some notes on the assignment:

The new feature has to introduce the concept of master and children files.

The tool has to keep multiple BibTex files synchronized, propagating changes from master to children and from children to master.

The tool will solve conflicts automatically by prioritizing the latest change over old data. For example, if the data in one entry in a child file does not match the data in the same entry in the master file, the entry in the master file will be replaced with the entry in the child file.

The information about the dependencies between the files should be stored in the BibTeX files: the master files will contain the list of their children, child files will contain the link to their master files.

Deadline: To be annunced Send Project Report in PDF by e-mail to Javier Perez, Alessandro Murgia and Serge Demeyer

Create an account on Bitbucket. An academic account will be provided if you sign up with your university email.

Load JabRef code into a new repository created specifically for this assignment. The team member acting as project leader should create the repository and add the rest of the team members as collaborators.

Use this repository to commit your changes regularly, as your personal backup and to collaborate with the members of your team.

Be sure to commit the final version of your reengineering process. The final commit will be considered for evaluation as part of your assignment submission.

Who is your group composed of? (it is encouraged to work out the assignment in a group (2-3 people))

Unless you chose to work on a project of your own choosing, then you will also need to motivate why this project would allow you to demonstrate your reengineering skills.

Lastly, you have to give access to your bitBucket repository to Javier Perez (javipeg in Bitbucket) and Alessandro Murgia (alessandro DOT murgia AT ua.ac.be).

Then, more specifically, we ask you to perform the following activities, and report about these in your project report:

[Design recovery]

Describe the current design of the implementation of the selected feature in JabRef. Clearly indicate how this design is located in the architecture of the project.

[Design]

Compose a generic design that describes how the new functionality / feature should be integrated and how the design handles the interaction with the rest of the system. It should be clear that, in a) the types of changes recorded can be easily extended; in b) the choice for a specific storage format is merely an implementation detail; in c) the types of repositories supported can be easily extended.

It will be necessary to redesign the test suite in such a way that it can cope with the new feature and design.

[Management]

Estimate the effort required for (i) refactoring towards the new requirements; and (ii) changing/extending the tests.

[Refactoring]

Refactor the current implementation of JabRef such that it can handle one of the new features.

Adjust/extend the tests of the project to preserve their effectiveness and coverage during and after refactoring.

You will be required to perform a number of techniques presented during the lab sessions. These are:

Analyse:

Duplicated Code Analysis

Metrics and visualization

Restructuring:

Testing

Refactoring

This project emphasizes the sound, systematic analysis of the presented problem, the associated solution space and the chosen solution(s). The software reengineering sessions are composed in such a way as to prepare you for such a project. We stimulate you to assess the benefits and drawbacks of the techniques presented in the lab sessions, and ask you to exploit the analysis techniques wisely. You are free to use alternative analysis techniques.

What concerns the refactoring-part, we emphasize the use of tests. Our minimum requirements are:

Determine the extent to which the current tests provide feedback on your future refactoring-steps. Quantify this.

Compose an argument discussing why the tests are (in)adequate for your chosen refactoring scenario, and adjust the tests in case this is required. Be efficient with regard to the time invested in testing.

Result

To show that you have passed the assignment, you will have to demonstrate the following:

You have made a selection of analysis techniques (e.g., duplicated code analysis, mining software repositories, metric and visualization as seen in the lab sessions, but others are allowed as well), and have applied these techniques in a sound, systematic manner. You have indicated clearly (using screenshots, results of the interpretation of the output of the techniques) how you have used the results of these analysis techniques.

You have performed the above 5 activities (decomposed into (i) Design Recovery; (ii) Design; (iii) Management; and (iv) Refactoring) and discussed them in your project report.

The restructurings you have applied are behavior preserving.

You can demonstrate the mapping between each of the classes from the original structure with the new structure.

The compilation process succeeds flawlessly.

The tests run without flaws, and demonstrate clearly that the new userinterface is implemented correctly.

The introduction of the new design clearly indicates the project is ready to be released in a language of choice. You are not supposed to carry out the refactoring process completely. Select and execute a set of refactorings that sufficently illustrate your proposed solution.

Report

Aspects that we typically like to see addressed in the report are:

Context: Briefly discuss the context in which you are running your project.

Problem at hand: Clarify the problem at the base of the project, and indicate its intrinsic difficulties.

Project management:Demonstrate how you have organized the work, and how you are controlling it (instead of the work controlling you!)

Scope: What are the boundaries of your project? What is not included in the project?

Risks: Which risks were envisioned, and which have been mitigated? What is the priority of the risks that still need to be migitated? E.g., which external dependencies might have an affect on your outcome? Which alternatives have you prepared in case this risk instantiates?

Software reengineering:

Tests: How can you verify that you satisfy the requirements? Which testing strategy have you selected, and what are the arguments for this selection? How confident are you that your solution satisfies the requirements?

Quality assurance: What are the non-functional requirements? E.g., how do you differentiate between a good and a bad solution?

Note: similar to previous years, it is once again possible to submit your own project proposals. These proposals will be approved in case they provide a well-structured exercise on the reengineering techniques presented in the lab sessions. E.g., you can always propose to reengineer another software system, for instance the software system used in your thesis, or written for another case.