PROJECT: FreeTime

1. Overview

This Project Portfolio outlines my personal contributions to this team project.

FreeTime is the product of my CS2113T project, done at National University of Singapore. In CS2113T, our team of 4 had to morph an existing application (AddressBook 4) into a different application, all the while ensuring the best coding practices and teamwork.

FreeTime is a Time-Planner application. It is primarily aimed at Students. The most unique feature about FreeTime is that it has the ability to quickly display the times when a group of friends are able to meet up.

Users can import existing timetables into FreeTime, and then proceed to do changes to it, such as adding or removing a timeslot. When they are satisfied with their timetable, they can view the times when they and their friends are mutually free, using the freetime feature.

The main interaction is through a command-line interface (CLI), but the graphical user interface (GUI) is also available. It is written in Java, and has about 10 kLoC.

2. Summary of contributions

This section is a brief summary of my personal contributions to this team project.

  • Major enhancement: Import and Export Command

    • What it does: Allows the user to import and export timetables that are in the .ics format.

    • Justification (Import): It is a time consuming process for users to manually add their timeslots one-by-one. The import command makes users' lives so much easier, because adding a full timetable is now reduced to a 1-step process.

    • Justification (Export): Having a export feature can allow users to share their personal timetables with their friends.

    • Highlights: I learnt to implement a third-party library into an existing product. It also taught me to be meticulous in my coding, as there can be many unforeseen issues with certain implementations of code. For example, I ran into a timezone bug because I focused too much on implementing logic and left out on testing.

    • Credits: biweekly third-party library (https://github.com/mangstadt/biweekly)

  • Minor enhancement: Save user’s timetable across application instances.

    • What it does: Allows the application to save the timetable into the disk automatically. This means that it can remember our users' timetables across restarts.

  • Code contributed: [Link to RepoSense]

  • Other contributions:

    • Project management:

      • Contributed to releases v1.1 - v1.4 (3 releases) on GitHub

    • Documentation:

      • Created documentation for import, export command and save timetable feature.

    • Community:

      • PRs reviewed (with non-trivial review comments): #116

      • Contributed to forum discussions (examples: 63)

    • Tools:

      • Integrated a third party library (biweekly) to the project (#55)

3. Contributions to the User Guide

Here are my contributions to the User Guide. I tried to write it so that users could easily understand the commands. I have also included step-by-step instructions for the examples, so that users can get started quickly.

3.1. Import Timetable : import (im)

Use this command to import a timetable for the current user from a specified file.
See the example below for a quick start!

Format: import FILE_NAME

  • Command parameters:

    • FILE_NAME refers to the name of the file that you want to import.

      • Do not include the .ics file extension when typing the command.

      • In other words, type: import nusmods_calendar instead of import nusmods_calendar.ics

  • Compatibility:

    • Only supports .ics files exported from NUSMODS.

  • Location of the import file:

    • The file will be imported from the folder import_export, which is located in the same folder as the FreeTime.jar file.

      • Please see the image below:

UG import directory
Figure 1. Location to put your import files.

Example:

  • import nusmods_calendar
    Imports the timetable from .\import_export\nusmods_calendar.ics
    (where . represents the folder that the application is in.)

    1. Download your file from NUDMODS website:

      UG import step 1
      Figure 2. Download your file from NUDMODS website.

    2. Copy your desired .ics file to the import_export folder:

      UG import step 2
      Figure 3. Copy your file to the correct folder.

    3. Go back to FreeTime, and type in the command import nusmods_calendar :

      UG import step 3
      Figure 4. Type this, then press enter!

    4. If the import was successful, FreeTime should look similar to this :

      UG import step 4
      Figure 5. Import Success! :)

      Jump back to FreeTime's feature list

3.2. Export Timetable : export (ex)

Use this command to export the currently-displayed timetable as an .ics file. See the example below for a quick start!

Format: export FILE_NAME

  • See the example below for a quick start!

  • Command parameters:

    • FILE_NAME refers to the name of the file that you want to export.

      • Do not include the .ics file extension when typing the command.

      • In other words, type: export my_timetable instead of export my_timetable.ics

  • Compatibility:

    • Can be imported back into FreeTime

  • Location of the exported file:

    • The file will be exported to the folder import_export, which is located in the same folder as the FreeTime.jar file.

      • Please see the image below:

UG export directory
Figure 6. Location of your exported files.

Example:

  • export my_timetable
    Exports the displayed timetable to .\import_export\my_timetable.ics
    (where . represents the folder that the application is in.)

    1. Ensure that the timetable you want to export is being shown:

      1. type select me to display your own timetable.

      2. type select INDEX to display one of your friend’s timetable.

        UG export step 1
        Figure 7. Select the desired timetable.

    2. Type the command export my_timetable:

      UG export step 2
      Figure 8. Type the command.

    3. If the export was successful, Your timetable should be waiting for you in the folder :

      UG export step 3
      Figure 9. Exported file is in the import_export folder

Jump back to FreeTime's feature list

4. Contributions to the Developer Guide

Here are my contributions to the Developer Guide. I tried to write it to be as informative as possible for Developers who are going to take over my code. They showcase my ability to write technical documentation targeting developers.

4.1. Import and Export timetable feature

The import and export timetable feature allows users to import and export their timetables from and to external applications as .ics files.

The Import command currently supports timetables from NUSMODS. [https://nusmods.com] This makes it easy for existing users of NUSMODS to bring their timetables into FreeTime

The Export command currently supports FreeTime. This makes it possible to make backups of your timetable, or to share it with other users of FreeTime.

4.1.1. Current implementation

The import and export feature consists of two parts:

  1. The frontend, which parses user input, and informs the user of success or failure.

  2. The backend, which handles the reading and writing of .ics files, and the conversion between the .ics format and the TimeTable object.

Frontend implementation

Similar to the other commands; see Events-Driven nature of the design.

Backend implementation - IcsUtil Class

The IcsUtil class implements two public methods for handling .ics files:

  1. IcsUtil#readTimeTableFromFile() - to read a TimeTable from a specified .ics file on the disk

  2. IcsUtil#saveTimeTableToFile() - to write a TimeTable to a specified location on the disk

Backend implementation - Import

The general implementation are as follows:

  1. Biweekly(external library) is used to obtain an ICalendar object, by reading the import file

  2. The ICalendar is converted to TimeTable by IcsUtil.

  3. Using this TimeTable, we can update the model.

The following sequence diagram shows how the TimeTable is imported:

ImportSequenceDiagram
Figure 10. Interactions between the various Components for the Import Command
Backend implementation - Export

The general implementation are as follows:

  1. The currently displayed TimeTable is obtained from model.

  2. the TimeTable is converted into an ICalendar by IcsUtil.

  3. The ICalendar is written to the file using Biweekly(external library).

The following sequence diagram shows how the TimeTable is exported:

ExportSequenceDiagram
Figure 11. Interactions between the various Components for the export Command

4.1.2. Design Considerations

Aspect: Which Classes (and which system(s)) should parse the ics file format?

  • Alternative 1 (current choice): All code related to parsing .ics timetable files are inside 'IcsUtil' class. When executing ImportCommand/ExportCommand, it directly calls a method in IcsUtil.

    • Pros:

      • All methods that have to do with .ics parsing are in one class. Easier to implement and manage, given that there are only a few methods for now.

      • Less dependencies. (directly call IcsUtil to read/write .ics files; compared to having to call IcsStorage which then calls IcsUtil).

    • Cons:

      • Single responsibility principle is broken. Also, difficult to manage if the class expands and has more methods.

  • Alternative 2 (Go through the Storage subsystem): Follow the existing IO implementation of addressbook.xml; create an IcsTimeTableStorage class to access the ics file in hard disk.

    • Pros:

      • Similar implementation to existing: Classes that have to do with IO are accessed using the Storage Interface.

    • Cons:

      • Increased dependency: LogicManager will then have increased dependency on Storage.

      • More difficult to implement: Storage subsystem needs to be created on starting the app, whereas the import and export commands are called ad-hoc.