CollegeZone - Developer Guide

By: Team T09-B2 Since: Mar 2018 Licence: MIT

1. Setting up
2. Design
3. Implementation
4. Documentation
5. Testing
6. Dev Ops
Appendix A: Product Scope
Appendix B: User Stories
Appendix C: Use Cases
Appendix D: Non Functional Requirements
Appendix E: Glossary
Appendix F: Product Survey
Appendix G: Instructions for Manual Testing

1. Setting up

1.1. Prerequisites

JDK 1.8.0_60 or later

ℹ️
Having any Java 8 version is not enough.
This app will not work with earlier versions of Java 8.
IntelliJ IDE

ℹ️
IntelliJ by default has Gradle and JavaFx plugins installed.
Do not disable them. If you have disabled them, go to File > Settings > Plugins to re-enable them.

1.2. Setting up the project in your computer

Fork this repo, and clone the fork to your computer
Open IntelliJ (if you are not in the welcome screen, click File > Close Project to close the existing project dialog first)
Set up the correct JDK version for Gradle
1. Click Configure > Project Defaults > Project Structure
2. Click New… and find the directory of the JDK
Click Import Project
Locate the build.gradle file and select it. Click OK
Click Open as Project
Click OK to accept the default settings
Open a console and run the command gradlew processResources (Mac/Linux: ./gradlew processResources). It should finish with the BUILD SUCCESSFUL message.
This will generate all resources required by the application and tests.

1.3. Verifying the setup

Run the seedu.address.MainApp and try a few commands
Run the tests to ensure they all pass.

1.4. Configurations to do before writing code

1.4.1. Configuring the coding style

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

Go to File > Settings… (Windows/Linux), or IntelliJ IDEA > Preferences… (macOS)
Select Editor > Code Style > Java
Click on the Imports tab to set the order
- For Class count to use import with '*' and Names count to use static import with '*': Set to 999 to prevent IntelliJ from contracting the import statements
- For Import Layout: The order is import static all other imports, import java.*, import javax.*, import org.*, import com.*, import all other imports. Add a <blank line> between each import

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

1.4.2. Updating documentation to match your fork

After forking the repo, links in the documentation will still point to the se-edu/addressbook-level4 repo. If you plan to develop this as a separate product (i.e. instead of contributing to the se-edu/addressbook-level4) , you should replace the URL in the variable repoURL in DeveloperGuide.adoc and UserGuide.adoc with the URL of your fork.

1.4.3. Setting up CI

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

ℹ️	Coverage reporting could be useful for a team repository that hosts the final version but it is not that useful for your personal fork.

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

ℹ️	Having both Travis and AppVeyor ensures your App works on both Unix-based platforms and Windows-based platforms (Travis is Unix-based and AppVeyor is Windows-based)

1.4.4. Getting started with coding

When you are ready to start coding,

Get some sense of the overall design by reading Section 2.1, “Architecture”.
Take a look at Appendix A, Product Scope.

2. Design

2.1. Architecture

Figure 1. Architecture Diagram

The Architecture Diagram given above explains the high-level design of the App. Given below is a quick overview of each component.

💡	The `.pptx` files used to create diagrams in this document can be found in the diagrams folder. To update a diagram, modify the diagram in the pptx file, select the objects of the diagram, and choose `Save as picture`.

Main has only one class called MainApp. It is responsible for,

At app launch: Initializes the components in the correct sequence, and connects them up with each other.
At shut down: Shuts down the components and invokes cleanup method where necessary.

Commons represents a collection of classes used by multiple other components. Two of those classes play important roles at the architecture level.

EventsCenter : This class (written using Google’s Event Bus library) is used by components to communicate with other components using events (i.e. a form of Event Driven design)
LogsCenter : Used by many classes to write log messages to the App’s log file.

The rest of the App consists of four components.

UI: The UI of the App.
Logic: The command executor.
Model: Holds the data of the App in-memory.
Storage: Reads data from, and writes data to, the hard disk.

Each of the four components

Defines its API in an interface with the same name as the Component.
Exposes its functionality using a {Component Name}Manager class.

For example, the Logic component (see the class diagram given below) defines it’s API in the Logic.java interface and exposes its functionality using the LogicManager.java class.

Figure 2. Class Diagram of the Logic Component

Events-Driven nature of the design

The Sequence Diagram below shows how the components interact for the scenario where the user issues the command delete 1.

Figure 3. Component interactions for delete 1 command (part 1)

ℹ️	Note how the `Model` simply raises a `AddressBookChangedEvent` when the Address Book data are changed, instead of asking the `Storage` to save the updates to the hard disk.

The diagram below shows how the EventsCenter reacts to that event, which eventually results in the updates being saved to the hard disk and the status bar of the UI being updated to reflect the 'Last Updated' time.

Figure 4. Component interactions for delete 1 command (part 2)

ℹ️	Note how the event is propagated through the `EventsCenter` to the `Storage` and `UI` without `Model` having to be coupled to either of them. This is an example of how this Event Driven approach helps us reduce direct coupling between components.

The sections below give more details of each component.

2.2. UI component

Figure 5. Structure of the UI Component

API : Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PersonListPanel, StatusBarFooter, CalendarPanel etc. All these, including the MainWindow, inherit from the abstract UiPart class.

The UI component uses JavaFx UI framework. The layout of these UI parts are defined in matching .fxml files that are in the src/main/resources/view folder. For example, the layout of the MainWindow is specified in MainWindow.fxml

The UI component,

Executes user commands using the Logic component.
Binds itself to some data in the Model so that the UI can auto-update when data in the Model change.
Responds to events raised from various parts of the App and updates the UI accordingly.

2.3. Logic component

Figure 6. Structure of the Logic Component

Figure 7. Structure of Commands in the Logic Component. This diagram shows finer details concerning XYZCommand and Command in Figure 6, “Structure of the Logic Component”

API : Logic.java

Logic uses the AddressBookParser class to parse the user command.
This results in a Command object which is executed by the LogicManager.
The command execution can affect the Model (e.g. adding a person) and/or raise events.
The result of the command execution is encapsulated as a CommandResult object which is passed back to the Ui.

Given below is the Sequence Diagram for interactions within the Logic component for the execute("delete 1") API call.

Figure 8. Interactions Inside the Logic Component for the delete 1 Command

2.4. Model component

Figure 9. Structure of the Model Component

API : Model.java

The Model,

stores a UserPref object that represents the user’s preferences.
stores the Address Book data.
exposes an unmodifiable ObservableList<Person> that can be 'observed' e.g. the UI can be bound to this list so that the UI automatically updates when the data in the list change.
does not depend on any of the other three components.

2.5. Storage component

Figure 10. Structure of the Storage Component

API : Storage.java

The Storage component,

can save UserPref objects in json format and read it back.
can save the Address Book data in xml format and read it back.

2.6. Common classes

Classes used by multiple components are in the seedu.addressbook.commons package.

3. Implementation

This section describes some noteworthy details on how certain features are implemented.

3.1. Undo/Redo feature

3.1.1. Current Implementation

The undo/redo mechanism is facilitated by an UndoRedoStack, which resides inside LogicManager. It supports undoing and redoing of commands that modifies the state of the address book (e.g. add, edit). Such commands will inherit from UndoableCommand.

UndoRedoStack only deals with UndoableCommands. Commands that cannot be undone will inherit from Command instead. The following diagram shows the inheritance diagram for commands:

Figure 11. Structure of Logic Command

As you can see from the diagram, UndoableCommand adds an extra layer between the abstract Command class and concrete commands that can be undone, such as the DeleteCommand. Note that extra tasks need to be done when executing a command in an undoable way, such as saving the state of the address book before execution. UndoableCommand contains the high-level algorithm for those extra tasks while the child classes implements the details of how to execute the specific command. Note that this technique of putting the high-level algorithm in the parent class and lower-level steps of the algorithm in child classes is also known as the template pattern.

Commands that are not undoable are implemented this way:

public class ListCommand extends Command {
    @Override
    public CommandResult execute() {
        // ... list logic ...
    }
}

With the extra layer, the commands that are undoable are implemented this way:

public abstract class UndoableCommand extends Command {
    @Override
    public CommandResult execute() {
        // ... undo logic ...

        executeUndoableCommand();
    }
}

public class DeleteCommand extends UndoableCommand {
    @Override
    public CommandResult executeUndoableCommand() {
        // ... delete logic ...
    }
}

Suppose that the user has just launched the application. The UndoRedoStack will be empty at the beginning.

The user executes a new UndoableCommand, delete 5, to delete the 5th person in the address book. The current state of the address book is saved before the delete 5 command executes. The delete 5 command will then be pushed onto the undoStack (the current state is saved together with the command).

Figure 12. Initial UndoRedoStack

As the user continues to use the program, more commands are added into the undoStack. For example, the user may execute add n/David … to add a new person.

Figure 13. UndoRedoStack given new command input

