Skip to content

Latest commit

 

History

History
1345 lines (935 loc) · 61.3 KB

DeveloperGuide.adoc

File metadata and controls

1345 lines (935 loc) · 61.3 KB

Module Planner - Developer Guide

By: Team T16-4      Since: Sep 2018      Licence: MIT

1. Setting up

1.1. Prerequisites

  1. JDK 9 or later

    ⚠️
    		 JDK 10 on Windows will fail to run tests in headless mode due to a JavaFX bug. Windows developers are highly recommended to use JDK 9.

  2. 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

  1. Fork this repo, and clone the fork to your computer

  2. Open IntelliJ (if you are not in the welcome screen, click File > Close Project to close the existing project dialog first)

  3. 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

  4. Click Import Project

  5. Locate the build.gradle file and select it. Click OK

  6. Click Open as Project

  7. Click OK to accept the default settings

  8. 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

  1. Run the seedu.planner.MainApp and try a few commands

  2. 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,

  1. Go to File > Settings…​ (Windows/Linux), or IntelliJ IDEA > Preferences…​ (macOS)

  2. Select Editor > Code Style > Java

  3. 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, the documentation will still have the T16-4 branding and refer to the CS2103-AY1818S1-T16-4/main repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to CS2103-AY1818S1-T16-4/main), you should do the following:

  1. Configure the site-wide documentation settings in build.gradle, such as the site-name, to suit your own project.

  2. Replace the URL in the attribute 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,

  1. Get some sense of the overall design by reading Section 2.1, “Architecture”.

  2. Take a look at [GetStartedProgramming].

2. Design

2.1. Architecture

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.

LogicClassDiagram
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.

SDforDeletePerson
Figure 3. Component interactions for delete 1 command (part 1)
ℹ️
 Note how the Model simply raises a ModulePlannerChangedEvent when the Module Planner 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.

SDforDeletePersonEventHandling
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

UiClassDiagram
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, ModuleListPanel, StatusBarFooter, FindModulePanel 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

LogicClassDiagram
Figure 6. Structure of the Logic Component

API : Logic.java

  1. Logic uses the ModulePlannerParser class to parse the user command.

  2. This results in a Command object which is executed by the LogicManager.

  3. The command execution can affect the Model (e.g. adding a module) and/or raise events.

  4. 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 c/CS1010") API call.

DeletePersonSdForLogic
Figure 7. Interactions Inside the Logic Component for the delete 1 Command

2.4. Model component

ModelClassDiagram
Figure 8. Structure of the Model Component

API : Model.java

The Model,

  • stores a UserPref object that represents the user’s preferences.

  • stores the Module Planner data.

  • exposes an unmodifiable ObservableList<Module> 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

StorageClassDiagram
Figure 9. Structure of the Storage Component

API : Storage.java

The Storage component,

  • can save UserPref objects in JSON format and read it back.

  • can save ReadOnlyModulePlanner object in JSON format and read it back.

StorageSequenceDiagram
Figure 10. Interactions inside the Storage component for whenever ModulePlannerChangedEvent is fired.

2.6. Common classes

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

3. Implementation

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

3.1. Module and Major Information

Information about modules and majors supports almost all the features in Module Planner.

Information of a module such as module code, module credit and prerequisite modules are stored in ModuleInfo class. This class is made to be immutable to avoid accidental changes to the class.

3.1.1. Current Implementation

Overview of components

Internally, ModuleInfo is an immutable class that holds all the information of a module that is universal to all students from any faculty. MajorDescription is an immutable class that holds information about the requirements of a major.

ModuleInfoClassDiagram
Figure 11. Class diagram for ModuleInfo.
MajorDescriptionClassDiagram
Figure 12. Class diagram for MajorDescription.

3.1.2. Deliberate simplifications

The real information about NUS modules are very complicated. Here list down some simplifications we made in order to create this proof of concept of our application.

Prequisites and preclusion

IVLE provides the prerequisites and preclusion of a module in normal English sentence (e.g. "CS1010 or its equivalents" and "Departmental approval"). Extracting the real module prerequisite and preclusion relationship would be infeasible due to the potential long list of exceptions we need to handle. To simplify this, we use regular expression to extract the module codes.

How are prerequisite and preclusion checking is implemented:

  • If user wants to take Module A, all prerequisites of Module A must already have been taken.

  • If Module B’s preclusion has at least one module that user has already taken, user cannot take Module B.

This gives a reasonable approximation of prerquisite and preclusion relationship for most modules.

Corequisites

Corequisite is used to descibe which modules must be taken together. We choose to ignore this entirely as it will complicate the implementation of add and delete commands significantly.

3.1.3. Data sanitizing script

The python script that downloads the list of NUS modules from NUSMods server and does the data transformation detailed above can be found at (moduleConverter.py).

