1. PROJECT: Hallper

The purpose of this portfolio is to document my role in and contributions to the project Hallper.

2. Introduction

About Hallper: Hallper is a desktop administration application used by Junior Common Room Committee (JCRC) members of the halls of NUS that facilitates management of hall residents and events. Our team of five undergraduate computer science students decided to create Hallper by building upon the existing AddressBook Level 4 application to improve management activities for JCRC members. Some of the main features include new features such as calendar, email and budgeting, as well as enhancement features such as erase, search and clear commands.

My role and contributions: I was tasked to implement four features: clear, erase, import and export commands. Every two weeks, I reviewed the milestones that were set before our team embarked on building Hallper, based on the features I had to implement, so i could complete my assigned portion on time. I also helped to review my team members’ codes to check for coding style errors and to keep myself updated with their implementations.

3. Summary of contributions

This section lists the major and minor enhancements I have contributed to building Hallper, as well as miscellaneous contributions in other aspects of this project.

  • Major enhancement 1: added the ability to import residents data to update Hallper

    • What it does: This feature allows the user to import xml files from the computer to update resident information stored in Hallper. The user can update information in various parts of Hallper based on the format of the imported file.

    • Justification: This feature improves Hallper significantly as the user can mass update resident information using a single command without having to key in the data one by one.

    • Highlights: This enhancement is highly case-sensitive as it requires the format of the imported file to be strictly followed for the data to be successfully read. However, more file formats can be added by future developers based on the current implementation of this command.

  • Major enhancement 2: added the ability to export residents data from Hallper

    • What it does: This feature allows the user to export all residents data in Hallper to an xml file on the computer.

    • Justification: This feature facilitates transporting of Hallper information across various devices, accompanied by the import command. Residents information can also be extracted to the computer for viewing or usage outside of the application.

    • Highlights: This enhancement allows users to export the xml file to any valid directory on the computer.

  • Minor enhancement 1: added the ability to erase CCAs from residents in Hallper

    • What it does: This feature allows the user to erase specified CCAs from all residents in Hallper.

    • Justification: This feature speeds up the reassigning of CCAs by facilitating mass CCA erasure. Users need not go through the residents one by one to remove the target CCAs.

    • Highlights: This enhancement is a prelude to the import feature as it clears CCAs of the residents for reassignment later using the import feature.

  • Minor enhancement 2: improved the ability to clear residents from Hallper

    • What it does: This feature allows the user to clear residents associated with the specified CCA and/or room number, or to clear the entire database.

    • Justification: This feature expands the functions of the existing clear command by allowing more flexible clearing options. The original clear command only allowed for clearing the entire database.

    • Highlights: This enhancement allows the user to clear residents under multiple keywords (CCA, room number) using just a single command line as multiple keywords can be specified at once in any order.

  • Code contributed: [Project Code Dashboard]

  • Other contributions:

    • Documentation:

      • Updated existing content in the User Guide: #65 #85

      • Documented implementation for my assigned commands in Developer Guide: #112

    • Community:

      • Reviewed pull requests by team members at each milestone.

4. Contributions to the User Guide

This section contains some of my contributions to the User Guide for Hallper. It has been documented and worded to facilitate mastering of features by end-users.

4.1. Clearing specific residents : clear

Clears residents associated with specified CCAs from Hallper.
Format: clear KEYWORD…​

  • Clears residents associated with specified KEYWORD.

  • KEYWORD refers to either a CCA or a ROOM.

  • Multiple KEYWORDS can be specified at once, in any order.

Example:

  • clear basketball
    Clears all residents associated with CCA basketball.

  • clear A123
    Clears all residents associated with room A123.

  • clear baseball C456
    Clears all residents associated with CCA baseball and room C456

4.2. Exporting residents' information: export

Exports file containing existing residents' information in Hallper.
Formate: export dst/PATH fn/FILENAME

  • The file exported will be a .xml file.

Example:

  • export dst/C://Users/Files fn/data.xml
    Exports Hallper residents information into data.xml located at C://Users/Files.