ℹ️	If a command fails its execution, it will not be pushed to the `UndoRedoStack` at all.

The user now decides that adding the person was a mistake, and decides to undo that action using undo.

We will pop the most recent command out of the undoStack and push it back to the redoStack. We will restore the address book to the state before the add command executed.

Figure 14. Undo command on UndoRedoStack

ℹ️	If the `undoStack` is empty, then there are no other commands left to be undone, and an `Exception` will be thrown when popping the `undoStack`.

The following sequence diagram shows how the undo operation works:

Figure 15. Sequence diagram for undo

The redo does the exact opposite (pops from redoStack, push to undoStack, and restores the address book to the state after the command is executed).

ℹ️	If the `redoStack` is empty, then there are no other commands left to be redone, and an `Exception` will be thrown when popping the `redoStack`.

The user now decides to execute a new command, clear. As before, clear will be pushed into the undoStack. This time the redoStack is no longer empty. It will be purged as it no longer make sense to redo the add n/David command (this is the behavior that most modern desktop applications follow).

Figure 16. UndoRedoStack given command clear

Commands that are not undoable are not added into the undoStack. For example, list, which inherits from Command rather than UndoableCommand, will not be added after execution:

Figure 17. UndoRedoStack given command list

The following activity diagram summarize what happens inside the UndoRedoStack when a user executes a new command:

Figure 18. Activity diagram of UndoRedoStack

3.1.2. Design Considerations

Aspect: Implementation of `UndoableCommand`

Alternative 1 (current choice): Add a new abstract method executeUndoableCommand()
- Pros: We will not lose any undone/redone functionality as it is now part of the default behaviour. Classes that deal with Command do not have to know that executeUndoableCommand() exist.
- Cons: Hard for new developers to understand the template pattern.
Alternative 2: Just override execute()
- Pros: Does not involve the template pattern, easier for new developers to understand.
- Cons: Classes that inherit from UndoableCommand must remember to call super.execute(), or lose the ability to undo/redo.

Aspect: How undo & redo executes

Alternative 1 (current choice): Saves the entire CollegeZone.
- Pros: Easy to implement.
- Cons: May have performance issues in terms of memory usage.
Alternative 2: Individual command knows how to undo/redo by itself.
- Pros: Will use less memory (e.g. for delete, just save the person being deleted).
- Cons: We must ensure that the implementation of each individual command are correct.

Aspect: Type of commands that can be undone/redone

Alternative 1 (current choice): Only include commands that modifies the CollegeZone (add, clear, edit).
- Pros: We only revert changes that are hard to change back (the view can easily be re-modified as no data are * lost).
- Cons: User might think that undo also applies when the list is modified (undoing filtering for example), * only to realize that it does not do that, after executing undo.
Alternative 2: Include all commands.
- Pros: Might be more intuitive for the user.
- Cons: User have no way of skipping such commands if he or she just want to reset the state of the address * book and not the view. Additional Info: See our discussion here.

Aspect: Data structure to support the undo/redo commands

Alternative 1 (current choice): Use separate stack for undo and redo
- Pros: Easy to understand for new Computer Science student undergraduates to understand, who are likely to be * the new incoming developers of our project.
- Cons: Logic is duplicated twice. For example, when a new command is executed, we must remember to update * both HistoryManager and UndoRedoStack.
Alternative 2: Use HistoryManager for undo/redo
- Pros: We do not need to maintain a separate stack, and just reuse what is already in the codebase.
- Cons: Requires dealing with commands that have already been undone: We must remember to skip these commands. Violates Single Responsibility Principle and Separation of Concerns as HistoryManager now needs to do two * different things.

3.2. [Proposed] Data Encryption

{Explain here how the data encryption feature will be implemented}

3.3. Logging

We are using java.util.logging package for logging. The LogsCenter class is used to manage the logging levels and logging destinations.

The logging level can be controlled using the logLevel setting in the configuration file (See Section 3.4, “Configuration”)
The Logger for a class can be obtained using LogsCenter.getLogger(Class) which will log messages according to the specified logging level
Currently log messages are output through: Console and to a .log file.

Logging Levels

SEVERE : Critical problem detected which may possibly cause the termination of the application
WARNING : Can continue, but with caution
INFO : Information showing the noteworthy actions by the App
FINE : Details that is not usually noteworthy but may be useful in debugging e.g. print the actual list instead of just its size

3.4. Configuration

Certain properties of the application can be controlled (e.g App name, logging level) through the configuration file (default: config.json).

3.5. Enhanced Find Command [Since v1.1]

The old find command feature only allows searching by name. To make CollegeZone more useful for RC4 students, we have enhanced the find command feature to be able to find persons by tags.

3.5.1. Aspect: User Input

Old user input format: find <name>
New user input format: find n/<name> t/<tag>

3.5.2. Aspect: Nature of user input

Searching of name and tag at the same time is not allowed
If user is searching by name, user input should be: find n/<name> t/<empty>
If user is searching by tags, user input should be: find n/<empty> t/<tag>

3.6. Command Aliases [Since v1.1]

CollegeZone users may now use shortcuts to perform desired tasks. These shortcuts are shown in the table below.

Command	Original	Alias
Add	add	a
Clear	clear	c
Delete	delete	d
Edit	edit	e
Find	find	f
History	history	h
List	list	l
Rate	rate	rt
Redo	redo	r
Seek	seek	sk
Select	select	s
Show	show	sh
Undo	undo	u
Meet	meet	m

3.7. Targeted add and edit command [Since v1.2]

As CollegeZone is designed for NUS RC4 students to use, being able to record other students Level of Friendship, Birthday, RC4 Unit Number and RC4 CCAs, will be a useful feature for them.

As CollegeZone is catered toward NUS RC4 Residents, we have changed the attributes of a Person to hold:
Name, Mobile Number, Birthday, Level of Friendship, RC4 Unit Number, Meet up dates with RC4 students, RC4 CCAs and Tags.
This is done by removing unwanted attributes of a person and adding new attributes of a person.
The figure below shows the new atrributes for student in the class diagram.

Figure 19. Class diagram for Student

3.7.1. Design Considerations

Aspect: Displaying level of friendship in CollegeZone UI.

Alternative 1(current choice): Level of Friendship is displayed as a string of heart symbols.
Pros: Looks fanciful to user.
Cons: Might not be intuitive for the user to understand the meaning of heart symbols.

Alternative 2: Level of Friendship is displayed as a number. +
Pros: User easily understands the meaning of it.
Cons: Less eye catching to the user.

3.8. Reminders [Since v1.4]

3.8.1. Introduction

RC4 students will have a very busy schedule that consists of tasks, events & activities.
Hence, we decided on implementing a reminder feature to allow them to add & delete reminders in CollegeZone to assist them in organising their schedule.

The AddReminderCommand allows you to add a Reminder into CollegeZone and is stored in an ArrayList, UniqueReminderList, in AddressBook. The DeleteReminderCommand allows you to delete a Reminder from CollegeZone.

Reminder commands are undoable and redoable for the benefit users to redo and undo a command they did or did not intend to change.
Hence, both AddReminderCommand and DeleteReminderCommand are implemented as UndoableCommand.

Reminder Features:

Adding a reminder to the Calendar: The AddReminderCommand allows you to add a Reminder into CollegeZone and is stored in an ArrayList, UniqueReminderList, in AddressBook.
Deleting a reminder on the Calendar: The DeleteReminderCommand allows you to delete a Reminder from UniqueReminderList, in AddressBook.

Reminder commands are undoable and redoable for the benefit users to redo and undo a command they did or did not intend to change. Hence, both AddReminderCommand and DeleteReminderCommand are implemented as UndoableCommand.

3.8.2. Implementation

Model Component

Reminder Class

Every time a Reminder is created, three other objects are also created:

ReminderText: This object contains a single string variable, reminderText, that is verified to contain characters and spaces and cannot be blank.
DateTime: This object contains a single string variable, dateTime. After obtaining the start date time from user input, it will parse through nattyDateAndTimeParser to convert it to a LocalDateTime variable. Subsequently, this LocalDateTime variable will then be converted back to a string variable using properReminderDateTimeFormat and it stored as dateTime in DateTime object.
EndDateTime: This object contains a single string variable, dateTime. After obtaining the end date time from user input, it will parse through nattyDateAndTimeParser to convert it to a LocalDateTime variable. Subsequently, this LocalDateTime variable will then be converted back to a string variable using properReminderDateTimeFormat and it stored as dateTime in DateTime object.

A Reminder will be marked with a blue circle if it’s not due and be marked with a red circle if it’s due.

Users can delete reminders on the Calendar if its already due or when they accidentally made a mistake.

Figure 20. Class Diagram of Reminder

UniqueReminderList

UniqueReminderList functions as a List of Reminders where every element is unique and is defined by its ReminderText, DateTime and EndDateTime.

