Tan Wei Hao - Project Portfolio

PROJECT: Codeducator

Overview

Codeducator is a desktop address book application for private programming language tutors. Users are able to track the progress of their students, manage their tutoring schedule and other important information about their students.

Codeducator has a graphical user interface built with JavaFX but most of the user interactions are done using command line interface. It is written in Java and has about 10 kLoC.

This project is based on the AddressBook-Level4 created by the SE-EDU initiative.

Summary of contributions

Major enhancement: added Scheduling functionality and Google Services integration.
- What it does: It allows a user to add lessons for students in their contact list.
  - Schedule helps tutors keep track of their lessons.
  - Lessons can be added to the schedule.
  - Users can upload contacts data and schedule data to Google Contacts and Calendar respectively.
  - Easy organisation of data: Data uploaded to Google Contact is uploaded under contact group label "Students". Data uploaded to Google Calendar is uploaded under calendar name "Student List". This make the process of utilising Google Accounts much easier.
- Justification: This feature improves the product significantly because:
  - The target user faces a big problem in keeping track of their timetable and schedule. This feature allows a user to easily add, remove and view the events specific to his part time teaching job.
  - Sync helps to push contacts and schedule to the cloud and be utilised by users in the cloud data context, e.g. viewing across devices
- Highlights: Scheduling required an addition of a major component not in the default AddressBook-level4. It required an in-depth analysis of design alternatives. The implementation too was challenging as it required fundamental changes the existing Model objects. Relating lessons with students required a refactor of Student class
- Credits:
  - Uses the excellent CalendarFX class that was thankfully open source at the time of implementation.
  - Uses Google APIs, which are very well documented and well developed. Made my life easier when exploring the option of Google Service integration.
Minor enhancement: added a findTag command that allows the user to find Students by Tags.
Code contributed: [Functional code] [Test code] Both add up to around 3k lines of code.
Other contributions:
- Project management:
  - Managed releases v1.3 and v1.5rc (2 releases) on GitHub