3.1.4. Design Consideration

Aspect: Representation of major and focus area

  • Alternative 1 (current choice): Use enum to represent major and focus area.

    • Pros: Stronger type checking.

    • Cons: Need to explicitly list down all the possible values of enums (there are more than hundreds of focus areas in all NUS majors). Special JSON serialization and deserialization is needed for enum types.

  • Alternative 2: Use String to represent major and focus area.

    • Pros: No need to convert major and focus area inputted by user into another type.

    • Cons: If major/focus area is passed into a function as a parameter, the function cannot assume that the it is a valid major/focus area. This leads to a lot of redundant checking.

Aspect: Storing of module and major information

To avoid having to download the module and major information from the Internet in first start up, we package the data directly into final .jar file as a resource file.

  • Alternative 1 (current choice): Store data in as a JSON resource file and deserialize data into Java types at runtime.

    • Pros: JSON format is easy to learn and can be manipulated easily with other (interpreted) programming languages.

    • Cons: JSON format can only hold simple primitive types such as String, number, array and hash table. Need to design a way to flatten the module relationship graph into something that can be represented in JSON and reconstruct the graph after deserialization.

  • Alternative 2: Generate Java code during build time. The data will be directly stored as a static constant Java object.

    • Pros: Better performance in runtime as the deserialization is no longer needed. Less moving parts when testing the data itself.

    • Cons: More complex build procedures.

Aspect: Two different classes to store module related information (ModuleInfo and ModuleDescription)

ModuleInfoRetriever opens the processed data/moduleInfo.json file packaged in the JAR file and deserialize its content into an array of ModuleInfo objects. As JSON can only hold simple values such as strings and numbers, prerequisites and preclusion are stored as an array of String, so we need to call ModuleInfo.finalizeModuleInfo to convert the strings into ModuleInfo`s as well before we can start querying prerequisite and preclusion from `ModuleInfo#getPrerequisites and ModuleInfo#getPreclusions.

3.2. Setup feature

3.2.1. Current Implementation

The setup command allows users to save their major and optionally their focus areas in Module Planner. The information is stored in UserProfile and is later used by suggest and status commands.

The following sequence shows the sequence when setup command is executed.

SetupSequenceDiagram
Figure 13. Sequence Diagram for setup command.

3.2.2. Design Considerations

Aspect: Argument leniency

  • Alternative 1: Entirely reject all focus areas even if one is invalid. Focus areas must have the exact same letter casing as listed in User Guide.

    • Pros: Implementation would be simpler.

    • Cons: Not user friendly. It is too easy for users to input the wrong letter casing, causing many retries.

  • Alternative 2 (current choice): Accept the valid focus areas even if one is invalid. Focus areas inputted is case-insensitive.

    • Pros: More user friendly. User is able to update the user profile and gets positive result.

    • Cons: Need to implement filtering of valid focus areas from inputted focus areas. As f/Computer Science and f/cOmpUter SciEnce are now both valid inputs and can be inputted at the same time, we also need to filter out duplicates.

3.2.3. Aspect: Error handling

  • Alternative 1: Check format criterias one by one and immediately throw an error in first failure.

    • Pros: Implementation would be simpler. Less possible of combinations to test.

    • Cons: Not user friendly. User only sees one syntax error at one time. If there are many syntax errors in user’s first try, it will take many retries for user to figure all the syntax errors.

  • Alternative 2: Check all format criterias. If there are more than one erros, concatenate their error message before throwing exception.

    • Pros: More user friendly. User will be able to see all syntax erros in first try and fix them.

    • Cons: Need to create many negative test cases to test each error individually and all together. More complicated to test the expected error messages.

3.3. Add feature

3.3.1. Current Implementation

The add mechanism is facilitated by ModulePlanner. ModulePlanner stores a list of Semester objects. A Semester stores a list containing modules that the user has taken or is planning to take on that semester.

Add mechanism is also facilitated by the posting and handling of events. The AddCommand#execute(…​) is the event poster and the MainWindow#handleAddEvent(…​) is the event handler.

The implementation is as follows:

  • ModulePlanner#addModules(List<Module> modules, int index) — Add the list of modules into the semester specified by index.

The operation above is exposed in the Model interface as Model#addModules(List<Module> modules, int index)

The following sequence diagram shows how the add operation works:

AddSequenceDiagram

In executing the add operation, the AddCommand will apply several filters on the input list of modules.

Consider the following case:

ModulePlanner contains only CS1010 in year 1 semester 1 and the user tries to add the following list of modules : CS0000, CS1010, CS1010E, CS1231, MA1100, CS2030, GER1000 to year 1 semester 1. The filterings, sequentially, are as follows:

(1) Filter out module(s) not offered by the education institute

Module CS0000 is not offered. It will be filtered out from the list and the user will be informed that it is not an offered module.