Logic Component

Adding a Reminder

When AddReminderCommand is executed, it first checks whether there are any duplicate reminders in UniqueReminderList. If there is no duplicate reminder, Reminder is added into UniqueReminderList in AddressBook.

Figure 21. Interactions Inside the Logic Component for the +r text/eat pills d/tmr 8pm e/tmr 10pm Command

Deleting a Reminder

When DeleteReminderCommand is executed, it will find the Reminder specified by the user using parameters ReminderText and DateTime. If Reminder specified by user is not found in UniqueReminderList, CommandException will be thrown. If Reminder is found, it will then be removed from UniqueReminderList. The code snippet to find and remove the Reminder specified by user is shown below. Code snippet of this is shown in Code Snippet 3.9.1.

Figure 22. Interactions Inside the Logic Component for the -r text/eat pills d/tmr 8pm Command

@Override
    protected void preprocessUndoableCommand() throws CommandException {
        model.updateFilteredReminderList(predicate);
        List<Reminder> lastShownList = model.getFilteredReminderList();
        targetIndex = Index.fromOneBased(1);
        if (lastShownList.size() > 1) {
            for (Reminder reminder : lastShownList) {
                if (reminder.getDateTime().toString().equals(dateTime)) {
                    reminderToDelete = reminder;
                }
            }
        } else {
            if (targetIndex.getZeroBased() >= lastShownList.size()) {
                throw new CommandException(Messages.MESSAGE_INVALID_REMINDER_TEXT_DATE);
            }

            reminderToDelete = lastShownList.get(targetIndex.getZeroBased());
        }
    }

Code Snippet 3.9.1: Method to find specific Reminder to delete

User Interface(Syncing Calendar to Reminders)

To display the reminder in the calendar, we have a CalendarPanel that takes in the UniqueReminderList.

    public CalendarPanel(ObservableList<Reminder> reminderList, ObservableList<Person> personList) {
        super(FXML);

        this.reminderList = reminderList;
        this.personList = personList;

        calendarView = new CalendarView();
        setupCalendar();
        updateCalendar();
        registerAsAnEventHandler(this);
    }

Code Snippet 3.9.2: Inititialisation of Calendar Panel for User Interface

UniqueReminderList will then be iterated and each reminder in the list is individually added into the calendar through updateCalendar(). Every time a new reminder is added into CollegeZone, an event handler, handleNewCalendarEvent, will cause calendarUpdate() to run again and CalendarPanel will be updated to display the new reminder added onto CollegeZone.

    @Subscribe
    private void handleNewCalendarEvent(AddressBookChangedEvent event) {
        reminderList = event.data.getReminderList();
        personList = event.data.getPersonList();
        Platform.runLater(this::updateCalendar);
    }

Code Snippet 3.9.3: Event Handler: handleNewCalendarEvent

    /**
     * Updates the Calendar with Reminders that are already added
     */
    private void updateCalendar() {
        setDateAndTime();
        CalendarSource myCalendarSource = new CalendarSource("Reminders and Meetups");
        Calendar calendarRDue = new Calendar("Reminders Already Due");
        Calendar calendarRNotDue = new Calendar("Reminders Not Due");
        Calendar calendarM = new Calendar("Meetups");
        calendarRDue.setStyle(Calendar.Style.getStyle(4));
        calendarRDue.setLookAheadDuration(Duration.ofDays(365));
        calendarRNotDue.setStyle(Calendar.Style.getStyle(1));
        calendarRNotDue.setLookAheadDuration(Duration.ofDays(365));
        calendarM.setStyle(Calendar.Style.getStyle(3));
        myCalendarSource.getCalendars().add(calendarRDue);
        myCalendarSource.getCalendars().add(calendarRNotDue);
        myCalendarSource.getCalendars().add(calendarM);
        for (Reminder reminder : reminderList) {
            LocalDateTime ldtstart = nattyDateAndTimeParser(reminder.getDateTime().toString()).get();
            LocalDateTime ldtend = nattyDateAndTimeParser(reminder.getEndDateTime().toString()).get();
            LocalDateTime now = LocalDateTime.now();
            if (now.isBefore(ldtend)) {
                calendarRNotDue.addEntry(new Entry(
                        reminder.getReminderText().toString(), new Interval(ldtstart, ldtend)));
            } else {
                calendarRDue.addEntry(new Entry(reminder.getReminderText().toString(), new Interval(ldtstart, ldtend)));
            }
        }
        calendarView.getCalendarSources().add(myCalendarSource);
    }

Code Snippet 3.9.4: updateCalendar() method

When a reminder is deleted, it will go through the same process as adding reminder and the changes will then be updated in the calendar.

3.8.3. Design Considerations

Aspect: Deleting a Reminder from CollegeZone.

Alternative 1: Delete Reminder using an index which is the index of the particular Reminder in UniqueReminderList
Pros: Implementing DeleteReminderCommand by parsing an index will be simple as DeleteCommand to delete a person from AddressBook is using a similar implementation.
Cons: We will have to first implement a list function to list all reminders with their respective indexes, which may be undesirable as there may be a large number of reminders to be listed out. This will in turn require the need of a find function to find a specific reminder that the users want to delete.

Alternative 2(current choice): Delete Reminder identified by ReminderText and DateTime.
Pros: Reduces the need of a listing and finding function to delete a Reminder from CollegeZone.
Cons: Implementation of DeleteReminderCommand will be more difficult as we will have to integrate a find function to pick out the specific Reminder that the user wants to remove.

3.9. Goal Object [Since v1.2]

CollegeZone is designed for RC4 students to use. RC4 students often have goals that they want to achieve in life – Career goals, health goals, social goals, relationship goals etc. This additional goal feature is created for RC4 users to add and keep track of their goals throughout their stay. The main reason behind this implementation is because setting goals gives you long-term vision and short-term motivation for the goals. This implementation allows RC4 students to set goals in CollegeZone – big or small ones - so that they will be reminded of the goals that they have set for themselves.

Goal features:

 1. add goal
 2. edit goal
 3. delete goal
 4. complete goal
 5. ongoing goal
 6. sort goal

3.9.1. Implementation of Goal Object

Goal objects consists of 5 attributes :

Date and time of when goal is completed.
Level of importance of goal.
Text content of Goal.
Date and time of Goal of when goal has started.
Goal completion status.

Figure 23. Class diagram of Goal

The code snippet shown below shows the overloading of StartDateTime constructor class. It keeps both a String value and a LocalDateTime value. The Code-snippet 2 and 3 shows the conversion of the String value to LocalDateTime value and vice versa.

public class StartDateTime implements Comparable<StartDateTime> {

    public final String value;
    public final LocalDateTime localDateTimeValue;

    public StartDateTime(LocalDateTime startDateTime) {
        requireNonNull(startDateTime);
        this.localDateTimeValue = startDateTime;
        this.value = properDateTimeFormat(startDateTime);
    }

    public StartDateTime(String startDateTimeInString) {
        requireNonNull(startDateTimeInString);
        this.value = startDateTimeInString;
        this.localDateTimeValue = getLocalDateTimeFromProperDateTime(startDateTimeInString);
    }
}

Code Snippet 3.10.1: StartDateTime method

    public static String properDateTimeFormat(LocalDateTime dateTime) {
        StringBuilder builder = new StringBuilder();
        int day = dateTime.getDayOfMonth();
        String month = dateTime.getMonth().getDisplayName(TextStyle.FULL, Locale.ENGLISH);
        int year = dateTime.getYear();
        int hour = dateTime.getHour();
        int minute = dateTime.getMinute();
        builder.append("Date: ")
                .append(day)
                .append(" ")
                .append(month)
                .append(" ")
                .append(year)
                .append(",  Time: ")
                .append(String.format("%02d", hour))
                .append(":")
                .append(String.format("%02d", minute));
        return builder.toString();
    }

Code Snippet 3.10.2: Method conversion

    public static LocalDateTime getLocalDateTimeFromProperDateTime(String properDateTimeString) {
        String trimmedArgs = properDateTimeString.trim();
        int size = trimmedArgs.length();
        String stringFormat = properDateTimeString.substring(BEGIN_INDEX, size);
        stringFormat = stringFormat.replace(", Time: ", "");
        return nattyDateAndTimeParser(stringFormat).get();
    }

Code Snippet 3.10.3: Method conversion

All goals will have a string of stars (indicating importance) in a yellow border directly below the goal text in the goal list panel.

3.9.2. Design Considerations

Aspect: Representation of Goals level of importance in UI
Alternative 1 (current choice): Each level of importance have a number of stars related to it.
Pros: Ability for the user to differentiate the Goals with higher level of importance compared to those with lower level of importance.
Cons: The goal list in the UI might look messy to the user without having a sort Goals option as the list of goals is displayed based on when it was added.
Alternative 2: Having an additional sort goal command
Pros: It is simple and easy to understand.
Cons: It requires extra methods to implement the sort function.