- Enhancements to existing features:
  - Updated the current GUI color scheme (Pull requests #154)
  - Refactored AddressBook into a relational database where students are related to lessons by a Uniquekey
- Documentation:
  - Refactored User guide with a more user-friendly tone, where it was more conversational and not so instructional. Gave the user guide a more personalised touch.
  - Did cosmetic tweaks to existing contents of the User Guide: #174
- Community:
  - PRs reviewed (with non-trivial review comments): #167
  - Reported bugs for another team: 1, 2, 3, 4, 5, 6, 7, 8, 9
- Tools:
  - Integrated a third party library (Google APIs) to the project (#95)

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. I wrote extensive documentation on my parts in my user and developer guides, but excluded them to fit within the page limit.

Start of extract from [User Guide]

Scheduling component

Schedule

Scheduling is a major feature of Codeducator. To help tutors manage their student lessons, Codeducator has implemented a Schedule component that keeps track of your student lessons on a weekly basis. Codeducator assumes you have regular lessons on a weekly basis.

Figure 1. What you will see as a Schedule

The Schedule comprises of Lessons. A Lesson represents the tutoring lesson session you will have with a Student in your Contacts List.

The Lesson is displayed with

The displayed Lesson Index
The Student with whom you wil be having the Lesson with.

Viewing your Schedule

A quick refresh of what lessons you have in the week is a simple command away. You can easily view your Schedule with a simple command.

Format: `schedule`

Steps taken to view your schedule

Type schedule into the command box. Press enter to execute.

Figure 2. Executing the schedule command
View your schedule in its entirety!

Adding a Lesson to your Schedule

If your student needs extra lessons or you have new students that want lessons, Codeducator will allow you to add Lessons to your schedule.

Format: `addLesson INDEX [d/DAY] [st/START_TIME] [et/END_TIME]`

Adds a lesson for the Student identified by their INDEX, for a certain DAY, starting at START_TIME and ending at END_TIME

Adds a lesson for the student at the specified INDEX. The index refers to the index number shown in the last student listing. The index must be a positive integer 1, 2, 3, …
The day for the input is the abbreviated first three letters (non-case sensitive) of the name of day, i.e. mon for Monday, fri for Friday.
The time input must be in the format HH:MM, seperated by a colon :
The time input must be a valid 24-hour time within the range of 00:00 to 23:59
Input lesson cannot clash with existing lessons already in the Schedule
Lessons will be added in chronological order to your Schedule

Overnight lessons i.e. st/23:30 et/00:30 cannot be held. It is assumed that people lead normal lives and work between 00:00 and 23:59 of the same day.
If you need to add a lesson that ends at midnight, enter 23:59.

Examples:

list
addLesson 1 d/mon st/10:00 et/10:30
Adds a lesson for the 1st student of the list command. Lesson will be held on the day of mon and starting time will be 10:00 and ending time will be 10:30.
find Betsy
addLesson 1 d/tue st/12:00 et/13:30
Adds a lesson for the 1st student of the find Betsy command. Lesson will be held on the day of tue and starting time will be 12:00 and ending time will be 13:30.

Steps taken to add a lesson

Let’s say that you may want to add a Lesson for Bernice (index 2). The lesson time slot would be Sunday, 10:00am to 12:00pm.

Type schedule into the command box. Press enter to execute.

Figure 3. Executing the schedule command
Visually find a free time slot. Sunday, 10:00 to 12:00 looks free!
Type addLesson 2 d/sun st/10:00 et/12:00. Press enter to execute the command

Figure 4. Type out the command as shown
The lesson will be added to your Schedule!

Figure 5. Result of the addLesson command

End of extract from [User Guide]

And more (Deleting lessons, syncing with Google)…

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.

Start of extract from [Developer Guide] === Schedule feature ==== Current Implementation To get better control of one’s weekly schedule, we will now attach a component called Schedule to Model.

At startup, a new Schedule object is instantiated in ModelManager.

A Schedule has a LessonList, it contains an ObservableList<Lesson> internalList attribute, which stores all the Lesson objects that describes your schedule. The UI is bounded to this LessonList so that it can automatically update when data changes.

A Lesson has a UniqueKey attribute, a Day attribute, a starting TIME START_TIME and an ending TIME END_TIME attribute. Lesson objects are created by the addLesson command.

Implementation of commands that edit your Schedule

Commands that modify the schedule are addLesson and deleteLesson. Editing a student’s name will edit the name of the event in the schedule. Deleting a student will also delete all his lessons in the schedule.

Students have the UniqueKey field, which we will now use in Lesson to create a relation to Student objects.
A Lesson object called newLesson will be created by ModelManager.addLesson(UniqueKey key, Day day, Time startTime, Time endTime), which is implemented as such:

    public void addLesson(Student studentToAddLesson, Day day, Time startTime, Time endTime) {
        requireAllNonNull(studentToAddLesson, day, startTime, endTime);
        UniqueKey studentKey = studentToAddLesson.getUniqueKey();
        Lesson newLesson = new Lesson(studentKey, day, startTime, endTime);
        schedule.addLesson(newLesson);
        indicateScheduleChanged();
    }

A sequence diagram of the result can be seen from the below diagram.

Figure 6. Sequence Diagram of addLesson command

The student will be selected by the Index of the last seen list of students. The UniqueKey is then retrieved from the Student. A new Lesson will now be added for that student at the specific Day, startTime and endTime, associated with the Student by the key

No Lesson objects can be created for students not in contact list.

If you have a future implementation that requires the addition of a new attribute in the Schedule class, you must take note of updating the Model.addLesson(Student, Day, Time START_TIME, Time END_TIME) method to reflect the new attribute.

Implementation of viewing your Schedule

The schedule command displays of a student’s dashboard. The schedule command is implemented this way:

Figure 7. Sequence Diagram of schedule command

From the following diagram,

InfoPanel handles the showScheduleEvent event. It changes the view to the CalendarPanel, hiding DashboardPanel and BrowserPanel.
InfoPanel raises the showScheduleEvent which is also handled by CalendarPanel to display the lessons of the student in the schedule.

Design Considerations

Aspect Alternatives Pros (+)/ Cons(-)

Aspect	Alternatives	Pros (+)/ Cons(-)
Implementation of `Lesson` in `Schedule`	`Schedule` contains `Lesson` objects, schedule is made up of only one layer, with attributes directly attached to `Lesson` (current choice)	+ : It is easier implement, just add `Lesson` to a `Schedule`, which is a list of `Lessons` - : Results in more coupling, attributes could have been furthur separated out. It is inefficient to search by `Day`. Searching for empty slot requires linear searching.
`Lesson` contains two layers of classes, `Day` is attached to `Schedule` and `Lesson` is attached to `Day`	+ : Less coupling and more cohesive design - : Much harder to implement and gets overly complicated
Data structure of `Schedule`	Relational database related by a uniquekey attribute (current choice)	+ : Much better normalised design. Modifying contacts list in any way will not affect the Schedule database. - : Another layer of abstraction. Harder to implement
Adding Student objects to lessons in schedule	+ : Easier implementation. - : Changes in contacts list data will require more workarounds to modify schedule data.

Implementation of Lesson in Schedule

Schedule contains Lesson objects, schedule is made up of only one layer, with attributes directly attached to Lesson (current choice)

+ : It is easier implement, just add Lesson to a Schedule, which is a list of Lessons

- : Results in more coupling, attributes could have been furthur separated out. It is inefficient to search by Day. Searching for empty slot requires linear searching.

Lesson contains two layers of classes, Day is attached to Schedule and Lesson is attached to Day

+ : Less coupling and more cohesive design

- : Much harder to implement and gets overly complicated

Data structure of Schedule

Relational database related by a uniquekey attribute (current choice)

+ : Much better normalised design. Modifying contacts list in any way will not affect the Schedule database.

- : Another layer of abstraction. Harder to implement

Adding Student objects to lessons in schedule

+ : Easier implementation.

- : Changes in contacts list data will require more workarounds to modify schedule data.

Google Service Integration

To sync with Google Contacts and Google Calendar, a GServiceManager class is implemented to handle the 2 services. GServiceManager contains a GContactsService and GCalendarService objects. GServiceManager.synchronize calls GContactsService.synchronize and GCalendarService.synchronize

Prerequisites/Dependencies

Google Contacts and Calendar APIs require an external libaries. Remember to add the following to your dependencies

dependencies {
    compile 'com.google.api-client:google-api-client:1.23.0'
    compile 'com.google.oauth-client:google-oauth-client-jetty:1.23.0'
    compile 'com.google.apis:google-api-services-oauth2:v1-rev139-1.23.0'
    compile 'com.google.apis:google-api-services-calendar:v3-rev305-1.23.0'
    compile group: 'com.google.gdata', name: 'core', version: '1.47.1'
}

Design Considerations

Aspect Alternatives Pros (+)/ Cons(-)

Aspect	Alternatives	Pros (+)/ Cons(-)
Implementation of `GServiceManager` class	Separate out 2 Google Services into two classes (current choice)	+ : Less coupling - : More files and more code
All services are in `GServiceManager` class. Synchronize runs the upload for both Contacts and Calendar classes.	+ : Fewer files and code to read - : More coupling
Implementation of flow of data for a sync	Only Upload (current choice)	As we have to store the IDs of contacts and events created offline, that would create a massive database issue. + : Reduces the complexity of the implementation of syncing data. + - : User cannot download updated data that he synced from another Codeducator instance
Upload and download	+ : Much more convenient for the user to sync his data to the cloud. - : Much harder to implement. At every session, need to keep track of which users were edited, added or deleted (similar to a diff program)

Implementation of GServiceManager class

Separate out 2 Google Services into two classes (current choice)

+ : Less coupling

- : More files and more code

All services are in GServiceManager class. Synchronize runs the upload for both Contacts and Calendar classes.

+ : Fewer files and code to read

- : More coupling

Implementation of flow of data for a sync

Only Upload (current choice)

As we have to store the IDs of contacts and events created offline, that would create a massive database issue. + : Reduces the complexity of the implementation of syncing data.

+ - : User cannot download updated data that he synced from another Codeducator instance

Upload and download

+ : Much more convenient for the user to sync his data to the cloud.

- : Much harder to implement. At every session, need to keep track of which users were edited, added or deleted (similar to a diff program)

End of extract from [Developer Guide]