(2) Filter out module(s) that already exist in the planner

Module CS1010 is already in the planner. It will be filtered out from the list and the user will be informed that it exists in the planner.

(3) Filter out module(s) which some of its preclusion is in the planner

Module CS1010E has CS1010 as its preclusion. It will be filtered out from the list and the user will be informed that this module has some of its preclusion in the planner.

(4) Filter out equivalent modules

Modules CS1231 and MA1100 are equivalent. These modules will be filtered out from the list, then grouped by equivalence and the user will be told that these modules are equivalence.

(5) Filter out module(s) which some of its prerequisites has not been fulfilled.

Module CS2030 has CS1010 as its prerequisite. To be able to add it to the planner, CS1010 must exist in previous semesters, which in this case is not possible since the semester to be added is the the earliest semester possible. Thus the module will be filtered out from the list and the user will be informed that the prerequisites for this module is not fulfilled yet.

(6) Add the filtered list of module(s) to the planner

At this point, the list to be added has been finalized. The Model#addModules(List<Module> modules, int index) is then called to add this list of module(s) (in this case only GER1000) to the planner.

ℹ️
 (1) The messages for each filtering will be collected and displayed simultaneously to the user.
(2) If the final filtered list is empty, the command box will not be emptied so the user do not need to type all over again.

3.3.2. Design Considerations

Aspect: Different semester start

The current implementation allows users to explore possible scenarios of study plan that they can make. Assuming a user is already in the middle of his study, let’s say he is in second year already, he can still modify his first year’s modules to see other possible study plans. Implementing a way to initialize ModulePlanner based on the user’s past modules (which they can’t modify after initializing) would be a good idea for the following reasons:

  1. To mirror the real world - it is impossible for a student to void a module that has already been taken.

  2. To prevent undefined behaviour - omitting a module already taken might make all future modules not yet taken to be inaccurately planned. Also, all currently suggested modules to the user might too be inaccurate.

Below are the summary of pros and cons of the current implementation and the alternative design:

  • Current implementation: Able to plan for every semester

    • Pros: Allow users to explore various study plans

    • Cons: Doesn’t enforce users to deal with their real progress

  • Alternative design: Only able to plan for future semester, with some initialization

    • Pros: Allow users to commit on their real progress

    • Cons: Harder implementation

3.4. Delete feature

3.4.1. Current Implementation

About

The current delete mechanism is facilitated by ModulePlanner. ModulePlanner stores a list of all the semesters the user has taken and will take. In turn, Semester stores a list of the modules the user has taken, is currently taking or will be taking.

Process

When a module is deleted, ModulePlanner will go through every module added after the semester which the module is deleted from and checks if those modules now have prerequisites that are not fulfilled. If there are now prerequisites not fulfilled for the modules checked, they too are deleted and the process repeats for them. For better addressing, this process will be defined as Iterative Deletion.

Input

The arguments given to the mechanism are modules, which can be a mix of valid and invalid modules. A valid module is defined as one that has the correct module code format and has been taken, is currently being taken or will be taken by the user (is stored in the module planner). An invalid module is defined as the opposite.

Result

Out of all these arguments, only the valid modules will be deleted from the module planner. The invalid modules are collected and made known to the user through the Result Display. The modules that are not found in the module planner are shown to the user in the Result Display. Modules with invalid module code formats are already filtered out by the DeleteCommandParser and hence do not appear as part of the message shown in the Result Display.

ModulePlanner uses the following operation to implement the delete mechanism:

  • ModulePlanner#deleteModules(List<Module> modules) — Deletes the modules from whatever semester it is in.

The above operation is exposed in the Model interface as Model#deleteModules(List<Module> modules)

The following sequence diagram shows how the delete operation works:

DeleteSequenceDiagram

Below are some usage scenarios. For convenience, let’s define some valid modules: CS1010, CS2030 and CS2040 and an invalid module CS0000. CS1010 is a prerequisite for CS2030 and CS2040. Let’s also initialise a module planner with those valid modules:
YEAR 1 SEMESTER 1: [CS1010]
YEAR 1 SEMESTER 2: [CS2030, CS2040]
…​

A Valid Module

The user executes delete CS1010 command to delete the valid module CS1010. The delete command calls Model#deleteModules(…​), which removes the module from the semester where it is found. Iterative Deletion is then applied. Since CS2030 and CS2040 have CS1010 as a prerequisite, if CS1010 is deleted, CS2030 and CS2040 will too be deleted.

The module planner now has this state:
[EMPTY]

ℹ️
 This applies to when more than one valid module is supplied.
An Invalid Module

The user executes delete CS0000 command. However, since that module is not found in the module planner, the command fails and Model#deleteModules(…​) will not be called. The user will be informed of the invalid module.

ℹ️
 This applies to where more than one invalid module is supplied.