3.10. Add goal mechanism [Since v1.3]

Adding a goal into CollegeZone is facilitated by AddGoalCommand, which extends UndoableCommand, it supports undoing and redoing of commands that modifies the state of the CollegeZone.

public class AddGoalCommand extends UndoableCommand {
@Override
    public CommandResult executeUndoableCommand() throws CommandException {
        // ... AddGoalCommand logic ...
    }
}

The following sequence diagram shows the flow of operation from the point CollegeZone receives an input to the output of the result.

Figure 24. Interactions Inside the Logic Component for the +g Command

AddGoalCommand is implemented in this way:

In the Logic component, AddressBookParser will parse the user’s input and detects if add goal keyword contains correct parsing keywords after. For example, e.g. +g text/eat healthily impt/9 AddGoalCommandParser parses the input by extracting the input text and importance,
e.g.Parsed text : eat healthily
Parsed importance : 9
Everytime a goal is added, the start date time of the goal will be recorded down in real time and it’s completion status will be "ongoing" by default. AddGoalCommandParser is implemented in this way:

public class AddGoalCommandParser implements Parser<AddGoalCommand> {

    public static final String EMPTY_END_DATE_TIME = "";
    public static final boolean INITIAL_COMPLETION_STATUS = false;

    public AddGoalCommand parse(String args) throws ParseException {
        ArgumentMultimap argMultimap =
                ArgumentTokenizer.tokenize(args, PREFIX_IMPORTANCE, PREFIX_GOAL_TEXT);

        if (!arePrefixesPresent(argMultimap, PREFIX_IMPORTANCE, PREFIX_GOAL_TEXT)
                || !argMultimap.getPreamble().isEmpty()) {
            throw new ParseException(String.format(MESSAGE_INVALID_COMMAND_FORMAT, AddGoalCommand.MESSAGE_USAGE));
        }
        try {
            Importance importance = ParserUtil.parseImportance(argMultimap.getValue(PREFIX_IMPORTANCE)).get();
            GoalText goalText = ParserUtil.parseGoalText(argMultimap.getValue(PREFIX_GOAL_TEXT)).get();
            StartDateTime startDateTime = new StartDateTime(LocalDateTime.now());
            EndDateTime endDateTime = new EndDateTime(EMPTY_END_DATE_TIME);
            Completion completion = new Completion(INITIAL_COMPLETION_STATUS);
            Goal goal = new Goal(importance, goalText, startDateTime, endDateTime, completion);
            return new AddGoalCommand(goal);
        } catch (IllegalValueException ive) {
            throw new ParseException(ive.getMessage(), ive);
        }
    }
}

The AddGoalCommandParser returns AddGoalCommand after execution, passes the text and importance and string as arguments which will be further processed by logic component. AddGoalCommand adds the new goal to the list locally and runs the execution which calls the model. In the Model component, the UniqueGoalList is called and the new goal is added to the list. In the Ui component, the new goal added is displayed in the goal list panel. In the Storage component, the new goal added is stored in the address book storage

Note: - A goal that has just been added will be placed at the bottom of the goal list.

3.10.1. Design Considerations

Aspect: Implementation of adding start date time and completion status of goal
Alternative 1 (current choice): Having the current date time as the start date time and having a default completion status of a goal added.
Pros: User have lesser words to input in the command box.
Cons: User might have a preferred start date time and completion status of the goal that they just added.
Alternative 2: Giving user a choice of start date time input and completion status of goal added.
Pros: Allows user to choose their own start date time and completion status.
Cons: Tedious for user to input a longer add goal command and slightly more difficult to properly parse the start date time that user enters.

Aspect: Representation of Goals in UI
Alternative 1 (current choice): Having a goal list panel beside our current person list panel.
Pros: Ability for the user to differentiate the Goals with higher level of importance compared to those with lower level of importance.
Cons: The initial space in UI reserved for person list is not being used to display 2 lists, the person list and the goal list. This causes the UI to look clunky and overwhelming.
Alternative 2: Having a tab button in CollegeZone that allows user to switch between the person list panel and goal list panel.
Pros: Ability for user to switch to person list and goal list in the UI, which makes it look more user friendly.
Cons: As CollegeZone is a desktop application that has most interactions happen using a Command Line Interface (CLI), a new command to switch tabs between goal list and person list needs to be implemented.

3.11. Delete goal mechanism [Since v1.4]

Deleting a goal from CollegeZone is facilitated by DeleteGoalCommand, which extends UndoableCommand, it supports undoing and redoing of commands that modifies the state of the CollegeZone.

public class DeleteGoalCommand extends UndoableCommand {
@Override
    public CommandResult executeUndoableCommand() throws CommandException {
        // ... DeleteGoalCommand logic ...
    }
}

DeleteGoalCommand is implemented in this way:

In the Logic component, AddressBookParser will parse the user’s input, for example, -goal 1 and detects the INDEX given by the user . DeleteGoalCommandParser parses the INDEX:
e.g.Parsed index : 1

Figure 25. Interactions Inside the Logic Component for the -goal Command

DeleteGoalCommandParser creates a DeleteGoalCommand class and passes the index as argument. It deletes the goal corresponding to the index locally and runs the execution which calls the model The filtered goals list and deletion of the specified Goal object occurs. The filtered goals list is updated and retrieved. The UI component displays the deletion of goal in the goal list panel and the storage component deletes the details of the deleted goal in the address book storage.

3.11.1. Design Considerations

Aspect: Deciding the field for user to enter to delete the goal
Alternative 1 (current choice): Using INDEX of goals in goal list panel
Pros: Easier to implement as it’s implementation is similar to deleting a student and easier for the user to type in the command as INDEX is an integer
Cons: User might get confused as we have 2 list panels with INDEX
Alternative 2: Using GOAL_TEXT of goals in goal list panel
Pros: Lower chance for user to use delete goal command wrongly
Cons: User have to type in a longer command

3.12. Sort goal mechanism [Since v1.5]

The sorting goal mechanism is facilitated by SortGoalCommandParser and SortGoalCommand, with both classes residing in the Logic component of CollegeZone. SortGoalCommand in not undoable.

SortGoalCommandParser takes in an arguments in the form of FIELD and ORDER that defines how UniqueGoalList should be sorted. You may customise the sort goal operation, with FIELD specifying the goal field to sort and ORDER specifying the type of sort order. It checks for validity against a few keywords. For example, ORDER only accepts 2 keywords: ascending or descending. On the other hand, FIELD only accepts 3 keywords: importance, startdatetime and completion.

The image below shows the interaction of sort the Logic component.

Figure 26. Interactions Inside the Logic Component for the sortgoal importance o/ascending Command

Upon execution of SortGoalCommand, a Comparator<Goal> will be initialised based on the sort type it receives. A sortGoal function call will be made to Model, which propagates down to UniqueGoalList, where the sorting of the internalList occurs.
The code below shows the switch statement used to define the type of sort the user wants in the UniqueGoalList.

public class UniqueGoalList implements Iterable<Goal> {

    public void sortGoal(String sortField, String sortOrder) throws EmptyGoalListException {
        String sortFieldAndOrder = sortField + " " + sortOrder;
        //Comparator<Goal> comparatorImportance = Comparator.comparingInt(Goal::getImportance);
        switch (sortFieldAndOrder) {
        case "importance ascending":
            FXCollections.sort(internalList, (Goal goalA, Goal goalB) ->goalA.getImportance()
                    .compareTo(goalB.getImportance()));
            break;
        case "importance descending":
            FXCollections.sort(internalList, (Goal goalA, Goal goalB) ->goalB.getImportance()
                    .compareTo(goalA.getImportance()));
            break;
        case "completion ascending":
            FXCollections.sort(internalList, (Goal goalA, Goal goalB) -> new Boolean(goalA.getCompletion().hasCompleted)
                    .compareTo(goalB.getCompletion().hasCompleted));
            break;
        case "completion descending":
            FXCollections.sort(internalList, (Goal goalA, Goal goalB) -> new Boolean(goalB.getCompletion().hasCompleted)
                    .compareTo(goalA.getCompletion().hasCompleted));
            break;
        case "startdatetime ascending":
            FXCollections.sort(internalList, (Goal goalA, Goal goalB) ->goalA.getStartDateTime()
                    .compareTo(goalB.getStartDateTime()));
            break;
        case "startdatetime descending":
            FXCollections.sort(internalList, (Goal goalA, Goal goalB) ->goalB.getStartDateTime()
                    .compareTo(goalA.getStartDateTime()));
            break;

        default:
            break;
        }
    }
}

Once verified, the argument will be tokenized to identify your specified sort type. A SortGoalCommand object is then created with the identified sort type.

ℹ️	If the goal list is found to be empty, a `CommandException` will be thrown from `SortGoalCommand`.

3.12.1. Design Considerations