4.3. Importing residents information : import

Imports file containing Hallper-related information and updates Hallper accordingly.
Format: import f/FILEPATH

  • Allows for the mass upload of resident or CCA information.

  • The file to be uploaded must be a .xml file.

File format examples for importable .xml files are as shown below:

AddressBookExample

Figure 4.1.9.1: Resident information example. Multiple persons can be specified.

CCAListExample

Figure 4.1.9.2: CCA list example. Residents are identified by their unique room number. Multiple room can be specified for multiple cca.

BudgetBookExample

Figure 4.1.9.3: Budget book information example. Multiple transaction can be specified for multiple ccas.

TransactionsExample

Figure 4.1.9.4: Transaction information example. Multiple transaction can be specified.

Example:

  • import f/C://Users/Files/data.xml
    Imports data.xml file to be read and for Hallper to be updated accordingly.

5. Contributions to the Developer Guide

This section contains some of my contributions to the Developer Guide for Hallper. It contains a technical documentation of my implementations of the features assigned to me as mentioned in the introduction.

5.1. Clear feature

5.1.1. Current Implementation

The clear feature allows the user to clear persons associated with specified keywords from the database.

It implements the following operations: * ClearCommand#clearAll(Model model) — Clears the entire database. * ClearCommand#clearSpecific(Model model) — Clears persons associated with specified keywords.

These operations are exposed in the Model interface as Model#commitAddressBook, Model#resetData() and Model#clearMultiplePersons(List<Person> target).

Given below is an example usage scenario and how the clear mechanism behaves at each step:

Step 1. The user specifies CCA(s) and/or room(s) of persons to be cleared from the database.

Step 2. ClearCommandParser checks for the validity of the CCA(s) and/or room(s) specified. If non-existent argument(s) specified, a CommandException will be thrown. A combination of existing and non-existent arguments specified will be successfully parsed.

Step 3. ClearCommand#execute(Model model, CommandHistory history) is then called and invokes ClearCommand#clearSpecific(Model model), which uses the specified arguments to create a persons list containing associated persons to be cleared. ModelManager#clearMultiplePersons(List<Person> target) is then invoked to clear the internal list of persons in target.

Step 4. After the internal list is cleared, ModelManager#clearMultiplePersons(List<Person> target) then invokes ModelManager#indicateAddressBookChanged(), which raises an AddressBookChangedEvent which is handled by EventsCenter.

Step 5. AddressBookChangedEvent is then handled by StorageManager#handleAddressBookChangedEvent(AddressBookChangedEvent event). StorageManager#saveAddressBook(ReadOnlyAddressBook data) is then called to update the existing addressbook.xml file with the cleared persons list.

The following sequence diagram shows how the clear operation works:

ClearCommandSequenceDiagram

Figure 4.5.1.1: Sequence diagram of clear command on specified keywords.

The following activity diagram summarizes what happens when a user executes the clear command:

ClearCommandActivityDiagram

Figure 4.5.1.2: Activity diagram showing different path flows of clear command.

5.1.2. Design Considerations

Aspect: Merging command to clear entire database or specific persons

  • Alternative 1 (current choice): Clear command is merged.

    • Pros: Due to the similar function of clearing persons from the database, merging them under a single command makes it easier for the user to remember and produce the command input. Clearing of the entire database is also rarely executed so it makes logical sense to merge these commands.

    • Cons: The user will not be able to use all as a CCA as it is a reserved keyword to clear the entire database.

  • Alternative 2: Clear commands are separated.

    • Pros: The user can clearly distinguish between the two features by renaming them with different command inputs.

    • Cons: There is no need for a separate command for clearing the entire database as it is a rarely used feature.

5.2. Export feature

5.2.1. Current Implementation

The export feature allows Hallper data to be exported as an xml file to the computer.

It implements the following operation:

  • ExportCommand#execute(Model model, CommandHistory history) — Exports current Hallper data as an xml file to the specified path.

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

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

Step 1. The user exports an 'xml' file by specifying the destination path and name of the exported file.

