Skip to content

Latest commit

 

History

History
476 lines (313 loc) · 18.5 KB

DeveloperGuide.md

File metadata and controls

476 lines (313 loc) · 18.5 KB
Raw

Developer Guide

Setting up

Prerequisites

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

  2. Eclipse IDE

  3. e(fx)clipse plugin for Eclipse (Do the steps 2 onwards given in this page)

  4. Buildship Gradle Integration plugin from the Eclipse Marketplace

Importing the project into Eclipse

  1. Fork this repo, and clone the fork to your computer
  2. Open Eclipse (Note: Ensure you have installed the e(fx)clipse and buildship plugins as given in the prerequisites above)
  3. Click File > Import
  4. Click Gradle > Gradle Project > Next > Next
  5. Click Browse, then locate the project's directory
  6. Click Finish
  • If you are asked whether to 'keep' or 'overwrite' config files, choose to 'keep'.
  • Depending on your connection speed and server load, it can even take up to 30 minutes for the set up to finish (This is because Gradle downloads library files from servers during the project set up process)
  • If Eclipse auto-changed any settings files during the import process, you can discard those changes.

Troubleshooting project setup

Problem: Eclipse reports compile errors after new commits are pulled from Git

  • Reason: Eclipse fails to recognize new files that appeared due to the Git pull.
  • Solution: Refresh the project in Eclipse:
    Right click on the project (in Eclipse package explorer), choose Gradle -> Refresh Gradle Project.

Problem: Eclipse reports some required libraries missing

  • Reason: Required libraries may not have been downloaded during the project import.
  • Solution: Run tests using Gardle once (to refresh the libraries).

Design

Architecture


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

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

  • At app launch: Initializes the components in the correct sequence, and connect them up with each other.
  • At shut down: Shuts down the components and invoke 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.

  • EventsCentre : 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 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.

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

Note how the Model simply raises a DailyPlannerEvent 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.

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.

UI component


API : Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, TaskListPanel, StatusBarFooter, BrowserPanel etc. All these, including the MainWindow, inherit from the abstract UiPart class and they can be loaded using the UiPartLoader.

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.

Logic component


API : Logic.java

  1. Logic uses the Parser 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 person) 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 1") API call.

Model component


API : Model.java

The Model,

  • stores a UserPref object that represents the user's preferences.
  • stores the Daily Planner data.
  • exposes a UnmodifiableObservableList<ReadOnlyTask> 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.

Storage component


API : Storage.java

The Storage component,

  • can save UserPref objects in json format and read it back.
  • can save the Daily Planner data in xml format and read it back.

Common classes

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

Implementation

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

Configuration

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

Testing

Tests can be found in the ./src/test/java folder.

In Eclipse:

  • To run all tests, right-click on the src/test/java folder and choose Run as > JUnit Test
  • To run a subset of tests, you can right-click on a test package, test class, or a test and choose to run as a JUnit test.

Using Gradle:

We have two types of tests:

  1. GUI Tests - These are System Tests that test the entire App by simulating user actions on the GUI. These are in the guitests 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.dailyplanner.commons.UrlUtilTest
    2. Integration tests that are checking the integration of multiple code units (those code units are assumed to be working).
      e.g. seedu.dailyplanner.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.dailyplanner.logic.LogicManagerTest

Headless GUI Testing : 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.
See UsingGradle.md to learn how to run tests in headless mode.

Troubleshooting tests

Problem: Tests fail because NullPointException when AssertionError is expected

  • Reason: Assertions are not enabled for JUnit tests. This can happen if you are not using a recent Eclipse version (i.e. Neon or later)
  • Solution: Enable assertions in JUnit tests as described here.
    Delete run configurations created when you ran tests earlier.

Dev Ops

Build Automation

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

Continuous Integration

We use Travis CI to perform Continuous Integration on our projects. See UsingTravis.md for more details.

Making a Release

Here are the steps to create a new release.

  1. Generate a JAR file using Gradle.
  2. Tag the repo with the version number. e.g. v0.1
  3. Crete a new release using GitHub and upload the JAR file your created.

Managing Dependencies

A project often depends on third-party libraries. For example, Address Book 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 : 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
* * * user add new task find out tasks are urgently due
* * * user set deadlines be reminded of my due dates for my respective tasks
* * * user delete a task remove entries that are completed
* * * user find a task by name search for a task without having to go through the entire list
* * * user edit a task and its particulars update instantly if there are any changes in the task
* * user mark my tasks know which ones are completed and uncompleted
* * user undo my last action amend my mistakes immediately or put lost information back completely
* * user view the tasks take a quick glance or have my tasks presented according to my needs and preference
* * busy user sort my tasks rank the importance and urgency(time and date) of my activities
* advanced user pin my tasks on a new list remind myself which are the tasks that require my constant attention
* advanced user use natural language specify my dates and time without using a fixed format