Aspect: Deciding the fields and orders that the goal list can be sorted
Alternative 1: Sort only one field and in one order
Pros: Sort becomes a more intuitive command for user to type
Cons: Less customization of sort goal command.
Alternative 2 (current choice): Sort in multiple fields and two orders
Pros: More customization for user
Cons: User have to type in a longer command

Aspect: Initialising of Comparator<Goal>
Alternative 1: Initialise in SortGoalCommand
Pros: Clear separation of concerns, SortGoalCommandParser to handle identifying of attribute to sort by only.
Cons: Hard for new developers to follow as other commands like AddGoalCommand handles object creation in its parser.
Alternative 2 (current choice): Initialise in UniqueGoalList
Pros: Straightforward as initialises the Comparator where it is used.
Cons: UniquePersonList is at a lower level and should only handle a minimal set of Goal related operations, and not logical operations like string matching.

3.13. Switching theme mechanism [Since v1.5]

CollegeZone has multiple themes for the user to choose from. Currently, there are 3 themes implemented. Namely, dark theme, bubblegum theme and light theme. This command is not undoable.

The switch theme mechanism is facilitated by ThemeCommandParser and ThemeCommand, with both classes residing in the Logic component of CollegeZone. ThemeCommand in not undoable.

ThemeCommandParser takes in an argument in the form of THEME_COLOUR that defines the theme colour of what CollegeZone will be. You may customise the theme colour you want out of the 3 that we have. It checks for validity against a few keywords. THEME_COLOUR only accepts 3 keywords: light, dark or bubblegum.

ThemeCommandParser returns a new ThemeCommand object. ThemeCommand then executes the new event change by calling ThemeSwitchRequestEvent. The updating of theme colour will be done by handleChangeThemeEvent method.
The following code snippet shows how the theme switch event is handled.

@Subscribe
private void handleChangeThemeEvent(ThemeSwitchRequestEvent event) {
    themeColour = event.themeToChangeTo;
    Platform.runLater(
            this::changeThemeColour
    );
}

3.13.1. Design Considerations

Aspect: Storing user choice of theme
Alternative 1 (current choice): User prefs will be set to dark theme colour by default
Pros: Lesser coding required as there’s no need to store theme colour as a part of the model component
Cons: CollegeZone does not remember user’s preferred theme upon restarting CollegeZone
Alternative 2 (current choice): Initialising in UserPref
Pros: CollegeZone will remember user’s preferred theme upon restarting CollegeZone
Cons: More coding required to store theme colour

3.14. Meet Command [Since v1.2]

The new meet up command was implemented specifically to provide a platform in CollegeZone for RC4 students to set up meetings with other students with ease.

Meet Command Features:
The MeetCommand allows you to add a MeetDate into CollegeZone and is stored as a attribute of the Person class of UniquePersonList, in AddressBook. The DeleteMeetCommand allows you to delete a MeetDate from CollegeZone. The MeetDate of the Person you deleted is set to an empty string.

Meet commands are undoable and redoable for the benefit of RC4 Students to redo and undo a command they did or did not intend to change.
Hence, both MeetCommand and DeleteMeetCommand are implemented as UndoableCommand.

3.14.1. Implementation

Meet Object

Every time a User sets up a meet up with someone else:

Meet: This object contains a single string variable, meetDate, that is verified to be a valid date of the format DD/MM/YYYY. This is format is enforced to ensure user ease of usage.
Person: The Meet Attribute that is a part of the Person attribute is then updated with the relevant meetDate

Users can delete meet ups on the Calendar if its already due or when they accidentally made a mistake.

Adding a Meet up date

When Meet Command is executed, it first preprocesses the data to check whether the Person you are meeting is a valid Person and also not a duplicate Person. If there is no DuplicatePersonException and PersonNotFoundException, then Person class is updated with the meetDate in the UniquePersonList.

Deleting a Meet up

When DeleteMeetCommand is executed, it will first find the Person specified by the user using the Person Index attribute. If Person Index specified by user is not found in UniquePersonList, PersonNotFoundException will be thrown. If Person is found, his/her "meetDate" attribute will then be removed from. The code snippet to find and remove the Meet Date specified by user is shown below.

 protected void preprocessUndoableCommand() throws CommandException {
        List<Person> lastShownList = model.getFilteredPersonList();

        if (targetIndex.getZeroBased() >= lastShownList.size()) {
            throw new CommandException(Messages.MESSAGE_INVALID_PERSON_DISPLAYED_INDEX);
        }

        personToDelete = lastShownList.get(targetIndex.getZeroBased());
    }

Syncing Meet ups to Calendar

To display the meet ups in the calendar, we have a CalendarPanel that takes in the UniquePersonList.

    public CalendarPanel(ObservableList<Reminder> reminderList, ObservableList<Person> personList) {
        super(FXML);

        this.reminderList = reminderList;
        this.personList = personList;

        calendarView = new CalendarView();
        setupCalendar();
        updateCalendar();
        registerAsAnEventHandler(this);
    }

UniquePersonList will then be iterated and each person with a valid meet up date in the list is individually added into the calendar through updateCalendar(). Every time any Person is updated with a new meet up date in CollegeZone, an event handler, handleNewCalendarEvent, will cause calendarUpdate() to run again and CalendarPanel will be updated to display the Person and his meetDate.

    @Subscribe
    private void handleNewCalendarEvent(AddressBookChangedEvent event) {
        reminderList = event.data.getReminderList();
        personList = event.data.getPersonList();
        Platform.runLater(this::updateCalendar);
    }

    /**
     * Updates the Calendar with Reminders that are already added
     */
    private void updateCalendar() {
        setDateAndTime();
        CalendarSource myCalendarSource = new CalendarSource("Reminders and Meetups");
        Calendar calendarRDue = new Calendar("Reminders Already Due");
        Calendar calendarRNotDue = new Calendar("Reminders Not Due");
        Calendar calendarM = new Calendar("Meetups");
        calendarRDue.setStyle(Calendar.Style.getStyle(4));
        calendarRDue.setLookAheadDuration(Duration.ofDays(365));
        calendarRNotDue.setStyle(Calendar.Style.getStyle(1));
        calendarRNotDue.setLookAheadDuration(Duration.ofDays(365));
        calendarM.setStyle(Calendar.Style.getStyle(3));
        myCalendarSource.getCalendars().add(calendarRDue);
        myCalendarSource.getCalendars().add(calendarRNotDue);
        myCalendarSource.getCalendars().add(calendarM);
        for (Reminder reminder : reminderList) {
            LocalDateTime ldtstart = nattyDateAndTimeParser(reminder.getDateTime().toString()).get();
            LocalDateTime ldtend = nattyDateAndTimeParser(reminder.getEndDateTime().toString()).get();
            LocalDateTime now = LocalDateTime.now();
            if (now.isBefore(ldtend)) {
                calendarRNotDue.addEntry(new Entry(
                        reminder.getReminderText().toString(), new Interval(ldtstart, ldtend)));
            } else {
                calendarRDue.addEntry(new Entry(reminder.getReminderText().toString(), new Interval(ldtstart, ldtend)));
            }
        }
        //@@author sham-sheer
        for (Person person : personList) {
            String meetDate = person.getMeetDate().toString();
            if (!meetDate.isEmpty()) {
                int day = Integer.parseInt(meetDate.substring(0,
                        2));
                int month = Integer.parseInt(meetDate.substring(3,
                        5));
                int year = Integer.parseInt(meetDate.substring(6,
                        10));
                calendarM.addEntry(new Entry("Meeting " + person.getName().toString(),
                        new Interval(LocalDate.of(year, month, day), LocalTime.of(12, 0),
                                LocalDate.of(year, month, day), LocalTime.of(13, 0))));
            }
        }
        calendarView.getCalendarSources().add(myCalendarSource);
    }

When a meet date is deleted, it will go through the same process as adding meet up dates and the changes will then be updated in the calendar.

3.14.2. Design Considerations

Aspect: Deleting a meetDate from CollegeZone.

Alternative 1(current choice): Delete meetDate using an index which is the index of the particular Person in UniquePersonList
Pros: Implementing DeleteReminderCommand by parsing an index will be simple and fast. With no need for parsing of data.
Cons: When your addressbook gets too large, using indexes to delete meet ups will not be a scalable option as people cant remember the individual Indexes relates to a Person.

Alternative 2: Delete meetDate identified by Date or Person.
Pros: Reduces the need of a listing and finding function to delete a meetDate from CollegeZone.
Cons: Implementation of DeleteReminderCommand will be more difficult as we will have to integrate a find function to pick out the specific meetDates or 'Person' that the user wants to remove.

3.15. Sort Command [Since v1.4]

The Sort Command is facilitated by SortCommandParser and SortCommand, with both classes residing in the Logic component of the address book. Since the address book state will be modified during the sorting process, the sort has to be undoable.