Mix of Valid and Invalid Modules

The user executes delete CS1010 CS0000. However, only the module CS1010 is valid. In this case, Model#deleteModules(…​) is still called, but only the valid module CS1010 will be deleted and Iterative Deletion applied. The user will be informed of the invalid module.

ℹ️
 This applies to where more than one valid and invalid modules are supplied.
No Modules

The user executes delete. As the command has no supplied arguments, the command will fail and the user will be informed to input arguments.

3.4.2. Design Considerations

Aspect: Argument leniency

  • Alternative 1: Entirely reject modules even if one is invalid.

    • Pros: Simple logic and requires minimal code.

    • Cons: Not user friendly. The user now has to expend additional effort to edit the modules inputted.

  • Alternative 2 (current choice): Accept the valid modules even if one is invalid.

    • Pros: User friendly. The user gets to delete the valid modules and is notified of which modules are invalid and why.

    • Cons: More complex. Requires filtering logic.

Aspect: Iterative Deletion

  • Alternative 1 (current choice): Iterate through the modules in each semester for all years. For each semester, the modules that do not have their prerequisite fulfilled are marked as invalid and are deleted.

    • Pros: Simple logic and requires minimal code.

    • Cons: Although the number of modules in the module planner is weakly limited by the education institute (students are only required to take about 40 modules to earn a degree), the algorithm is still relatively slow.

  • Alternative 2: Construct a direct acyclic graph for all the modules in the module planner

    • Pros: Fast and efficient. There is no need to iterative through several semesters to mark modules as invalid and then deleting them.

    • Cons: More complex. Due to time constraints during the project, this approach was not taken.

3.5. Find feature

3.5.1. Current Implementation

About

The find mechanism is facilitated by the posting and handling of events. The FindCommand#execute(…​) is the event poster and the MainWindow#handleFindEvent(…​) is the event handler. find allows the user to retrieve more information about a specified module.

Input

The argument given to the mechanism is a module, which has to be offered by the education institute. If a module is not offered, the command fails.

Result

The information about the module is retrieved and displayed in the Multipurpose Panel.

The following sequence diagram shows how the find operation works:

FindSequenceDiagram

Below are some usage scenarios.

3.5.2. Module is Offered

The user executes find c/CS1010. The MultiPurposePanel displays the retrieved module information.

3.5.3. Module is Not Offered

The user executes find c/CS0000. The MultiPurposePanel does not display anything.

3.6. Goto feature

3.6.1. Current Implementation

About

The goto mechanism is facilitated by the posting and handling of events. The GoToCommand#execute(…​) is the event poster and the MainWindow#handleGoToEvent(…​) is the event handler. goto allows the user to switch between time periods in the ui. A time period is defined as a year-semester pair [Year, Semester].

Input

The argument given to the mechanism is a year-semester pair. The year has to be between 1 and 4, and the semester has to be between 1 and 2.

Result

The ui switches time periods to the specified. The modules taken in the time period is displayed too.

The following sequence diagram shows how the goto operation works:

GoToSequenceDiagram

Below are some usage scenarios.

Valid Year and Semester

The user executes goto y/1 s/1. Since both the year and semester are valid, the ui changes accordingly.

Invalid Year and Valid Semester

The user executes goto y/5 s/1. Since only the semester is valid, command fails and the ui does not change.

ℹ️
 This applies to when the year is valid but the semester is invalid.
ℹ️
 It is possible that some users take a 5th year and beyond in their education institute. However, as of now, Module Planner does not support years beyond the 4th.

3.7. List feature

3.7.1. Current Implementation

The list mechanism is facilitated by ModulePlanner. ModulePlanner stores a list of all Semester`s and each `Semester stores a list modulesTaken containing modules that the user has taken or is planning to take. It implements the following operation:

  • ModulePlanner#getTakenModules() — Retrieves the list takenModules.

  • ModulePlanner#listTakenModulesAll() — Updates takenModules to contain a list of modules retrieved from the list modulesTaken in every Semester.

  • ModulePlanner#listTakenModulesForYear(int year) — Updates takenModules to contain a list of modules retrieved from the list modulesTaken in the `Semester`s that belongs to the specified year.

The operation is exposed in Model interface as Model#getTakenModules(), Model#listTakenModulesAll(), and Model#listTakenModulesForYear(int year).

ℹ️
 A valid index should be an integer between 0 to 7 inclusive, where index 0 represents year 1 semester 1, index 1 represents year 1 semester 2, index 2 represents year 2 semester 1, and so on.

Below is an example usage scenario and how the list mechanism works.

Step 1. User launches the application. ModulePlanner is initialised with 8 Semester objects in a list semesters.

Step 2. User executes add y/1 s/1 c/CS1231. The add command inserts Module CS1231 to the list modulesTaken for Semester object with index 0.

