PROJECT: JitHub

Ui

Introduction

This portfolio documents my contribution to this group project for the module CS2113T Software Engineering & Object-Oriented Programming taught in the National University of Singapore and showcases my ability to contribute production quality software engineering work to a small/medium software project, and the ability to work in a team of 5.

We are required to enhance a Java sample AddressBook application with 6kLoc(lines of code) while following software engineering principles taught in the module.

Product Overview

Our end product, JitHub, is a CLI (Command Line Interface) desktop application that helps students manage group project meetings through cross-checking the timetables of their group mates.

JitHub can:

  • Suggest available timeslot for group project meetings

  • Import/Export contacts details between group members

  • Keep track of your todos

  • Suggest/Autocomplete your commands

Summary of contributions

  • Major enhancement: added the ability to import/export contacts details of different project groups

    • What it does: allows students to share contact details specific to different projects among his/her group members.

    • Justification: This feature improves the product significantly because only one member from the group is required to key in all the details, in contrast to requiring everyone in the team to type in the exact same details, which is tedious and inefficient.

    • Highlights: This enhancement required an in-depth analysis of design alternatives regarding reading and writing data. The implementation too was challenging as it required thorough understanding of all the components related to data storage in the application.

    • Credits: OpenCSV

  • Code contributed: [Functional code] - about 2K LoC(Lines of Code) including tests.

  • Other contributions:

    • Project management:

      • Managed milestones v1.1 - v1.4 (4 milestones) on GitHub

    • Enhancements to existing features:

      • Updated the GUI to reflect persons and todos (Pull requests #117)

      • Wrote additional tests for existing features to increase coverage from 77% to 80% (Pull requests #200)

    • Documentation:

      • Did cosmetic tweaks to existing contents of the User Guide: #14

    • Community:

      • PRs reviewed (with non-trivial review comments): #4, #27, #29, #73

      • Reported bugs and suggestions for other teams in the class (examples: 1, 2, 3)

    • Tools:

      • Integrated a third party library (OpenCSV) to the project (#62)

      • Integrated Github plugins (TravisCI and Coveralls) to the team repo

Contributions to the User Guide

Given below are sections I contributed to the User Guide.

They showcase my ability to write documentation targeting end-users.

Export contacts displayed: export

You can save the hassle of your group mates typing in the exact same contact details of your group members if you have already save them into your JitHub.

To do so, simply find the person(s) and export the contact details in JitHub to a file and share it with your group mates.

Format: export FILENAME.xml

Examples:

  • find Alex

  • export alex.xml

  1. The file will be located in <DIRECTORY OF YOUR JAR FILE>/data/FILENAME.xml

  2. This command overwrites any files with the same name at <DIRECTORY OF YOUR JAR FILE>/data/

Your team members can import the contact details to their JitHub. Please refer to Import contacts: import.

Import contacts: import

You can save the hassle of typing in the exact same contact details of your group members if one of your group members have already save them into his/her JitHub.

To do so, politely ask them to export the contact details and place the file your teammate exported into the /data/ of your JitHub and import it into your JitHub.

Format: import FILENAME.xml

Examples:

  • import alex.xml

  1. The file to import must be placed in <DIRECTORY OF YOUR JAR FILE>/data/

  2. Persons that already exist in your JitHub won’t be imported. To import an existing person in JitHub with different contact details, please delete them first.

  3. The undo command works with the import command.

You can refer to Export contacts displayed: export for instructions on how to export contact details.

Exporting all contacts : exportall

Export the name, phone, address and email of all persons in the addressbook under the specified filetype.
Format: exportall FILETYPE

Examples:

  • exportall csv

  • exportall vcf [coming in v2.0]

  1. The file will be located in <DIRECTORY OF YOUR JAR FILE>/data/jithub.csv.

  2. This command overwrites the previous <DIRECTORY OF YOUR JAR FILE>/data/jithub.csv.

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide.

They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Export component

ExportClassDiagram
Figure 1. Structure of the Export Component

API : Export.java

The Export component can save the filtered persons to the specified file in xml format.

Import component

ImportClassDiagram
Figure 2. Structure of the Import Component

API : Import.java

The Import component can read the Address Book data from the specified file in xml format.

The import component (Import.java and ImportManager.java) is packaged under the export package.

ExportAll feature

Current Implementation

The exportall mechanism is facilitated by CsvWriter. Internally, a CSVWriter object from the OpenCSV library is instantiated to write all persons to the default file path /data/jithub.csv. Currently, it implements the following operation(s):

  • CsvWriter#write() — Writes the name, phone, address, and email of all persons in the current address book to /data/jithub.csv, and overwrites the file if an older version is available.

This operation is exposed in the Model interface as Model#exportAddressBook().

Given below is an example usage scenario and how the exportall mechanism behaves at each step.

Step 1. The user calls the exportall command with exportall csv.

Step 2. The LogicManager calls parseCommand with the user input.

Step 3. The AddressBookParser is called and it returns a ExportAllCommand object to LogicManager.

Step 4. The LogicManager calls execute() on the ExportAllCommand object

Step 5. The Logic component then interacts with the Model component by calling exportAddressBook() of the Model interface.

Step 6. The Model interface creates a new CsvWriter object and invokes the method write().

Step 7. The CsvWriter writes the data to the defined file path.

The file path is defined in outputFilepath, and is hardcoded as /data/jithub.csv for now.
Any existing file named as jithub.csv at the defined path will be overwritten.

The following sequence diagram shows how the ExportAll operation works:

ExportAllSequenceDiagram

Implementation of CsvWriter#write()

Given below is the algorithm behind the write() method used in the ExportAll Command:

Step 1. Instantiate an OpenCSV writer.

Step 2. Write the header to the csv file.

Step 3. Declare a List<String[]> data.

Step 4. Loop through an ObservableList<Person> containing all persons in the AddressBook and push String[] personDetails to data.

// Generates a string array for each person and stores the details
String[] personDetails = new String[header.length];
personDetails[INDEX_PERSON_NAME] = person.getName().toString();
personDetails[INDEX_PERSON_PHONE] = person.getPhone().toString();
personDetails[INDEX_PERSON_ADDRESS] = person.getAddress().toString();
personDetails[INDEX_PERSON_EMAIL] = person.getEmail().toString();

Step 5. Write data to the csv file.

Step 6. Close the OpenCSV writer.

Design Considerations

Aspect: How data in the AddressBook is passed into the CsvWriter object

  • Alternative 1 (current choice): ObservableList<Person>

    • Pros: Easy to implement since getFilteredPersonList() is already implemented.

    • Cons: We must ensure that the implementation of each individual command are correct.

  • Alternative 2: versionedAddressBook

    • Pros: Looks more direct since the whole AddressBook is passed into the CsvWriter.

    • Cons: Hard to write tests and requires more methods to process the data.

  • Solution: The data is passed into the CsvWriter object through its constructor as an ObservableList<Person>.

Appendix A: User Stories

Priority As a/an …​ I want to …​ So that I can…​

* * *

student who does not like to do unnecessary work

import the contact details my group members saved before

avoid unnecessary typing

* * *

student who likes to save the trouble of my group mates

export the contact details of my other group members that I have saved

share it to my group members for them to import to their JitHub

Use case: Export contacts

MSS

  1. User finds the contacts he wants to export.

  2. JitHub shows a list of contacts matching the search criteria.

  3. User requests to export the contacts shown to a file with specific filename.

  4. JitHub exports the list of contacts to the specific file.

  5. User sends the file to his/her group members. Use case ends.

Extensions

  • 2a. The list is empty.

    • 2a1. User requests to export the empty contacts to a file with specific filename.

    • 2a2. JitHub indicates there is nothing to export.

      Use case ends.

  • 3a. The given filename is invalid.

    • 3a1. JitHub shows an error message.

      Use case resumes at step 3.

Exporting and importing data

  1. Exporting an empty list

    1. Prerequisites: Clear all persons using the clear command.

    2. Test case: export somefile
      Expected: Error message "Invalid command format!"

    3. Test case: export somefile.xml
      Expected: Error message "There is nothing to export!"

  2. Importing a non-existent file

    1. Prerequisites: The file somefile.xml does not exist at <DIRECTORY OF YOUR JAR>/data/

    2. Test case: import somefile
      Expected: Error message "Invalid command format!"

    3. Test case: import somefile.xml
      Expected: Error message "File not found!"

  3. Exporting and importing the whole JitHub

    1. Prerequisites: List all persons using the list command.

    2. Test case: export somefile.xml + clear + import somefile.xml
      Expected:

      • The persons listed are cleared after the clear command.

      • The persons cleared are restored after the import command.

PROJECT: AnimatedEpp

{Optionally, you may include other projects in your portfolio.}