Julian Lim - Project Portfolio

PROJECT: PlanMySem

My team and I were tasked with enhancing a basic command line interface addressbook application, AddressBook Level 3, for our Software Engineering project.

We chose to morph it into a student planner called PlanMySem. This planner is made specially for NUS students and staff, containing features that will help them manage their school schedules more easily.

PlanMySem is automatically synchronised according to the current semester of the NUS academic calendar. Special weeks such as recess week and reading week are taken into account within our unique recursion system.

This allows students and staff to easily keep track of school related matters such as classes, deadlines and examinations. These activities can also be efficiently managed via the intuitive tagging system. The user can then view his schedule for the day or week (shown in the figure below), or view the current semester.

Figure 1. Example of viewing the current week

Overview

The next sections will illustrate my enhancements in more detail as well as my various contributions to the project.

Kindly take note that throughout this portfolio, there will be various icons used as described as such.

This is a tip. Follow these suggested tips to make your life much simpler when using PlanMySem!

This is a note. These are things for you to take note of when using PlanMySem.

This is a sign-post informing caution. Please take note of these items and exercise some care.

Summary of contributions

This section shows a summary of the features I have implemented in PlanMySem as well as some details regarding the implementation.

Major enhancement 1: I added the ability to import .ics files
- What it does: allows the user to import .ics files obtained from this or other applications.
  
  .ics stands for a iCalendar file format. .ics files are one of the most commonly used calendar formats in applications such as Google Calendar and Outlook.
- Justification: This feature improves the product significantly because the user can import existing appointments on other calendar applications into PlanMySem, allowing him to combine external appointments with his school schedule.
- Highlights: This enhancement works with existing as well as future commands. In particular, this enhancement works hand-in-hand with 2 features that I will go into detail later: exporting and data and encryption. An in-depth analysis of the add command was necessary to understand how slots are added into our planner as I had to add multiple slots into the planner at once.
- Code available here
Major enhancement 2: I added the ability to export .ics files
- What it does: allows the user to export .ics files from the planner ** What it does: allows the user to export .ics files from the planner
- Justification: This feature improves the product because the user can export current slots in the planner and merge them into other calendar applications. The user can also export the .ics file to be imported across devices.
- Highlights: This enhancement works with existing as well as future commands. In particular, this enhancement works hand-in-hand with the import feature described above. This allows the user to export a file that can be imported into PlanMySem on another device. This enhancement also allows the user to obtain a readable file as the data will be encrypted (discussed later).
  An in-depth analysis of how the planner stores slots was necessary in order to extract their details to be exported.
- Code available here
Minor enhancement: I added data encryption of the storage file.
- What it does: the planner automatically encrypts the data before saving it into a .txt file. This data is then decrypted before being loaded by the application.
- Justification: This feature improves the product because the user’s schedule data will not be able to easily obtained by others.
- Highlights: This enhancement works with existing as well as future commands. In particular, this enhancement works hand-in-hand with the import and export functions. As we have decided to encrypt the raw data file, the user will not be able to obtain the raw data of his planner.
  As a result, the export function allows the user to obtain a read-able text file when he wishes to.
  This enhancement also allows the user to obtain a readable file as the data will be encrypted (discussed later).
  An in-depth analysis of how the planner data is stored was necessary to identify where encryption and decryption should be done on the data. Also, a general understanding of ciphers and data encryption was necessary in implementation of this enhancement.
- Code available here
Code contributed:
- View my RepoSense contribution analysis: here
Other contributions:

Test coverage: * I wrote JUnit tests for all my features and had close to 100% coverage.
Documentation: * I wrote Use Cases on the Developer Guide: here

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.
- Data Encryption
- Importing files
- Exporting files

Encrypting/decrypting data files

Planner data is automatically encrypted before saving and decrypted before loading. You do not need to encrypt or decrypt the data manually.

Exporting .ics formatted files: `export`

You can export the planner as a .ics file. Format: export [fn/FILE_NAME]

Figure 2. Output after entering export

The default name of the exported file is "PlanMySem.ics" and is saved in the main directory. The .ics file can be imported into other calendar apps that support .ics files such as Google Calendar.

Figure 3. Location of PlanMySem.ics file

A file with the ICS file extension is an iCalendar file. These are plain text files that include calendar event details like a description, beginning and ending times, location, etc.

Importing native .ics files `import`

You can import a .ics file generated by PlanMySem into the current planner. Format: import [fn/FILE_NAME]/