Step 3. User executes add y/2 s/1 c/CS1010. The add command inserts Module CS1010 to the list modulesTaken for Semester object with index 2.

Step 4. User wants to see the list of modules taken for year 1 by executing list y/1. The list command updates takenModules to contain list of modules taken in year 1 and retrieves it. A list containing CS1231 will be displayed to the user.

Step 5. User wants to see the list of modules taken for all years by executing list. The list command updates takenModules to contain list of modules taken in all years and retrieves it. A list containing CS1231 and CS1010 will be displayed to the user.

The following sequence diagram shows how the list operation when a valid year is specified:

ListSequenceDiagram 1

The following sequence diagram shows how the list operation when no year is specified:

ListSequenceDiagram 2

3.7.2. Design Considerations

Aspect: How list of modules is retrieved for list command

  • Alternative 1 (current choice): Updates list of modules whenever it is modified by a command (e.g. add) and immediately retrieves the list upon list command.

    • Pros: Easy to implement.

    • Cons: May have performance issue in terms of running time if commands that modify the list are called frequently.

  • Alternative 2: Saves all commands that modify list of modules without applying it and updates the list based on the commands only when it is retrieved upon list command.

    • Pros: May be more effective in terms of running time because it only modifies the list when needed.

    • Cons: Implementation will be more complicated as we have to store all commands that modify the list.

3.8. Status feature

3.8.1. Current Implementation

Status feature allows the user to keep track of their credit progress for different requirements. It is tracked in the ModulePlanner in form of a map and will be updated every time the user use the add or delete feature and when they set up their profile. This map will then later posted by StatusCommand#execute(…​) in an event. Finally MainWindow#handleStatusEvent(…​) will handle this event and convert the map to a string for display.

The implementation is as follows:

*ModulePlanner#getStatus()-Updates and retrieves the status of credit progress in the ModulePlanner

The operation above is exposed in Model as Model#getStatus().

Below shows the sequence diagram which describe how the status feature works:

StatusSequenceDiagram

Initially, status feature will display progress for degree requirements which does not include unrestricted electives and focus area requirements. When the user sets up their focus area, additional field(s) of Focus_Area_Requirement will be added to the status. The additional field(s) are named "Focus Area Requirement 1", "Focus Area Requirement 2" and so on, with the number of additional fields is equal to the number of focus area that the user has.

As an illustration, consider the following case:

Initially, the ModulePlanner is empty and the user does not have any focus area. Using the status feature will display the following strings:

University Level Requirement: 0/20
Foundation: 0/36
Mathematics: 0/12
Science: 0/4
IT Professionalism: 0/12
Industrial Experience Requirement: 0/12
Team Project: 0/8

Now the user wants to set up Software Engineering and Artificial Intelligence as their focus area.
The status will now display additional strings as follows:

Focus Area Requirement 1: 0/12
Focus Area Requirement 2: 0/12

3.8.2. Design Considerations

Aspect: Inclusion of Unrestricted Elective requirement

Currently the status doesn’t keep track of Unrestricted Elective requirement because of the complexity of how it is counted. Credits from modules with more than 4 credit count may or may not have its extra credits transferred to UE requirement. For that, a possible alternative would be to list down all modules with more than 4 credit count that transfer its extra credits to UE credits and taking them into consideration.

Below are the summary of pros and cons of the current implementation and the alternative design

  • Current Implementation: Doesn’t include Unrestricted Electives

    • Pros: Straightforward implementation by just counting for each module

    • Cons: Doesn’t include all possible degree requirements, hence not real progress

  • Alternative Design: Includes Unrestricted Electives

    • Pros: Able to track real progress

    • Cons: Much more tedious to implement

3.9. Suggest feature

3.9.1. Current Implementation

The suggest mechanism displays a list of modules available in the specified index to the user, where index represents the year and semester that the user is asking suggestions for. It is supported by an internal list availableModules in ModulePlanner, which is regenerated after every successful execution of commands that modify ModulePlanner (add, delete, clear, etc.) and suggest command. The list availableModules can be retrieved through Model#getAvailableList() using suggest command, which (suggest command) takes in one argument: a valid index that corresponds to a specific year and semester.

ℹ️
 A valid index should be an integer between 0 to 7 inclusive, where index 0 represents year 1 semester 1, index 1 represents year 1 semester 2, index 2 represents year 2 semester 1, and so on.

Below is an example usage scenario and how the suggest mechanism works.

Step 1. User launches the application and ModulePlanner is initialized.

Step 2. User executes suggest y/1 s/1. The suggest command updates availableModules to a newly generated list of available modules for index 0 an stores index 0 as availableIndex in ModulePlanner. It then retrieves availableModules and displays it to user.