Step 2. ExportCommandParser checks for the validity of the path and file name. If path or file name are invalid, Hallper data will not be exported. Otherwise, path and filename will be parsed into a single, full path.

Step 3. ExportCommand#execute(Model model, CommandHistory history) then invokes ModelManager#exportAddressBook(Path filePath) which raises an ExportAddressBookEvent.

Step 4. ExportAddressBookEvent is then handled by StorageManager#handleExportAddressBookEvent(ExportAddressBookEvent event). StorageManager#exportAddressBook(ReadOnlyAddressBook addressBook, Path path) is then called to export Hallper’s storage data to the specified path.

The following sequence diagram shows how the export operation works:

ExportCommandSequenceDiagram

Figure 4.8.1.1: Sequence diagram of export command.

The following activity diagram summarizes what happens when a user executes the export command:

ExportCommandActivityDiagram

Figure 4.8.1.2: Activity diagram showing different path flows of export command.

5.2.2. Design Considerations

Aspect: Choice of export format

  • Alternative 1 (current choice): Export .xml format only.

    • Pros: Easy for user to update and re-import the .xml file. Standardised format for Hallper-related data files.

    • Cons: Difficult to convert/transfer data to other applications due to limited export format. Need to use external applications to convert .xml file.

  • Alternative 2: Export .xml, .txt and .xlsx formats.

    • Pros: More options for user to export Hallper data. Exported files can be read across different applications.

    • Cons: Unused file formats. .xml is the format that is mainly used by Hallper so .txt and .xlsx may be underused or unused.

5.3. Import feature

5.3.1. Current Implementation

The import feature allows .xml files of different formats to be imported from the computer.

It implements the following operations and classes:

  • ImportCommand#parseFile() — Parses specified path into document for reading.

  • ImportAddressBook#execute(Document doc, Model model) — Imports .xml file from the specified path to update Hallper data.

  • ImportCcaList#execute(Document doc, Model model) — Imports .xml file from the specified path to update Hallper contacts' CCAs.

These operations are exposed in the Model interface as Model#commitAddressBook(), Model#addMultiplePersons() and Model#updateMultiplePersons.

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

Step 1. The user imports .xml file by specifying the path of the file.

Step 2. ImportCommandParser checks for the validity of the path and .xml file format. If .xml file has an invalid format, the specified file will not be imported.

Step 3. ImportCommand#parseFile() then prepares the file for reading by parsing into a document.

Step 4: ImportCommand#execute(Model model, CommandHistory history) then invokes ImportAddressBook#execute(Document doc, Model model) to read the document.

Step 5. After the document data is read, ImportAddressBook#execute(Document doc, Model model) then invokes ModelManager#addMultiplePersons(List<Person> personList) to update Hallper’s internal list and ModelManager#indicateAddressBookChanged(), which raises an AddressBookChangedEvent which is handled by EventsCenter.

Step 6. AddressBookChangedEvent is then handled by StorageManager#handleAddressBookChangedEvent(AddressBookChangedEvent event). StorageManager#saveAddressBook(ReadOnlyAddressBook data) is then called to update the existing addressbook.xml file with the new contacts.

The following sequence diagram shows how the import operation works:

ImportCommandSequenceDiagram

Figure 4.7.1.1: Sequence diagram of import command.

The following activity diagram summarizes what happens when a user executes the import command:

ImportCommandActivityDiagram

Figure 4.7.1.2: Activity diagram showing different path flows of import command.

5.3.2. Design Considerations

Aspect: Choice of component to read imported file

  • Alternative 1 (current choice): Reads file in Logic.

    • Pros: Easy to change parsing of .xml file when .xml file format changes. New .xml file formats can be added without disrupting the existing parsers.

    • Cons: Importing from the computer is a storage-related feature but the reading of the file is located outside of Storage component.

  • Alternative 2: Reads file in Storage.

    • Pros: Proper grouping of import implementation inside related component.

    • Cons: More complicated implementation if more .xml file formats are added to be parsed in the future.