SortCommandParser takes in an argument in the form of INDEX_TYPE that defines how UniquePersonList should be sorted. You may customise the sort operation, with PREFIX specifying the sort type. It first checks for validity against a regular expression. Once verified, the argument will be tokenized to identify your specified sort type. A SortCommand object is then created with the identified sort type.

The INDEX_TYPE can be any three of the following: 1 for sorting RC4 Students based on their level of friendship, 2 for sorting persons by meet date, 3 for sorting persons by Birthday. The sorted list is always default to descending order of importance.

Upon execution of SortCommand, a Comparator<Person> will be initialised based on the sort type it receives. A sortPersons function call will be made to Model, which propagates down to UniquePersonList, where the sorting of the internalList occurs. Since sorting of internalList results in the change of state to address book, SortCommand is to be implemented as an UndoableCommand.

Figure 4.5.1 : Structure of Sort Command in the Logic Component

ℹ️	Implementation of the Sort Command requires both the manipulation of `Logic` and `Model` component of address book.

The following sequence diagram shows the flow of operation from the point the address book receives an input to the output of the result.

Figure 27. Interactions Inside the Logic Component for the sort 1 Command_

ℹ️	If the list is found to be empty, an `CommandException` will be thrown from `SortCommand`. The command should be terminated without any state change, keeping the redoStack clean of changes.

3.15.1. Design Considerations

Aspect: Initialising of Comparator<Person>
Alternative 1: Initialise in SortCommand
Pros: Clear separation of concerns, SortCommandParser to handle identifying of attribute to sort by only.
Cons: Hard for new developers to follow as other commands like AddCommand handles object creation in its parser.
Alternative 2 (current choice): Initialise in UniquePersonList
Pros: Straightforward as initialises the Comparator where it is used.
Cons: UniquePersonList is at a lower level and should only handle a minimal set of Person related operations, and not logical operations like string matching.

Aspect: Sorting by multiple attribute
Alternative 1 (current choice): Only allows sorting by single attribute
Pros: Fast and arguments to input is straightforward.
Cons: Unable to have fine grain control of how list should appear.
Alternative 2: Allow sorting by multiple attribute
Pros: Enables fine grain control of how list should appear.
Cons: Not necessary as effect is only obvious when contact list is long and has multiple common names. As target audience for iConnect are students, contact list will not be more than few thousand contacts long.

3.16. Rate friends [Since v1.4]

The Rate friends feature allows RC4 residents to rate their friends and change their levels of friendship. This feature is implemented by the RateCommand and RateCommandParser in the Logic component of the CollegeZone code. The RC4 student is able to rate one or more friends by keying in the new desired level of friendship through the Command Line Interface (CLI). The RateCommand inherits from UndoableCommands as well, as shown in the diagram below.

To rate other RC4 residents and friends, the LevelOfFriendship class is being used and is part of the Person class. A Person is composed of a LevelOfFriendship component, and each person in CollegeZone application has a particular level of friendship between 1 to 10. The next diagram illustrates the relationship between a Person and its LevelOfFriendship.

The following shows a part of the code of RateCommand and reveals the parameters that RateCommand makes use of.

    public RateCommand(List<Index> indexList, String levelOfFriendship) {
    }

As observed, RateCommand involves two parameters, namely indexList and leveloffriendship.

indexList has a List of indexes type, and leveloffriendship is of String type.

The parameter indexList refers to the list of students whose are intended to be rated, and thus RateCommand is able to help RC4 residents rate multiple people at a time. The leveloffriendship parameter refers to the new level of friendship that the resident would like to rate their friends to.

The following code sample shows the execution of RateCommnad,