Step 3. User executes add y/1 s/2 c/CS1010. The add command performs adding a module and updates availableModules to a newly generated list of available modules for the stored index 0. The suggested modules list shows an updated list of available modules in year 1 semester 1 to the user. Only suggest command will change the index (year and semester) to be displayed by the suggested modules list, other commands will only show an updated list for the last index displayed by suggest.

Step 4. User executes suggest y/1 s/2. The suggest command updates availableModules to a newly generated list of available modules for index 1 an stores index 1 as availableIndex in ModulePlanner. It then retrieves availableModules and displays list of available modules in year 1 semester 2 to user.

Below is how the list of available modules is generated.

The method ModulePlanner#generateAvailableModules(int index) is called by ModulePlanner#updateModulesAvailable(), which sets the content of availableModules to be the list of modules returned by generateAvailableModules(index), with index being the stored availableIndex.

private List<Module> generateAvailableModules(int index) {
    List<Module> modulesAvailable = new ArrayList<>();
    List<Module> modulesTaken = getAllModulesTaken();
    List<Module> modulesTakenBeforeIndex = getAllModulesTakenBeforeIndex(index);
    List<Module> allModules = getAllModulesFromStorage();

    for (Module m : allModules) {
        if (ModuleUtil.isModuleAvailable(modulesTaken, modulesTakenBeforeIndex, m)) {
            modulesAvailable.add(m);
        }
    }

    sortAvailableModules(modulesAvailable, userProfile);

    return modulesAvailable;
}

The method ModulePlanner#generateAvailableModules(int index) retrieves all modules from the storage and performs availability checking on each of them. The available modules are put into a list which is then sorted:

  • in a lexicographical order if user has specified a major other than Computer Science through setup command, or

  • such that core modules for Computer Science major are put on top, followed by general education modules and unrestricted electives.

The availability checking is done by the following method.

public static boolean isModuleAvailableToTake(List<Module> modulesTaken, List<Module> modulesTakenBeforeIndex, Module module) {
    return hasNotTakenModule(modulesTaken, module)
            && hasFulfilledAllPrerequisites(modulesTakenBeforeIndex, module)
            && hasNotFulfilledAnyPreclusions(modulesTaken, module);
}

A sample scenario: Module CS2030 has a prerequisite CS1010 and a preclusion CS1020. User has taken CS1010 in year 1 semester 2 and has not taken CS1020 or CS2030.

  • Executing suggest y/2 s/1 will display CS2030 as one of the available modules, as user has fulfilled all prerequisites of CS2030 before year 2 semester 1 and has not taken any preclusion or the module itself.

  • Executing suggest y/1 s/1 will not display CS2030 in the list of available modules, as user has not fulfilled all the prerequisites before year 1 semester 1 (user has only fulfilled CS1010 in the semester after).

The following sequence diagram shows how the suggest operation works:

SuggestSequenceDiagram

3.9.2. Design Considerations

Aspect: How list of available modules is regenerated

  • Alternative 1 (current choice): Regenerates list of available modules after every successful execution of commands that modify ModulePlanner and suggest command.

    • Pros: Easy to implement.

    • Cons: May have performance issue in terms of running time because list is regenerated even if there is no change to the content.

  • Alternative 2: Regenerates list of available module only after successful execution of commands that modify the content of the list of available modules.

    • Pros: May be more effective in terms of running time because it only regenerates the list when needed.

    • Cons: Implementation will be more complicated as we have to check whether a command modifies the list.

3.10. Undo/Redo feature

3.10.1. Current Implementation

The undo/redo mechanism is facilitated by VersionedModulePlanner. It extends ModulePlanner with an undo/redo history, stored internally as an modulePlannerStateList and currentStatePointer. Additionally, it implements the following operations:

  • VersionedModulePlanner#commit() — Saves the current module planner state in its history.

  • VersionedModulePlanner#undo() — Restores the previous module planner state from its history.

  • VersionedModulePlanner#redo() — Restores a previously undone module planner state from its history.

These operations are exposed in the Model interface as Model#commitModulePlanner(), Model#undoModulePlanner() and Model#redoModulePlanner() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedModulePlanner will be initialized with the initial module planner state, and the currentStatePointer pointing to that single module planner state.

UndoRedoStartingStateListDiagram

Step 2. The user executes delete c/GER1000 command to delete the module GER1000 in the module planner. The delete command calls Model#commitModulePlanner(), causing the modified state of the module planner after the delete c/CS1010 command executes to be saved in the modulePlannerStateList, and the currentStatePointer is shifted to the newly inserted module planner state.

UndoRedoNewCommand1StateListDiagram