This feature is to allow transfer of data between PlanMySem on different devices. This feature is NOT for importing non-native .ics files. Hence, only .ics files generated by PlanMySem should be imported.

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.
- Exporting files
- Data Encryption
- Use cases

Data Exporting / Exporting feature

This feature exports the Planner into a .ics file. This section will detail how this feature is implemented.

Current Implementation

Upon entering the export command with valid parameters (refer to UserGuide.adoc for export usage), the following sequence of events is executed:

The ParserManager parses the export command and calls the parse method in ExportCommandParser.
The ExportCommandParser then constructs a ExportCommand object with a filename.
The Command object is returned and execution will get the current Semester from Model
The IcsSemester is then constructed using Semester and converted to a String.
The String is then written to a file with the filename parsed.
The result of the command execution, CommandResult, will then returned to Ui.

Given below is the Sequence Diagram upon executing the export command.

Figure 4. Sequence of implementation for the export Command

The ExportCommandParser will check whether the optional filename parameter was input. If this parameter is included, the input filename is used. Else, if no other characters have been input (e.g. "export"), the default "PlanMySem" is used as the filename. This process can be seen from the activity diagram in the figure below.

Figure 5. Activity diagram showing the workflows for export Command

Design Considerations

This portion explains alternative implementations as well as the rationale behind my chosen method.

Aspect: Using a .ics library

Alternative 1 (current choice): Writing my own .ics file.
- Pros: No need to include and understand how to use the external library.
- Cons: Difficult to read and work with .ics formatting.
Alternative 2: Using iCal4j library to read and write .ics files.
- Pros: No need to manually format data into .ics format.
- Cons: Difficult to translate our recursion system to the .ics RRULE system.

Reason for current choice: Using the library will allow PlanMySem to easily import non-native .ics files. However, this would require changes to Model as currently the recurrence for slots is not saved.

In addition, as our application is a specially designed planner for NUS matters, I felt that it was unnecessary to have the same slots on multiple applications.

Hence, I chose to code the reading and writing of .ics files and add a disclaimer that importing of non-native .ics files is likely to cause errors.

Data Encryption / Decryption feature

The storage file "PlanMySem.txt" is encrypted to prevent easy access of the user’s calendar.

Current Implementation

We are encrypting and decrypting the data using the Java Cipher. This feature is implemented through the Encryptor that contains the encrypt and decrypt methods. The encrypt method takes a String as an argument and returns a encrypted String object. The decrypt method takes in a String object as an argument and returns the decrypted message as a String object.

The encryption is done using AES/CBC/PKCS5Padding. The key used for encryption/decryption is generated through various device parameters such as username, operating system (OS) and java runtime version. The secret key generated is stored in a file named "KeyStorage.jceks". No password is required from the user to retrieve this key, but a password input can be added to KeyStorage to improve security.

A initialization vector (IV) is required for the Cipher Block Chain (CBC) mode of encryption. A random IV is generated and appended at the beginning of the data before being stored. The IV is then retrieved from the same file to decrypt the data.

Encryption of the data is done automatically before the file is saved. In the implementation, the AdaptedPlanner is first marshaled into a StringWriter before being encrypted and written into the file. This is to ensure that the data is JAXB formatted and the save algorithm is unaffected. Similarly, decryption of the data is done automatically before it is loaded. In the implementation, the file is read and decrypted and parsed into a StringReader. The StringReader is then un-marshaled and loaded. This is to ensure that the file is converted back into a JAXB object before being loaded and the load algorithm is unaffected.

Configuration

User Preferences [COMING IN 2.0]

The files generated by PlanMySem are also named "PlanMySem" and are saved in user’s PlanMySem folder by default. This default filename and file path can be changed via the the configuration file (default: config.json).
There is no need for manual configuration of the Semester as it is initialized dynamically as mentioned in [Planner-Initialization].

Use Case: Export planner

MSS:
- 1. User inputs command to export the planner.
- 2. System converts planner to .ics format.
- 3. System saves .ics file in the main directory as "PlanMySem.ics".
- 4. System displays confirmation message.
  
  Use case ends.
Extensions:

1a. A filename is included in the command.

1ai. The filename is valid.

1ai.1. System converts planner to .ics format.

1ai.2. System saves .ics file in the respective directory.

1ai.3. System displays confirmation message.

Use case ends.

1aii. The filename is invalid

1aii.1 System outputs error message.

Use case ends.