public CommandResult executeUndoableCommand() throws CommandException {
        List<Person> latestList = model.getFilteredPersonList();
        for (Index index : indexList) {
            Person selectedPerson = latestList.get(index.getZeroBased());
            try {
                Person editedPerson = new Person(selectedPerson.getName(), selectedPerson.getPhone(),
                        selectedPerson.getBirthday(), new LevelOfFriendship(levelOfFriendship),
                        selectedPerson.getUnitNumber(),
                        selectedPerson.getCcas(), selectedPerson.getMeetDate(), selectedPerson.getTags());
                model.updatePerson(selectedPerson, editedPerson);

As seen, the index of the student whose level of friendship is to be rated and changed, a new editedPerson object is created and all the details of the person, the name and phone number and other details were copied from the selectedPerson and is assigned the new level of friendship from the rate command.

ℹ️

If an invalid index value is entered, i.e the person with an index of which does not exist in CollegeZone contact list is entered with valid index entries, only the valid entries will have their Level of friendships rated and updated. As seen in the code below, there will be a error message informing the user that they have keyed in an invalid index value.

            if (index.getZeroBased() >= latestList.size()) {
                throw new CommandException(MESSAGE_ONE_OR_MORE_INVALID_INDEX);
            }

3.16.1. Design Considerations

Aspect: Implementation of RateCommand.
Alternative 1 (current choice): Creates a new Person object which copies all its respective personal details and adds a new LevelOfFriendship value.
Pros: It uses a pre-existing method, and additional methods to implement RateCommand need not be created and added.
Cons: Copying all respective personal data in order to change only the LevelOfFriendship attribute can be excessive as cause additional processing time if a person have many attributes.
Alternative 2: Add a changeLevelOfFriendship setter method in Person class
Pros: Relatively simple to implement.
Cons: Additional methods have to be added to ensure that the input values and indexes are valid.

4. Documentation

We use asciidoc for writing documentation.

ℹ️	We chose asciidoc over Markdown because asciidoc, although a bit more complex than Markdown, provides more flexibility in formatting.

4.1. Editing Documentation

See UsingGradle.adoc to learn how to render .adoc files locally to preview the end result of your edits. Alternatively, you can download the AsciiDoc plugin for IntelliJ, which allows you to preview the changes you have made to your .adoc files in real-time.

4.2. Publishing Documentation

See UsingTravis.adoc to learn how to deploy GitHub Pages using Travis.

4.3. Converting Documentation to PDF format

We use Google Chrome for converting documentation to PDF format, as Chrome’s PDF engine preserves hyperlinks used in webpages.

Here are the steps to convert the project documentation files to PDF format.

Follow the instructions in UsingGradle.adoc to convert the AsciiDoc files in the docs/ directory to HTML format.
Go to your generated HTML files in the build/docs folder, right click on them and select Open with → Google Chrome.
Within Chrome, click on the Print option in Chrome’s menu.
Set the destination to Save as PDF, then click Save to save a copy of the file in PDF format. For best results, use the settings indicated in the screenshot below.

Figure 28. Saving documentation as PDF files in Chrome

5. Testing

5.1. Running Tests

There are three ways to run tests.

💡	The most reliable way to run tests is the 3rd one. The first two methods might fail some GUI tests due to platform/resolution-specific idiosyncrasies.

Method 1: Using IntelliJ JUnit test runner

To run all tests, right-click on the src/test/java folder and choose Run 'All Tests'
To run a subset of tests, you can right-click on a test package, test class, or a test and choose Run 'ABC'

Method 2: Using Gradle

Open a console and run the command gradlew clean allTests (Mac/Linux: ./gradlew clean allTests)

ℹ️	See UsingGradle.adoc for more info on how to run tests using Gradle.

Method 3: Using Gradle (headless)

Thanks to the TestFX library we use, our GUI tests can be run in the headless mode. In the headless mode, GUI tests do not show up on the screen. That means the developer can do other things on the Computer while the tests are running.

To run tests in headless mode, open a console and run the command gradlew clean headless allTests (Mac/Linux: ./gradlew clean headless allTests)

5.2. Types of tests

We have two types of tests:

GUI Tests - These are tests involving the GUI. They include,
1. System Tests that test the entire App by simulating user actions on the GUI. These are in the systemtests package.
2. Unit tests that test the individual components. These are in seedu.address.ui package.
Non-GUI Tests - These are tests not involving the GUI. They include,
1. Unit tests targeting the lowest level methods/classes.
  e.g. seedu.address.commons.StringUtilTest
2. Integration tests that are checking the integration of multiple code units (those code units are assumed to be working).
  e.g. seedu.address.storage.StorageManagerTest
3. Hybrids of unit and integration tests. These test are checking multiple code units as well as how the are connected together.
  e.g. seedu.address.logic.LogicManagerTest

5.3. Troubleshooting Testing

Problem: HelpWindowTest fails with a NullPointerException.

Reason: One of its dependencies, UserGuide.html in src/main/resources/docs is missing.
Solution: Execute Gradle task processResources.

6. Dev Ops

6.1. Build Automation

See UsingGradle.adoc to learn how to use Gradle for build automation.

6.2. Continuous Integration

We use Travis CI and AppVeyor to perform Continuous Integration on our projects. See UsingTravis.adoc and UsingAppVeyor.adoc for more details.

6.3. Coverage Reporting

We use Coveralls to track the code coverage of our projects. See UsingCoveralls.adoc for more details.

6.4. Documentation Previews

When a pull request has changes to asciidoc files, you can use Netlify to see a preview of how the HTML version of those asciidoc files will look like when the pull request is merged. See UsingNetlify.adoc for more details.

6.5. Making a Release

Here are the steps to create a new release.

Update the version number in MainApp.java.
Generate a JAR file using Gradle.
Tag the repo with the version number. e.g. v0.1
Create a new release using GitHub and upload the JAR file you created.

6.6. Managing Dependencies

A project often depends on third-party libraries. For example, CollegeZone depends on the Jackson library for XML parsing. Managing these dependencies can be automated using Gradle. For example, Gradle can download the dependencies automatically, which is better than these alternatives.
a. Include those libraries in the repo (this bloats the repo size)
b. Require developers to download those libraries manually (this creates extra work for developers)

Appendix A: Product Scope

Target user profile:

Current NUS Students living in Residential College 4 (RC4)
has a need to manage a significant number of contacts (friends) and tasks to do
has a need to be reminded of things to do
has a need to keep track of goals that they have
prefer desktop apps over other types
can type fast
prefers typing over mouse input
is reasonably comfortable using CLI apps

Value proposition: manage contacts and tasks faster than a typical mouse/GUI driven app

Feature Contribution:

Assignee	Major	Minor
Deborah Low	Goals Panel : Allows user to set/edit/delete goals they have for the year and to keep track of their goals progress. Allows user to indicate goal is still ongoing or has already been completed. Allows user to sort goals.	Add and Edit : Change add and edit command to suit our target audience ( RC4 Students ) - adding birthday, cca, level of friendship and unit number field for student. GUI : Change the look and feel of the GUI to make it more user friendly. Allows user to switch themes.
Fuad B Sahmawi	Calendar: Integrate CalendarFX onto CollegeZone UI Reminder: Allows user to set/delete reminders reflected on the Calendar. Due reminders are marked red while undue reminders marked blue.	Find : Change find command to be able to find persons in contact list according to tags Logic : Added command aliases to allow users to be able to perform commands by typing shortcuts
Shamsheer Ahamed	Social (Meet-Up) : This feature allows user to set up meet ups with RC4 students that will be reflected on a Calendar Social (Sorting) : On top of the meet up dates appearing on the calendar, a sorting tool is also added to keep the user up to date with his meet up dates, birthdays and friendship levels.	Command Box Enhancement : Added a autocomplete command that auto fills the required preambles for the individual commands in the command box
Goh Zu Wei	Rate Friends : This feature allows categorize and rate one or more friends by changing their levels of friendships.	Seek: Add seek command to be able to seek the Resident Assistant (RA) of any particular the student living in RC4

Appendix B: User Stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Priority	As a …	I want to …	So that I can…
`* * *`	new user	see usage instructions	refer to instructions when I forget how to use the App
`* * *`	RC student	add a new person
`* * *`	RC student	delete a person	remove entries that I no longer need
`* * *`	RC student	find a person by name	locate details of persons without having to go through the entire list
`* * *`	RC student	find a person by tags	locate a particular group of people without having to go through the entire list
`* * *`	RC student	edit a detail I added
`* * *`	RC student	add my goals for the year	keep track of the goals I have and have not completed
`* * *`	RC student	set a level of friendship with a specific person	maintain my friendships depending on a priority system set by myself
`* * *`	RC student	Rate my friends	keep track and update of who my close friends are
`* * *`	RC student	edit details of my contacts	stay updated with the current information about my contacts
`* * *`	forgetful RC student	add persistent reminders	periodically remind myself to do something.
`* * *`	forgetful RC student	add other RC friends name, birthday, hall CCAs and tags into CollegeZone
`* * *`	forgetful RC student	set up a meet up with another RC4 student	shows who you are meeting up with on the calendar
`* * *`	RC student	note down tasks, events or training sessions in a calendar	make my schedule more organised
`* * *`	RC student	Set down a date for group events	do necessary group preparation prior to a group event
`* * *`	RC student	Set up meetings and keep track of them	I can effectively network and meet new people in my RC
`* * *`	RC student	easily find out important dates like meeting dates and birth dates	be up to task with those dates
`* *`	careless RC student	undo a command I entered	undo a wrong command that I entered
`* *`	careless RC student	redo a command I entered	redo when I want to undo my "undo" command
`* *`	RC student	write down a short reflection of how an event/training session went	remember precious moments easier in the future
`* *`	RC student	list down all past appointments with a particular friend	reminisce past memories with a particular friend
`* *`	RC student	hide private contact details by default	minimize chance of someone else seeing them by accident
`* *`	RC student	be reminded on when my campus fees are due	pay it on time
`* *`	RC student	know who the Resident Assistant (RA) is of a fellow resident	find the RA of the resident and convey floor issues to the RA
`*`	user with many persons in CollegeZone	sort persons by name	locate a person easily
`*`	user with many persons with the same in CollegeZone	set a display picture of each contact	differentiate persons with the same name

{More to be added}

Appendix C: Use Cases

C.1. Use case: Add student

MSS

User requests to add a student to the list
CollegeZone adds the student

Use case ends.

Extensions

1a. The given detail format is invalid.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.

C.2. Use case: List students

User requests to list students
CollegeZone shows a list of students

Use case ends.

Extensions

2a. The list is empty.

Use case ends.

C.3. Use case: Delete student

MSS

User requests to list students
CollegeZone shows a list of students
User requests to delete a specific student in the list
CollegeZone deletes the student

Use case ends.

Extensions

2a. The list is empty.

Use case ends.
3a. The given index is invalid.
- 3a1. CollegeZone shows an error message.
  
  Use case resumes at step 2.

C.4. Use case: Edit student

User requests to list students
CollegeZone shows a list of students
User requests to edit a detail or multiple details of a student in the list
CollegeZone edits the detail or details of the student

Use case ends.

Extensions

2a. The list is empty.

Use case ends.
3a. The given index is invalid.
- 3a1. CollegeZone shows an error message.
3b. The given detail format is invalid.
- 3b1. CollegeZone shows an error message.
  
  Use case resumes at step 2.

C.5. Use case: Find student

User requests to find student by tag or name using keywords
CollegeZone shows a list of students

Use case ends.

Extensions

1a. The given detail format is invalid.
- 1a1. CollegeZone shows an error message

2a. The list has all students with name or tag that matches keywords

Use case ends.

2b. The list is empty

Use case ends.

C.6. Use case: Select student or goal

User requests to list students
CollegeZone shows a list of students
User requests to select a student or goal
CollegeZone shows the detail of the student or goal

Use case ends.

Extensions

2a. The list is empty.

Use case ends.

3a. The given INDEX for either student or goal is invalid.
- 3a1. CollegeZone shows an error message
  
  Use case ends.

C.7. Use case: Add reminder

User requests to add a reminder on a certain date
CollegeZone adds the reminder in the calendar and changes are reflected on the calendar

Use case ends.

Extensions

1a. The given date detail in invalid.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.

C.8. Use case: Delete reminder

User requests to delete a certain reminder on a certain date
CollegeZone delete the reminder from the calendar and changes is reflected on the calendar

Use case ends.

Extensions

1a. The given reminder to delete does not exist.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
1b. The given details to delete reminder is invalid.
- 1b1. CollegeZone shows an error message.
  
  Use case ends.

C.9. Use case: Meet student

User request to add a meet up date on a certain date with a student using his index
CollegeZone adds the meet up in the calendar and changes are reflected in the calendar

Use case ends.

Extensions

1a. The given date is invalid.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
1b. The given student’s index is invalid.
- 1b1. CollegeZone shows an error message.
  
  Use case ends.

C.10. Use case: Sort students

Users requests to sort the RC4 Students list according to meet up dates.
CollegeZone sorts the list and shows the upcoming the meet dates first.

Use case ends.

Extensions

1a. The list is empty
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
1b. The given sorting index type is invalid.
- 1b1. CollegeZone shows an error message.
  
  Use case ends.

C.11. Use case: Add goal

User requests to add a goal in the list
CollegeZone adds the goal

Use case ends.

Extensions

1a. The given goal details is invalid.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.

C.12. Use case: Edit goal

CollegeZone shows a list of goals
User requests to edit a detail or multiple details of a goal in the list
CollegeZone edits the detail or details of the selected goal

Use case ends.

Extensions

1a. The list is empty.

Use case ends.
2a. The given index is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.
2b. The given goal detail format is invalid.
- 2b1. CollegeZone shows an error message.
  
  Use case ends.
2c. The given goal details is invalid.
- 2c1. CollegeZone shows an error message.
  
  Use case ends.

C.13. Use case: Delete goal

MSS

CollegeZone shows a list of goals
User requests to delete a specific goal in the list
CollegeZone deletes the goal

Use case ends.

Extensions

1a. The list is empty.

Use case ends.
2a. The given index is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.

C.14. Use case: Complete goal

MSS

CollegeZone shows a list of goals
User requests to complete a specific goal in the list
CollegeZone indicates the specified goal is completed

Use case ends.

Extensions

1a. The list is empty.
- 1a1. CollegeZone shows an error message.
2a. The given index is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.
2b. The specified goal is already completed.
- 2b1. CollegeZone shows an error message.
  
  Use case ends.

C.15. Use case: Ongoing goal

MSS

CollegeZone shows a list of goals
User requests to indicate goal is ongoing to a specific goal in the list
CollegeZone indicates the specified goal is ongoing

Use case ends.

Extensions

1a. The list is empty.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
2a. The given index is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.
2b. The specified goal is already ongoing.
- 2b1. CollegeZone shows an error message.
  
  Use case ends.

C.16. Use case: Sort goal

MSS

CollegeZone shows a list of goals
User requests sort goal based on field and order to sort
CollegeZone sort the goal list based on field and order specified

Use case ends.

Extensions

1a. The list is empty.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
2a. The given format is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.
2b. The given field is invalid.
- 2b1. CollegeZone shows an error message.
  
  Use case ends.
2c. The given order is invalid.
- 2c1. CollegeZone shows an error message.
  
  Use case ends.

C.17. Use case: Seek Resident Assistant (RA)

MSS

User requests to find students' RA by name using keywords.
CollegeZone shows a list of students and Resident assistants (RA).

Use case ends.

Extensions

1a. The given detail format is invalid.
- 1a1. CollegeZone shows an error message.

2a. The list has all students and RA(s) with name that matches keywords.

Use case ends.

2b. The list is empty

Use case ends.

C.18. Use case: Rate friends

MSS

User requests to list or show students of a particular level of friendship.
CollegeZone shows a list of students.
User requests to rate one or more student in the list.
CollegeZone rates and changes the level of friendship of the student(s).

Use case ends.

Extensions

2a. The list is empty.

Use case ends.
3a. The given index is invalid.
- 3a1. CollegeZone shows an error message.
3b. The given detail format is invalid.
- 3b1. CollegeZone shows an error message.
  
  Use case ends.

C.19. Use case: Show student

MSS

User requests to show student by level of friendship using valid value.
CollegeZone shows a list of students of a particular level of friendship.

Use case ends.

Extensions

1a. The given detail format is invalid.
- 1a1. CollegeZone shows an error message.

2a. The list has all students with level of friendship that matches input value.

Use case ends.

2b. The list is empty.

Use case ends.

C.20. Use case: Switch theme colour

MSS

CollegeZone has a theme colour
User requests to switch theme colour
CollegeZone switches theme colour

Use case ends.

Extensions

2a. The given theme colour is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.
2b. The given theme colour is currently in use.

Use case ends.

C.21. Use case: Undo

MSS

User requests to undo a command
CollegeZone undo the command and update CollegeZone

Use case ends.

Extensions

1a. The given format is invalid.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
1b. There are no more commands to undo.
- 1b1. CollegeZone shows an error message.
  
  Use case ends.

C.22. Use case: Redo

MSS

User requests to redo a command
CollegeZone redo the command and update CollegeZone

Use case ends.

Extensions

1a. The given format is invalid.
- 1a1. CollegeZone shows an error message.
  
  Use case ends.
1b. There are no more commands to redo.
- 1b1. CollegeZone shows an error message.
  
  Use case ends.

C.23. Use case: Seek Resident Assistant (RA)

C.24. Use case: History

MSS

User requests to toggle command history
CollegeZone displays command history

Use case ends.

Extensions

2a. The given format is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.

C.25. Use case: Clear

MSS

User requests to clear CollegeZone
CollegeZone deletes all data

Use case ends.

Extensions

2a. The given format is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.

C.26. Use case: Help

MSS

User requests for help page in CollegeZone
CollegeZone opens help page

Use case ends.

Extensions

2a. The given format is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.

C.27. Use case: Exit CollegeZone

MSS

User requests to exit CollegeZone
CollegeZone displays command history

Use case ends.

Extensions

2a. The given format is invalid.
- 2a1. CollegeZone shows an error message.
  
  Use case ends.

Appendix D: Non Functional Requirements

Should work on any mainstream OS as long as it has Java 1.8.0_60 or higher installed.
Should be able to hold up to 1000 persons without a noticeable sluggishness in performance for typical usage.
A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.
Should be intuitive to use for users who are not tech-savvy.
Should be able to be accessed offline.
The system should respond within 2 seconds.
Should work on 32-bit and 64-bit environment.
Should store data locally and should be in a .xml file. {More to be added}

Appendix E: Glossary

Mainstream OS: Windows, Linux, Unix, OS-X
Private contact detail: A contact detail that is not meant to be shared with others
Co-Curricular Activities: Co-Curricular Activities offered within Residential College 4 (RC4)
Residential College 4: A campus living area at NUS U-Town for NUS undergraduate students

Appendix F: Product Survey

Product Name

Author: …

Pros:

…
…

Cons:

…
…

Appendix G: Instructions for Manual Testing

Given below are instructions to test the app manually.

ℹ️	These instructions only provide a starting point for testers to work on; testers are expected to do more exploratory testing.

G.1. Launch and Shutdown

Initial launch
1. Download the jar file and copy into an empty folder
2. Double-click the jar file
  Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.
Saving window preferences
1. Resize the window to an optimum size. Move the window to a different location. Close the window.
2. Re-launch the app by double-clicking the jar file.
  Expected: The most recent window size and location is retained.

{ more test cases … }

G.2. Deleting a student

Deleting a student while all students are listed
1. Prerequisites: List all students using the list command. Multiple students in the list.
2. Test case: delete 1
  Expected: First contact is deleted from the list. Details of the deleted contact shown in the status message. Timestamp in the status bar is updated.
3. Test case: delete 0
  Expected: No student is deleted. Error details shown in the status message. Status bar remains the same.
4. Other incorrect delete commands to try: delete, delete x (where x is larger than the list size) {give more}
  Expected: Similar to previous.

{ more test cases … }

G.3. Saving data

Dealing with missing/corrupted data files
1. {explain how to simulate a missing/corrupted file and the expected behavior}

{ more test cases … }

Files

DeveloperGuide.adoc

Latest commit

History

DeveloperGuide.adoc

File metadata and controls

CollegeZone - Developer Guide

1. Setting up

1.1. Prerequisites

1.2. Setting up the project in your computer

1.3. Verifying the setup

1.4. Configurations to do before writing code

1.4.1. Configuring the coding style

1.4.2. Updating documentation to match your fork

1.4.3. Setting up CI

1.4.4. Getting started with coding

2. Design

2.1. Architecture

Events-Driven nature of the design

2.2. UI component

2.3. Logic component

2.4. Model component

2.5. Storage component

2.6. Common classes

3. Implementation

3.1. Undo/Redo feature

3.1.1. Current Implementation

3.1.2. Design Considerations

Aspect: Implementation of UndoableCommand

Aspect: How undo & redo executes

Aspect: Type of commands that can be undone/redone

Aspect: Data structure to support the undo/redo commands

3.2. [Proposed] Data Encryption

3.3. Logging

3.4. Configuration

3.5. Enhanced Find Command [Since v1.1]

3.5.1. Aspect: User Input

3.5.2. Aspect: Nature of user input

3.6. Command Aliases [Since v1.1]

3.7. Targeted add and edit command [Since v1.2]

3.7.1. Design Considerations

3.8. Reminders [Since v1.4]

3.8.1. Introduction

3.8.2. Implementation

3.8.3. Design Considerations

3.9. Goal Object [Since v1.2]

3.9.1. Implementation of Goal Object

3.9.2. Design Considerations

3.10. Add goal mechanism [Since v1.3]

3.10.1. Design Considerations

3.11. Delete goal mechanism [Since v1.4]

3.11.1. Design Considerations

3.12. Sort goal mechanism [Since v1.5]

3.12.1. Design Considerations

3.13. Switching theme mechanism [Since v1.5]

3.13.1. Design Considerations

3.14. Meet Command [Since v1.2]

3.14.1. Implementation

3.14.2. Design Considerations

3.15. Sort Command [Since v1.4]

3.15.1. Design Considerations

3.16. Rate friends [Since v1.4]

3.16.1. Design Considerations

4. Documentation

4.1. Editing Documentation

4.2. Publishing Documentation

4.3. Converting Documentation to PDF format

5. Testing

5.1. Running Tests

5.2. Types of tests

5.3. Troubleshooting Testing

6. Dev Ops

6.1. Build Automation

6.2. Continuous Integration

6.3. Coverage Reporting

6.4. Documentation Previews

6.5. Making a Release

6.6. Managing Dependencies

Appendix A: Product Scope

Appendix B: User Stories

Aspect: Implementation of `UndoableCommand`