Appendix B : Use Cases

(For all use cases below, the System is the DailyPlanner and the Actor is the user, unless specified otherwise)

Use case: Add task

MSS

  1. User requests to add task with minimum input TASKNAME
  2. Task Manager adds task and displays the new list of tasks Use case ends.

Extensions

1a. Name of task missing

1a1. Daily Planner shows an error message
Use case resumes back to step 1

1b. Time slot for task is already filled

1b1. Daily Planner warns user that time slot clashes
Use case resumes

1c. Format is invalid

3b1. Daily Planner shows an error message
Use case resumes

Use case: Delete task

MSS

  1. User requests to view tasks for specific time period or completed list
  2. Daily Planner displays all tasks during time period or the completed tasks
  3. User requests to delete a specific task in the list or the clear the completed task list
  4. Daily Planner deletes the task(s) Use case ends

Extensions

2a. The list is empty

Use case ends

3a. Given index is invalid

3b1. Task manager shows error message
Use case resumes at step 2

Use case: Completing task

MSS

  1. User requests to view tasks for specific time period
  2. Daily Planner displays all tasks during time period
  3. User requests to mark a specific task in the list as completed
  4. Daily Planner mark the task as completed Use case ends

Extensions

2a. The list is empty

Use case ends

3a. Given index is invalid

3b1. Task manager shows error message
Use case resumes at step 2

Use case: Pin a task

MSS

  1. User requests to view tasks for specific time period
  2. Task Manager displays all tasks during time period
  3. User requests to pin a specific task in the current schedule list to the pinned list
  4. Task Manager puts the task as on pinned list and displays it there Use case ends

Extensions

2a. The list is empty

Use case ends

3a. Given index is invalid

3b1. Task manager shows error message
Use case resumes at step 2

Use case: Unpin a task

MSS

  1. User refers to the INDEX on the pinned list
  2. User requests to unpin a specific task in the pinned list to the tasks list
  3. Task Manager removes the task from the pinned list Use case ends

Extensions

2a. The list is empty

Use case ends

2a. Given index is invalid

3b1. Task manager shows error message
Use case resumes at step 2

Use case: View task

MSS

  1. User requests to view tasks for specific time period or completed tasks
  2. Task Manager displays all tasks during time period or tasks that are completed

Use case ends

Use case: Edit task

MSS

  1. User requests to list tasks for a specific time period
  2. Task Manager displays all tasks during time period
  3. User requests to edit a specific task in the list
  4. Task manager makes the edits
    Use case ends.

Extensions

2a. The list is empty

Use case ends

3a. The given index is invalid

3a1. Task Manager shows an error message
Use case resumes at step 2

3b. Format is invalid

3b1. Task Manager shows an error message
Use case resumes at step 2


Appendix C : Non Functional Requirements

  1. Should work on any mainstream OS as long as it has Java 1.8.0_60 or higher installed.
  2. Should be able to hold up to 1000 tasks.
  3. Should come with automated unit tests and open source code.
  4. Should favor DOS style commands over Unix-style commands.
  5. Task input should not be more than 200 characters to be concise.

{More to be added}

Appendix D : Glossary

Mainstream OS

Windows, Linux, Unix, OS-X

Private contact detail

A contact detail that is not meant to be shared with others

Appendix E : Product Survey

Our product survey is researched and presented from our client's point of view - Jim does not use cloud-based platforms and prefers to key in his tasks in a single command line to clicking.

Wunderlist Google Calendar Todoist
Strengths
  • Elegant and simple
  • CLI input but graphical display
  • Add notes and timestamps to tasks
  • Ability to create email with list of tasks automatically
  • Organize tasks in different lists
  • Quick add feature to minimize use of mouse
  • Ability to allocate tasks to specific timeslots
  • Ability to view free timeslots
  • Ability to set reminders
  • CLI input but graphical display
  • Keyboard shortcuts to minimize use of mouse
  • Ability to set deadlines and reminders for tasks
  • Ability to set priorities for tasks to decide which task to do next
Irrelevant features
  • Cross-platform functionality
  • Syncs between devices
  • Collaboration with others
  • Collaboration with others
  • Cross-platform functionality
  • Collaboration with others
Weaknesses
  • No way to allocate tasks to a specific timeslot
  • No way to view free timeslots
  • Does not provide a desktop software for easy summoning using keyboard shortcuts
  • No easy way to block multiple timeslots when the exact timing of a task is uncertain and release the blocked slots when the time is finalized
  • Not good with capturing tasks that need to be done before a specific date/time, or after a specific date/time, and items without specific times
  • No support for offline access
  • No way to allocate tasks to a specific timeslot
  • No way to view free timeslots