Step 3. The user executes add y/1 s/1 c/CS1010 to add the module CS1010 to the first year first semester. The `add command also calls Model#commitModulePlanner(), causing another modified module planner state to be saved into the modulePlannerStateList.

UndoRedoNewCommand2StateListDiagram
ℹ️
 If a command fails its execution, it will not call Model#commitModulePlanner(), so the module planner state will not be saved into the modulePlannerStateList.

Step 4. The user now decides that adding the module was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoModulePlanner(), which will shift the currentStatePointer once to the left, pointing it to the previous module planner state, and restores the module planner to that state.

UndoRedoExecuteUndoStateListDiagram
ℹ️
 If the currentStatePointer is at index 0, pointing to the initial module planner state, then there are no previous module planner states to restore. The undo command uses Model#canUndoModulePlanner() to check if this is the case. If so, it will return an error to the user rather than attempting to perform the undo.

The following sequence diagram shows how the undo operation works:

UndoRedoSequenceDiagram

The redo command does the opposite — it calls Model#redoModulePlanner(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the module planner to that state.

ℹ️
 If the currentStatePointer is at index modulePlannerStateList.size() - 1, pointing to the latest module planner state, then there are no undone module planner states to restore. The redo command uses Model#canRedoModulePlanner() to check if this is the case. If so, it will return an error to the user rather than attempting to perform the redo.

Step 5. The user then decides to execute the command list. Commands that do not modify the module planner, such as list, will usually not call Model#commitModulePlanner(), Model#undoModulePlanner() or Model#redoModulePlanner(). Thus, the modulePlannerStateList remains unchanged.

UndoRedoNewCommand3StateListDiagram

Step 6. The user executes clear, which calls Model#commitModulePlanner(). Since the currentStatePointer is not pointing at the end of the modulePlannerStateList, all module planner states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add y/1 s/1 c/CS1010 command. This is the behavior that most modern desktop applications follow.

UndoRedoNewCommand4StateListDiagram

The following activity diagram summarizes what happens when a user executes a new command:

UndoRedoActivityDiagram

3.10.2. Design Considerations

Aspect: How undo & redo executes

  • Alternative 1 (current choice): Saves the entire module planner.

    • 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 module being deleted, as well as the year and semester it was in).

    • Cons: We must ensure that the implementation of each individual command are correct.

Aspect: Data structure to support the undo/redo commands

  • Alternative 1 (current choice): Use a list to store the history of module planner states.

    • Pros: Easy 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 VersionedModulePlanner.

  • Alternative 2: Use HistoryManager for undo/redo

    • Pros: We do not need to maintain a separate list, 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.11. 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.12, “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.12. Configuration

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

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.

  1. Follow the instructions in UsingGradle.adoc to convert the AsciiDoc files in the docs/ directory to HTML format.

  2. Go to your generated HTML files in the build/docs folder, right click on them and select Open with → Google Chrome.

  3. Within Chrome, click on the Print option in Chrome’s menu.

  4. 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.

chrome save as pdf
Figure 14. Saving documentation as PDF files in Chrome

4.4. Site-wide Documentation Settings

The build.gradle file specifies some project-specific asciidoc attributes which affects how all documentation files within this project are rendered.

💡
 Attributes left unset in the build.gradle file will use their default value, if any.
Table 1. List of site-wide attributes
Attribute name Description Default value

site-name

The name of the website. If set, the name will be displayed near the top of the page.

not set

site-githuburl

URL to the site’s repository on GitHub. Setting this will add a "View on GitHub" link in the navigation bar.

not set

site-seedu

Define this attribute if the project is an official SE-EDU project. This will render the SE-EDU navigation bar at the top of the page, and add some SE-EDU-specific navigation items.

not set

4.5. Per-file Documentation Settings

Each .adoc file may also specify some file-specific asciidoc attributes which affects how the file is rendered.

Asciidoctor’s built-in attributes may be specified and used as well.

💡
 Attributes left unset in .adoc files will use their default value, if any.
Table 2. List of per-file attributes, excluding Asciidoctor’s built-in attributes
Attribute name Description Default value

site-section

Site section that the document belongs to. This will cause the associated item in the navigation bar to be highlighted. One of: UserGuide, DeveloperGuide, LearningOutcomes*, AboutUs, ContactUs

* Official SE-EDU projects only

not set

no-site-header

Set this attribute to remove the site navigation bar.

not set

4.6. Site Template

The files in docs/stylesheets are the CSS stylesheets of the site. You can modify them to change some properties of the site’s design.

The files in docs/templates controls the rendering of .adoc files into HTML5. These template files are written in a mixture of Ruby and Slim.

⚠️

Modifying the template files in docs/templates requires some knowledge and experience with Ruby and Asciidoctor’s API. You should only modify them if you need greater control over the site’s layout than what stylesheets can provide. The SE-EDU team does not provide support for modified template files.

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:

  1. 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.planner.ui package.

  2. Non-GUI Tests - These are tests not involving the GUI. They include,

    1. Unit tests targeting the lowest level methods/classes.
      e.g. seedu.planner.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.planner.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.planner.logic.LogicManagerTest

5.3. Troubleshooting Testing

Problem: HelpWindowTest fails with a NullPointerException.

  • Reason: One of its dependencies, HelpWindow.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.

  1. Update the version number in MainApp.java.

  2. Generate a JAR file using Gradle.

  3. Tag the repo with the version number. e.g. v0.1

  4. 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, Module Planner 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:

  • NUS Computer Science students who :

    • need to manage their modules

    • is familiar with CLI apps

    • prefer typing over using mouse

    • prefer desktop apps over other types

Value proposition: easily plan modules based on graduation requirements

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…​

* * *

CS student

specify my major, focus area and current semester

Get a list of modules I need to take to fulfill requirements

* * *

student

add modules that I have taken

know what other modules I can take next based on the module prerequisites

* * *

student

add modules that I want to take for future semesters

plan my modules for the future semesters

* * *

student

delete modules from plan

remove modules that I choose not to take

* * *

student

see the list of modules

choose what modules I want to take for the next semester

* * *

student

get a summary of my current progress

get a better sense of what I need to do next

* *

student

look up a module

know which semester it is available in

* *

student

look up a module I want to take

get the list of prerequisites for it

Appendix C: Use Cases

(For all use cases below, the System is the ModulePlanner, unless specified otherwise)

Use case: Specify major/focus area

MSS

  1. User requests to specify a major/focus area

  2. System displays a list of modules related to the major/ focus area

    Use case ends.

Extensions

  • 2a. The given input is invalid.

    • 2a1. System shows an error message.

      Use case ends.

Use case: Add modules that have been taken

MSS

  1. User requests to add any number of module codes to the list of modules taken

  2. System shows success message

  3. User requests to see the list of available modules

  4. System shows the list of modules that user can take based on the list of modules taken

    Use case ends.

Extensions

  • 2a. User inputs no module code

    • 2a1. System shows error message

      Use case ends.

  • 2b. User inputs invalid module code(s)

    • 2b1. System shows error message

      Use case ends.

  • 4a. The list is empty

    Use case ends.

Use case: Delete modules

MSS

  1. User requests to see the module plan he/she has made for a specific semester

  2. System shows module plan for the specified semester

  3. User requests to delete any number of module codes from the plan

  4. System shows success message

    Use case ends.

Extensions

  • 2a. The plan is empty

    Use case ends.

  • 2b. The semester is a past semester

    • 2b1. User is told that old modules cannot be changed

      Use case ends.

  • 3a. User inputs no module code

    • 3a1. System shows error message

    • 3a2. System prompts for module code(s)

      Use case ends.

  • 3b. User inputs invalid module code(s)

    • 3b1. System shows error message

    • 3b2. System prompts for valid module code(s)

      Use case ends.

Appendix D: Non Functional Requirements

  1. Should work on any mainstream OS as long as it has Java 9 or higher installed

  2. Should be able to handle at least 80 modules

  3. Should have good documentation

  4. Should be designed to allow for future extensibility

  5. Should be designed well to ease maintainability and be easily tested

  6. Should be scalable to cater to more modules if a second major, degree or the like is taken

Appendix E: Glossary

Mainstream OS

Windows, Linux, Unix, macOS

Time Period

Year-Semester pair

  • year 1 semester 1

  • year 2 semester 2

Iterative Deletion

The process of removing modules, checking if their removal causes other modules to not fulfill some of their prerequisites, removing those modules that no longer have their prerequisites fulfilled, and repeating until no more modules are removed.

Ui Components

The ui is divided into several sections.

UiLabelled
Figure 15. The labelled ui

  • Input Box: input commands here.

  • Result Display: displays command results and other associated messages.

  • Time Period: displays the year and semester you are currently viewing.

  • Taken Modules Panel: lists modules that you put into the specified time period.

  • Suggested Modules Panel: lists modules that suggested to you for that time period.

  • Multipurpose Panel: displays results for the Find and Status commands.

Appendix F: 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.

F.1. Launch and Shutdown

  1. Initial launch

    1. Download the jar file and copy into an empty folder

    2. Double-click the jar file
      Expected: Shows the GUI with no modules. The window size may not be optimum.

  2. 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.

F.2. Saving data

  1. Dealing with missing/corrupted data files

    1. Double-click the jar file. This will generate some supporting files like preferences.json and config.json.

    2. To simulate missing data files, remove any of the generated files. Close the window.

    3. Double click the jar file again.
      Expected: The jar file will automatically generate the relevant files removed. These files contain default values and not custom values set by the user.

    4. To simulate corrupted data files, edit any of the generated files to break the format. The files are in json format and are easily editable. One example edit is to add "BobBuilder" like in the image below.

    5. Expected: The jar file will automatically regenerate the corrupted files. These files contain default values and not custom values set by the user.

CorruptedDataFile