PROJECT: FreeTime

1. Overview

FreeTime is a desktop application that helps users coordinate their schedules with their friends or groupmates. It allows users to add and remove events from their timetables. It also uses these individual user timetables to generate a combined timetable showing when everyone the user wants to meet is available.

FreeTime receives input through a command line interface (CLI) while displaying output through a graphical user interface (GUI). It is written in Java, and has approximately 10 kLoC.

FreeTime was developed in a team of four throughout the course of a semester. It is modified from the Address Book (Level 4) (AB4) project by SE-EDU.

FreeTime was developed as part of the module requirements for the following modules offered by the School of Computing, National University of Singapore:

  • CS2113 - Software Engineering & Object-Oriented Programming

  • CS2101 - Effective Communication for Computing Professionals

This project portfolio documents my contributions to the FreeTime project.

2. Summary of contributions

  • Major enhancement: Added timetables to FreeTime

    • What it does: Implements timetables for each user and allows the user to add and remove timeslots from their own timetables. Additionally, allows users to determine when they can organise meetings such that everyone they want to meet can be present.

    • Justification: As it is difficult for students with varied and complex timetables to schedule meetings for their many group projects, FreeTime simplifies this process by automatically highlighting mutually free timeslots among different user timetables.

    • Highlights: This enhancement was challenging as it required the development of a completely new portion of the GUI for the displaying of timetables, which required proficiency in JavaFX, the software platform used to build FreeTime’s GUI. Moreover, significant additions were made to the Model component to allow the in-app storage of timetables.

  • Code contributed

  • Other contributions:

    • Project management:

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

    • Community

      • PRs reviewed: Pull requests #20, #63, #68, #153

      • Reported bugs for other teams in the class: 1, 2, 3

    • Tools:

    • Miscellaneous enhancements to new and existing features:

      • Added aliases for all commands: Pull request #3

      • Updated sample data loaded when FreeTime first loads up: Pull requests #80, #167, #169

      • Updated existing commands in AB4 to work with FreeTime: Pull requests #82, #108, #109

3. Contributions to the User Guide

This section details my contributions to FreeTime’s User Guide.

3.1. Add a timeslot to your timetable: add (a)

Adds a timeslot to your timetable.

Format: add Monday 10:00-12:30

  • FreeTime uses the 24-hour clock, so 01:00 means 1 am, not 1 pm!

  • Shortforms for the day of the week are fine too. e.g. you can type Mon instead of Monday.

  • If you type a single number, like 10 for either the start or end time, FreeTime will assume that you mean 10:00.

  • You cannot add a timeslot that clashes with your current timetable.

Examples:

  • add Monday 10:00-12:30
    Adds the timeslot from 10:00 to 12:30 on Monday to your timetable.

  • add Fri 13:30-14:00
    Adds the timeslot from 13:30 to 14:00 on Friday to your timetable.

  • add Wed 17-18
    Adds the timeslot from 17:00 to 18:00 on Wednesday to your timetable.

After adding a timeslot, you should see the following:

AddTimeSuccess
Figure 1. Timeslot added to your timetable

Jump back to FreeTime's feature list

3.2. Delete a timeslot from your timetable: delete (d)

Deletes a timeslot from your timetable.

Format: delete Monday 10:00-12:30

  • FreeTime uses the 24-hour clock, so 01:00 means 1 am, not 1 pm!

  • Shortforms for the day of the week are fine too. e.g. you can type Mon instead of Monday.

  • If you type a single number, like 10 for either the start or end time, FreeTime will assume that you mean 10:00.

  • You cannot delete a timeslot that is not already in your timetable.

Examples:

  • delete Monday 10:00-12:30
    Deletes the timeslot from 10:00 to 12:00 on Monday from your timetable.

  • delete Fri 13:30-14:00
    Deletes the timeslot from 13:30 to 14:00 on Friday from your timetable.

  • delete Wed 17-18
    Deletes the timeslot from 17:00 to 18:00 on Wednesday from your timetable.

3.3. Show free slots among selected people: free (fr)

Highlights timeslots where you and everyone specified is free.

Format: free INDEX…​

  • You can specify more than one friend.

  • The indices refer to the index number shown in your friend list.

  • The indices must be positive integers 1, 2, 3, …​

Examples:

  • free 1 2
    Highlights timeslots where you, friend 1, and friend 2, are all free to meet up.

After executing the command, you should see the following:

FreeTimeSuccess
Figure 2. Timeslots highlighted in green are available while timeslots highlighted in red are unavailable.

Jump back to FreeTime's feature list

4. Contributions to the Developer Guide

This section details my contributions to FreeTime’s Developer Guide.

4.1. Timetable feature

4.1.1. Current implementation

FreeTime’s timetable feature allows users to store and view their own timetables.

FreeTime can also display a deconflicted timetable, highlighting mutually free timeslots among the current user and all other selected people.

The timetable feature can be broadly split into two parts:
1. The backend, which handles the storage and logic of TimeTable objects;
2. The frontend, which handles the display of TimeTable objects.

Backend implementation

The TimeTable object is composed under the Person class in Model. Each TimeTable is composed of any number of TimeSlot objects. Each TimeSlot consists of:
1. One DayOfWeek object to indicate the day of week of the TimeSlot;
2. Two LocalTime objects to indicate the start time and end time of the TimeSlot respectively.
3. One Color object to indicate the color of the TimeSlot when displayed on FreeTime’s UI.

The following class diagram summarises the relationship between the components of the TimeTable class:

TimeTableClassDiagram
Figure 3. Structure of the TimeTable Class

The TimeTable class implements two key methods:
1. TimeTable#addTimeSlot() - to add a new TimeSlot to the TimeTable
2. TimeTable#deleteTimeSlot() - to remove an existing TimeSlot from the TimeTable

The class DeconflictTimeTable, which inherits from TimeTable, is used when the free command is executed to store mutually free timeslots among users.
When the free command is executed, a DeconflictTimeTable object is instantiated with all TimeSlot objects in the user’s TimeTable. Subsequently, the TimeTable objects of every Person that is passed as an argument to the free command is added to the DeconflictTimeTable.

The following sequence diagram shows the significant method calls for the method FreeCommand#execute():

DeconflictSequenceDiagram
Figure 4. Interactions between the Logic Component and Model Component for the FreeTime#execute() Method

The key difference between TimeTable and DeconflictTimeTable lies in the implementation of the addTimeSlot() method. TimeTable#addTimeSlot() throws a TimeSlotOverlapException when the TimeSlot to be added overlaps with an existing TimeSlot in the TimeTable.
However, DeconflictTimeTable#addTimeSlot() merges the TimeSlot to be added with all overlapping TimeSlot objects in the DeconflictTimeTable. Thus, DeconflictTimeTable#addTimeSlot() never throws TimeSlotOverlapException.

Frontend implementation

TimeTablePanel extends the abstract class UIPart and is implemented using a BorderPane. It is composed of the following classes:
1. TimeTableDayMarkerGrid - a GridPane on the left of the TimeTablePanel to display the days of the week;
2. TimeTableTimeMarkerGrid - a GridPane on the top of the TimeTablePanel to display the time markers
3. TimeTableMainGrid - a GridPane in the center of the TimeTablePanel. Composed of any number of TimeTablePanelTimeSlot objects.

The following class diagram summarises the relationship between the components of the TimeTablePanel class:

TimeTablePanelClassDiagram
Figure 5. Structure of the TimeTablePanel Class

The following screenshot shows the relative position of all the components in TimeTablePanel:

TimeTableScreenshotLabelled
Figure 6. Layout of the TimeTablePanel

FreeTime’s UI is updated through the EventsCenter every time Model#updateTimeTable() is called.

The following sequence diagram shows the significant method calls for the method Model#updateTimeTable().

UpdateTimeTableSequenceDiagram
Figure 7. Interactions between the Model, EventsCenter, and UI Components for the FreeTime#execute() Method

 

4.1.2. Design Considerations

Aspect: How the frontend updates the TimeTable to be displayed

  • Alternative 1 (current choice): Clears the entire TimeTableMainGrid before loading the new TimeTable

    • Pros: Easy to implement, only one method (loadTimeTable()) is required

    • Cons: May suffer from performance degradation, especially when the TimeTable to be loaded contains many TimeSlot objects

  • Alternative 2: Detect the difference between the currently displayed TimeTable before adding or deleting TimeTablePanelTimeSlot objects accordingly.

    • Pros: Reduces execution time of methods which update the displayed TimeTable

    • Cons: A method to detect the difference between TimeTable objects must be implemented. May not result in significant performance improvements when switching between TimeTable objects with few or no TimeSlot objects in common.