By: Team CS2103-AY1819S2-W16-2      Since: Mar 2019      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.

  9. Open MainWindow.java and check for any code errors

    1. Due to an ongoing issue with some of the newer versions of IntelliJ, code errors may be detected even if the project can be built and run successfully

    2. To resolve this, place your cursor over any of the code section highlighted in red. Press ALT+ENTER, and select Add '--add-modules=…​' to module compiler options for each error

  10. Repeat this for the test folder as well (e.g. check HelpWindowTest.java for code errors, and if so, resolve it the same way)

1.3. Verifying the setup

  1. Run the seedu.address.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

If you plan to develop this fork as a separate product, 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, get some sense of the overall design by reading Section 2.1, “Architecture”.

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. The following class plays an important role at the architecture level:

  • 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

How the architecture components interact with each other

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

SDforDeletePerson
Figure 3. Component interactions for delete 1 command

The sections below give more details of each component.

2.2. UI component

UiClassDiagram
Figure 4. Structure of the UI Component

API : Ui.java

The UI consists of a MainWindow that is made up of parts e.g.CommandBox, ResultDisplay, PinListPanel, PersonListPanel, ArchiveListPanel, StatusBarFooter, BrowserPanel 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.

  • Listens for changes to Model data so that the UI can be updated with the modified data.

2.3. Logic component

LogicClassDiagram
Figure 5. Structure of the Logic Component

API : Logic.java

  1. Logic uses the AddressBookParser 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).

  4. The result of the command execution is encapsulated as a CommandResult object which is passed back to the Ui.

  5. In addition, the CommandResult object can also instruct the Ui to perform certain actions, such as displaying help to the user.

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

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

2.4. Model component

ModelClassDiagram
Figure 7. Structure of the Model Component

API : Model.java

The Model,

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

  • stores the Address Book, Archive Book and Pin Book data as 3 separate instances of the AddressBook class.

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

As a more OOP model, we can store a Tag list in Address Book, which Property can reference. This would allow Address Book to only require one Tag object per unique Tag, instead of each Property needing their own Tag object. An example of how such a model may look like is given below.

ModelClassBetterOopDiagram

2.5. Storage component

StorageClassDiagram
Figure 8. 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 json format and read it back.

  • can save the Archive Book data in json format and read it back.

  • can save the Pin Book data in json format and read it back.

  • maintains separate data files for each of the books.

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. Transformation of AddressBook4 to The Real App

3.1.1. Current Implementation

To allow The Real App to store client contact and property information, the model of AB4 must be modified. The Person class has been modified to only contain the following 4 information:

  • Name — Encapsulates the name of a client in the model.

  • Phone — Encapsulates the phone of a client in the model.

  • Email — Encapsulates the email of a client in the model.

  • Remark — Encapsulates the remark associated with a client in the model.

The Person class has also been extended to the following 4 sub-classes to encapsulate the customer type and related information:

  • Buyer — Represents a client who is a buyer in the model.

  • Seller — Represents a client who is a seller in the model, contains additional property information.

  • Tenant — Represents a client who is a tenant in the model.

  • Landlord — Represents a client who is a landlord in the model, contains additional property information.

The abstraction of the property information is done through a Property class. The Property class encapsulates property information through the following 3 classes:

  • Address — Encapsulates the address of a property in the model.

  • Price — Encapsulates the price of a property in the model.

  • Tag — Encapsulates short keywords associated with a property in the model.

There are 2 ways through which client information can be added into the model. One is through user input in the add command, the other is through reading the storage json files at launch.

Given below is an example scenario of how client information can be added into the model via the 2 ways described above.

From storage

Step 1. The user launches the application.

Step 2. MainApp will find the addressbook, archivebook and pinbook json files in the data folder and get them as JsonAddressBookStorage objects.

Step 3. The JsonAddressBookStorage objects are used to initialise StorageManager.

Step 4. The MainApp calls initModelManager method which will eventually return a ModelManager object.

Step 5. To build the model, the StorageManager will build three AddressBook objects which are collections of all the Person objects stored in the addressbook, archivebook and pinbook json files.

Step 6. The three AddressBook objects are used to initialise the ModelManager, which creates the model.

The following sequence diagram summarizes how the model is created from json files when a user launches The Real App:

LaunchSequenceDiagram

Through add command

Step 1. The user launches the application.

Step 2. The user enters the add command with the correct parameters into the Command Box.
e.g. add c/seller n/James Tan p/97652456 e/jamestan@example.com r/need to sell by April 2018 a/Blk 345 Clementi Ave 5, #04-04, S120345 sp/500000 t/MRT t/newlyRenovated

Step 3. The LogicManager handles the user input and creates an AddCommand object.

Step 4. The AddCommand object is executed by the LogicManager.

Step 5. The ModelManager updates the model to add the contact into the AddressBook.

The following sequence diagram summarizes how a contact is added to the AddressBook using the add command:

AddSequenceDiagram

3.1.2. Other Improvements

To allow for modification and retrieval of information, the edit and search commands have been expanded to fit the new model.

Edit command

Edit command has been improved to handle the different types of contacts safely. Object type checking is done during the execution of the command to ensure that only the correct information associated with the customer type is edited. This also ensures that the returned object is the same class as the original object being edited.

Search command

The original find command in AB4 has been renamed to search command to better reflect its new functionality. search command can now search through multiple information fields to look for matches to the input keywords. This allows users to quickly retrieve contacts using whatever limited information they may have at hand.

3.1.3. Design Considerations

Aspect: Abstraction of different customer types

  • Alternative 1 (current choice): The four customer types are abstracted as sub-classes which extends the Person class

    • Pros: Allows for subclass polymorphism.

    • Cons: Legacy code from AB4 is not optimised for runtime polymorphism.

  • Alternative 2: Encapsulate customer type information in Person class using a CustomerType class.

    • Pros: Easy to implement.

    • Cons: Requires rigorous checking of customer type to ensure each contact is handled appropriately.

  • Alternative 3: Refactor Person class into an abstract class and extend the 4 subclasses from it

    • Pros: Prevents the initialisation of a Person object, which is not required in our application.

    • Cons: Much of the legacy code of AB4 has strong dependence on the instantiation of the Person objects.

3.2. Undo/Redo feature

3.2.1. Current Implementation

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

  • VersionedAddressBook#commit() — Saves the current address book state in its history.

  • VersionedAddressBook#undo() — Restores the previous address book state from its history.

  • VersionedAddressBook#redo() — Restores a previously undone address book state from its history.

These operations are exposed in the Model interface as Model#commitAddressBook(), Model#undoAddressBook() and Model#redoAddressBook() respectively.

The archiveBook and pinBook use the VersionedAddressBook as well to facilitate the undo/redo mechanism by running in parallel with addressBook.

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 VersionedAddressBook will be initialized with the initial address book state, and the currentStatePointer pointing to that single address book state.

UndoRedoStartingStateListDiagram

Step 2. The user executes delete 5 command to delete the 5th person in the address book. The delete command calls Model#commitAddressBook(), causing the modified state of the address book after the delete 5 command executes to be saved in the addressBookStateList, and the currentStatePointer is shifted to the newly inserted address book state.

UndoRedoNewCommand1StateListDiagram

Step 3. The user executes add n/David …​ to add a new person. The add command also calls Model#commitAddressBook(), causing another modified address book state to be saved into the addressBookStateList.

UndoRedoNewCommand2StateListDiagram
If a command fails its execution, it will not call Model#commitAddressBook(), so the address book state will not be saved into the addressBookStateList.

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

UndoRedoExecuteUndoStateListDiagram
If the currentStatePointer is at index 0, pointing to the initial address book state, then there are no previous address book states to restore. The undo command uses Model#canUndoAddressBook() 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#redoAddressBook(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the address book to that state.

If the currentStatePointer is at index addressBookStateList.size() - 1, pointing to the latest address book state, then there are no undone address book states to restore. The redo command uses Model#canRedoAddressBook() 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 address book, such as list, will usually not call Model#commitAddressBook(), Model#undoAddressBook() or Model#redoAddressBook(). Thus, the addressBookStateList remains unchanged.

UndoRedoNewCommand3StateListDiagram

Step 6. The user executes clear, which calls Model#commitAddressBook(). Since the currentStatePointer is not pointing at the end of the addressBookStateList, all address book states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add n/David …​ 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.2.2. Design Considerations

Aspect: How undo & redo executes

  • Alternative 1 (current choice): Saves the entire address book.

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

  • Alternative 1 (current choice): Use a list to store the history of address book 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 VersionedAddressBook.

  • 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.3. Pin/Unpin feature

This feature allows users to move person between contact list and pin list. To use this feature, the user need to enter pin or unpin command, with the INDEX(in the contact list and pin list) of the contact to be pinned/unpinned.

  • pin 2

The command above put the 2nd contact in the contact list to the topped pin list.

  • unpin 1

The command above put the 1st contact in the pin list back to the contact list.

What’s more, it also allow users to select some contact in the pin list and display address location on the Google Maps™ browser window. To use this feature, the users need to enter pinselect command, with the INDEX(in the pin list) of the contact to be selected.

  • pinselect 3

The command above will select the 3rd contact in the pin list and the address location is displayed on the Google maps™ browser window.

3.3.1. Current Implementation

This section explains the implementation of all pin related features.

Pin/Unpin

The following sequence diagram shows how the pin operation works:

PinUnpinSequenceDiagram

  • The command is recognized by parserCommand() and an PinCommandParser is created, then a PinCommand object is created with the parsed index.

  • The command object is then executed by Logic and pinPerson is called from the PinCommand object. Then pinPerson will call ModelManager to create two VersionedAddressBook object: versionedPinBook and versionedAddressBook.

  • The versionedPinBook call addPerson() and the versionedAddressBook call removePerson().

  • Both objects will call commit() after execution.

The unpin command does the opposite — it calls removePerson() of the versionedPinBook and addPerson() of the versionedAddressBook instead.

PinSelect

The pinselect command is implemented the same as select.

When pin and unpin are performed, the pinned/unpinned contact is being selected automatically.

3.3.2. Design Considerations

Aspect: How pin & unpin executes

  • Alternative 1 (current choice): Saves the entire address book and pin book.

    • Pros: Easy to implement.

    • Cons: May have performance issues in terms of memory usage.

  • Alternative 2 (current choice): Commands excepts pin, unpin, pinselect command doesn’t work on the pinned person.

    • Pros: Easy to implement.

    • Cons: Users must filter pin list contacts' information through eyes.

Aspect: How undo & redo executes

  • Alternative 1 (current choice): Saves the entire address book and pin book.

    • Pros: Easy to implement.

    • Cons: May have performance issues in terms of memory usage.

3.4. Archive features

3.4.1. Current Implementation

This section explains the implementation of all archive related features.

To implement the archive features, an archiveBook is created in the Model and Storage to facilitate the archiving of contacts. The archiveBook implements the AddressBook class in the Model since it works similarly, and has its own ArchiveBookStorage class in the Storage to facilitate the storage of a separate data file.

Archive/Unarchive

The following sequence diagram shows how the archive command operation works:

ArchiveSequenceDiagram

The unarchive command does the opposite — it calls addPerson(p) of the versionedAddressBook and removePerson(p) of the versionedArchiveBook instead.

Archive List

The archivelist command displays the list of persons in the archiveBook. This has to be carefully implemented to work hand-in-hand with the list of persons in the addressBook, as well as the list command.

More importantly, to have a separate archive list that can be swapped back and forth with the main list in the UI display requires careful designs and implementations in the Logic and Ui components.

Archive Select

The archiveselect command is implemented the same as 'select'.

When unarchive is performed on a person that has been selected by archiveselect, archiveselect is set to be null, so no person will be selected.

Archive Clear

The archiveclear command is implemented the same as clear where a new empty archiveBook is created by calling Model#setArchiveBook(new AddressBook()).

3.4.2. Design Considerations

3.5. Select feature

3.5.1. Current Implementation

The select feature requires careful implementation:

  • As there are 3 separate lists (main contact list, archive list, pin list) that can be selected from, having a unique command for each list (i.e. select, archiveselect, pinselect) ensures that the person is selected from the correct list.

  • Only at most 1 person can be selected at any point in time from each list.

    • However, having 3 separate lists means that there will be overlapping selections which will cause errors in the Ui component in displaying the browser panel.

    • To avoid overlapping of selections from each of the select commands, previous selections from another list are set to null.

  • Adding and editing a person will select that person.

  • Deleting, archiving and unarchiving a selected contact will set the selection to null.

  • Changing lists will set the selected person in the list that is swapped away to be set to null.

  • Selection of a pinned person will remain regardless of which of the two lists are displayed.

3.6. 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.7, “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.7. Configuration

Certain properties of the application can be controlled (e.g user prefs file location, 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 9. 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, AboutUs, ContactUs

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.

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.address.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.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, 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, The Real App depends on the Jackson library for JSON parsing. Managing these dependencies can be automated using Gradle. For example, Gradle can download the dependencies automatically, which is better than these alternatives:

  1. Include those libraries in the repo (this bloats the repo size)

  2. Require developers to download those libraries manually (this creates extra work for developers)

Appendix A: Product Scope

Target User Profile:

  • manage buying/selling/leasing of properties

  • has a need to manage a significant number of contacts

  • has a need to maintain an accurate record of property addresses

  • has a need to store essential information of properties

  • prefer desktop apps over other types

  • can type fast

  • prefers typing over mouse input

  • is reasonably comfortable using CLI apps

Value Proposition:

  • What problem does this product solve?
    This product aims to help real estate agents manage large amount of customer and property information within the same app. The app will also help to safeguard the sensitive information through encryption.

  • How does it make the the user’s life easier?
    With a proper address book app, real estate agents can quickly and conveniently search for their customers’ contact details, as well as essential property information to speed up their business process.

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

* * *

real estate agent

add a new contact with contact and associated property details

record an entry of the contact and the associated property

* * *

clean user

delete a contact

remove entries that I no longer need

* * *

efficient user

search for a contact by using any details (e.g. name/phone/tags etc.)

locate details of contacts without having to go through the entire list

* * *

real estate agent

add property information to each contact

link my customers to the property that they buying/selling/renting

* * *

real estate agent

search and filter contacts by the address of their associated property

find all properties within the same area, e.g. search for "Woodlands" should return all contacts with "Woodlands" in their address

* * *

real estate agent

add and update financial information of properties that can be bought/sold/rented

use the information to better determine which properties to buy/sell based on price, and match customers who are looking for certain prices

* * *

organised user

categorise my contacts into different groups (i.e. buyers, sellers, landlords, tenants)

keep track of my customers better

* * *

clean user

archive contacts when I currently do not need them

keep contacts for later use

* * *

efficient user

see the list of contacts which I have archived

check which contacts I have in my archive

* * *

real estate agent

unarchive contacts

retrieve contacts which I need again

* * *

forgetful user

pin important contacts to the top of the lists

see which contacts are the most important for me to attend to

* * *

efficient user

unpin contacts from the top of the lists when they are no longer of priority

focus on the other important contacts which have not yet been attended to

* * *

user who prefers visuals

select a contact and see the address (if any) of the contact on the Google Map applet within the app

visualise the location of the property and search for directions to the location

* *

sloppy user

add and edit a contact in the app without having to specify certain information (i.e. some fields are optional)

add and edit a contact even if I do not have the complete contact information

* *

forgetful user

add rental period information for tenants

be reminded when the rental agreement is expiring

* *

efficient user

display contacts sorted by specific categories

locate contacts and/or properties easily

* *

efficient user

search and filter by financial information of properties

see which properties can meet my customers' expectation, as well as my own, in terms of price

* *

efficient user

check all my properties sorted in ascending or descending order by price or size

compare across my properties to buy/sell based on price or size

* *

real estate agent

link sellers to buyers, and landlords to tenants through properties

see all customers linked to a certain property

* *

efficient user

search for properties with address within a 1 km radius of a specific address

filter out properties near a given location

*

responsible user

password-protect the app and/or encrypt individual data

protect my contacts' personal information from access by unauthorised people

*

efficient user

link multiple properties for each contact

keep track of all the properties linked to a contact

*

lazy user

send automated email and/or SMS reminder notifications to my customers

do not have to send individual notifications manually

*

lazy user

have the app start on boot up and minimise to tray

have the app open at all times without having to open it manually all the time

*

real estate agent

search online for current market trends and prices of properties similar to mine

check the competitiveness of my properties to make improvements on my properties and make adjustments to my prices

*

user who prefers visuals

upload and store photos of a specific property

view the property on-the-go

Appendix C: Use Cases

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

Use case: View help

MSS

  1. User requests to view help.

  2. TheRealApp displays the User Guide.

    Use case ends.

Use case: Add contact

MSS

  1. User requests to add contact, with any additional information.

  2. TheRealApp adds contact into the contact list and displays the added contact in the displayed contact list.

    Use case ends.

Extensions

  • 1a. A field is invalid.

    • 1a1. The RealApp shows an error message.

      Use case resumes at step 1.

  • 1b. The list displayed is invalid.

    • 1b1. TheRealApp shows an error message.

    • 1b2. User requests for the valid list.

    • 1b3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Display contact list

MSS

  1. User requests to list contacts.

  2. TheRealApp shows a list of contacts.

    Use case ends.

Extensions

  • 1a. The contact list is empty.

    Use case ends.

Use case: Select contact

MSS

  1. User requests to select a contact.

  2. TheRealApp selects the contact and shows the information of the contact.

    Use case ends.

Extensions

  • 1a. The given index is invalid.

    • 1a1. TheRealApp shows an error message.

      Use case resumes at step 1.

  • 1b. The list displayed is invalid.

    • 1b1. TheRealApp shows an error message.

    • 1b2. User requests for the valid list.

    • 1b3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Display contact list sorted in a specific category

MSS

  1. User requests to list contacts sorted in a specific category.

  2. TheRealApp shows a list of contacts sorted in the requested category.

    Use case ends.

Extensions

  • 1a. The contact list is empty.

    Use case ends.

  • 1b. The category is invalid.

    • 1b1. TheRealApp shows an error message.

      Use case resumes at step 1.

  • 1c. The list displayed is invalid.

    • 1c1. TheRealApp shows an error message.

    • 1c2. User requests for the valid list.

    • 1c3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Search for contact

MSS

  1. User requests to search for a contact by entering keyword(s).

  2. TheRealApp shows a list of contacts with information containing the keywords(s).

    Use case ends.

Extensions

  • 1a. The keyword(s) is invalid.

    • 1a1. The RealApp shows an error message.

      Use case resumes from step 1.

  • 1b. The list displayed is invalid.

    • 1b1. TheRealApp shows an error message.

    • 1b2. User requests for the valid list.

    • 1b3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Edit contact

MSS

  1. User requests to edit a contact, with new information.

  2. TheRealApp edits the contact in the contact list and displays the edited contact in the displayed contact list.

    Use case ends.

Extensions

  • 1a. A field is invalid.

    • 1a1. The RealApp shows an error message.

      Use case resumes at step 1.

  • 1b. The given index is invalid.

    • 1b1. TheRealApp shows an error message.

      Use case resumes at step 1.

  • 1c. The list displayed is invalid.

    • 1c1. TheRealApp shows an error message.

    • 1c2. User requests for the valid list.

    • 1c3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Match contacts

MSS

  1. User requests to list contacts.

  2. TheRealApp shows a list of contacts.

  3. User requests to match 2 contacts in the list.

  4. TheRealApp links the 2 contact.

    Use case ends.

Extensions

  • 2a. The contact list is empty.

    Use case ends.

  • 3a. The given index is invalid.

    • 3a1. TheRealApp shows an error message.

      Use case resumes at step 3.

  • 3b. The 2 contacts are not matchable.

    • 3b1. TheRealApp shows an error message.

      Use case resumes at step 3.

Use case: Delete contact

MSS

  1. User requests to list contacts.

  2. TheRealApp shows a list of contacts.

  3. User requests to delete a specific contact in the list.

  4. TheRealApp deletes the contact.

    Use case ends.

Extensions

  • 2a. The contact list is empty.

    Use case ends.

  • 3a. The given index is invalid.

    • 3a1. TheRealApp shows an error message.

      Use case resumes at step 3.

Use case: Clear contact list

MSS

  1. User requests to clear the contact list.

  2. TheRealApp clears the entire contact list.

    Use case ends.

  • 1a. The list displayed is invalid.

    • 1a1. TheRealApp shows an error message.

    • 1a2. User requests for the valid list.

    • 1a3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Pin contact

MSS

  1. User requests to list contacts.

  2. TheRealApp shows a list of contacts.

  3. User requests to pin a specific contact in the list.

  4. TheRealApp pins the contact.

    Use case ends.

Extensions

  • 2a. The contact list is empty.

    Use case ends.

  • 3a. The given index is invalid.

    • 3a1. TheRealApp shows an error message.

      Use case resumes at step 3.

  • 3b. There are already 5 contacts in the pinned list.

    • 3b1. TheRealApp shows an error message.

      Use case ends.

Use case: Unpin contact

MSS

  1. User requests to unpin a specific pinned contact in the pinned list.

  2. TheRealApp unpins the contact.

    Use case ends.

Extensions

  • 1a. The pinned list is empty.

    Use case ends.

  • 1b. The given index is invalid.

    • 1b1. TheRealApp shows an error message.

      Use case resumes at step 1.

  • 1c. The list displayed is invalid.

    • 1c1. TheRealApp shows an error message.

    • 1c2. User requests for the valid list.

    • 1c3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: select pinned contact

MSS

  1. User requests to select an pinned contact.

  2. TheRealApp selects the contact and shows the information of the pinned contact.

    Use case ends.

Extensions

  • 1a. The given index is invalid.

    • 1a1. TheRealApp shows an error message.

      Use case resumes at step 1.

Use case: Archive contact

MSS

  1. User requests to list contacts.

  2. TheRealApp shows a list of contacts.

  3. User requests to archive a specific contact in the list.

  4. TheRealApp archives the contact.

    Use case ends.

Extensions

  • 2a. The contact list is empty.

    Use case ends.

  • 3a. The given index is invalid.

    • 3a1. TheRealApp shows an error message.

      Use case resumes at step 3.

Use case: Display archived contact list

MSS

  1. User requests to list archived contacts.

  2. TheRealApp shows a list of archived contacts.

    Use case ends.

Extensions

  • 1a. The archived contact list is empty.

    Use case ends.

Use case: Select archived contact

MSS

  1. User requests to select an archived contact.

  2. TheRealApp selects the contact and shows the information of the archived contact.

    Use case ends.

Extensions

  • 1a. The given index is invalid.

    • 1a1. TheRealApp shows an error message.

      Use case resumes at step 1.

  • 1b. The list displayed is invalid.

    • 1b1. TheRealApp shows an error message.

    • 1b2. User requests for the valid list.

    • 1b3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Search for archived contact

MSS

  1. User requests to search for an archived contact by entering keyword(s).

  2. TheRealApp shows a list of archived contacts with information containing the keywords(s).

    Use case ends.

Extensions

  • 1a. The keyword(s) is invalid.

    • 1a1. The RealApp shows an error message.

      Use case resumes from step 1.

  • 1b. The list displayed is invalid.

    • 1b1. TheRealApp shows an error message.

    • 1b2. User requests for the valid list.

    • 1b3. TheRealApp displays the requested list.

      Use case resumes at step 1.

Use case: Unarchive contact

MSS

  1. User requests to list archived contacts.

  2. TheRealApp shows a list of archived contacts.

  3. User requests to unarchive a specific contact in the archived list.

  4. TheRealApp unarchives the contact.

    Use case ends.

Extensions

  • 2a. The archived contact list is empty.

    Use case ends.

  • 3a. The given index is invalid.

    • 3a1. TheRealApp shows an error message.

      Use case resumes at step 3.

Use case: Clear archived contact list

MSS

  1. User requests to clear the archived contact list.

  2. TheRealApp clears the entire archived contact list.

    Use case ends.

    • 1a. The list displayed is invalid.

      • 1a1. TheRealApp shows an error message.

      • 1a2. User requests for the valid list.

      • 1a3. TheRealApp displays the requested list.

        Use case resumes at step 1.

Use case: View history

MSS

  1. User requests to view the history of previous commands.

  2. TheRealApp displays a history of previous commands in reverse chronological order.

    Use case ends.

Extensions

  • 1a. The history list is empty.

    Use case ends.

Use case: Undo

MSS

  1. User requests to undo the previous undoable command.

  2. TheRealApp undoes the previous undoable command.

    Use case ends.

Extensions

  • 1a. There is no previous undoable command.

    Use case ends.

Use case: Redo

MSS

  1. User requests to redo the previous undo.

  2. TheRealApp redoes the undo.

    Use case ends.

Extensions

  • 1a. There is no previous undo command.

    Use case ends.

Use case: Exit app

MSS

  1. User requests to exit the app.

  2. TheRealApp requests to confirm the exit.

  3. User confirms the exit.

    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 hold up to 1000 persons without a noticeable sluggishness in performance for typical usage.

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

Appendix E: Glossary

Mainstream OS

Windows, Linux, Unix, OS-X

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 a set of sample contacts. 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. Adding a client

  1. Adding a client to the app.

    1. Prerequisite: The app must be launched and the client does not already exist in the database.

    2. Test case: add c/seller n/James Tan p/97652456 e/jamestan@example.com r/need to sell by April 2018 a/Blk 345 Clementi Ave 5, #04-04, S120345 sp/500000 t/MRT t/newlyRenovated
      Expected: A new contact appears at the end of the contact list with all the relevant information added. Address location of the added contact is displayed on the Google Maps™ window panel(if applicable).

    3. Test case: add c/buyer n/James Ho e/jamesho@example.com r/looking for 3-room apartment
      Expected: Contact cannot be added as there are missing parameters. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect add commands to try: add c/seller p/86567123, add c/buyer n/James Ho. Expected: Similar to previous.

F.3. Edit a contact

  1. Editing an existing contact in the app.

    1. Prerequisite: The app must be launched and there are contacts currently in the database.

    2. Test case: edit x n/James Han e/jameshan@example.com r/looking for houses in Woodlands (where x is the index of a buyer contact)
      Expected: The buyer contact as index x will be edited with new name James Han, new email jameshan@example.com and new remark looking for houses in Woodlands. Other information remains the same.

    3. Test case: edit x n/James Li e/jamesli@example.com sp/450000 t/ (where x is the index of a contact who is not a seller)
      Expected: Contact cannot be edited as there are parameters that are not applicable to this customer type. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect edit commands to try: edit n/James, edit 1. Expected: Invalid command format.

F.4. Edit a contact

  1. Searching for a contact in the app.

    1. Prerequisite: The app must be launched and there are contacts currently in the database.

    2. Test case: search James
      Expected: The contact list will be updated to display all contacts with information matching the keyword james.

    3. Test case: search &$%$ Expected: No contacts listed as &$%$ does not match any of the valid information field in a contact.

    4. Other incorrect search commands to try: `search `. Expected: Invalid command format.

F.5. Edit a contact

  1. Searching for an archived contact in the app.

    1. Prerequisite: The app must be launched and the archive contact list view is active with existing archived contacts..

    2. Test case: archivesearch James
      Expected: The archive contact list will be updated to display all archived contacts with information matching the keyword james.

    3. Test case: archivesearch &$%$ Expected: No archived contacts listed as &$%$ does not match any of the valid information field in a contact.

    4. Other incorrect archivesearch commands to try: `archivesearch `. Expected: Invalid command format.

F.6. Deleting a person

  1. Deleting a person while all persons are listed

    1. Prerequisites: List all persons using the list command. Multiple persons 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 person is deleted. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect delete commands to try: delete, delete one, delete x (where x is larger than the list size), delete n (where n is a name of an existing contact), delete ., delete list
      Expected: Similar to previous.

F.7. Selecting a person

  1. Selecting a person while all persons are listed

    1. Prerequisites: List all persons using the list command. Multiple persons in the list.

    2. Test case: select 2
      Expected: 2nd contact in the list is selected. Address location of the selected contact is displayed on the Google Maps™ browser window panel (if applicable).

    3. Test case: select 0
      Expected: No person is selected. Error details shown in the status message.

    4. Other incorrect select commands to try: select, select one, select x (where x is larger than the list size), select n (where n is a name of an existing contact), select .
      Expected: Similar to previous.

  2. Selecting a person from a search command result

    1. Prerequisites: Enter list. Search for persons using the search command. Persons that match the search are displayed in the list.

    2. Test case: select 1
      Expected: 1st contact in the list is selected. Address location of the selected contact is displayed on the Google Maps™ browser window panel (if applicable).

    3. Test case: select 0
      Expected: No person is selected. Error details shown in the status message.

    4. Other incorrect select commands to try: select, select one, select x (where x is larger than the list size), select n (where n is a name of an existing contact), select .
      Expected: Similar to previous.

F.8. Archiving a person

  1. Archiving a person while all persons are listed

    1. Prerequisites: List all persons using the list command. Multiple persons in the list.

    2. Test case: archive 2
      Expected: 2nd contact in the list is selected. Details of the archived contact shown in the status message. Timestamp in the status bar is updated.

    3. Test case: archive 0
      Expected: No person is archived. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect archive commands to try: archive, archive one, archive x (where x is larger than the list size), archive n (where n is a name of an existing contact), archive .
      Expected: Similar to previous.

  2. Archiving a person from a search command result

    1. Prerequisites: Enter list. Search for persons using the search command. Persons that match the search are displayed in the list.

    2. Test case: archive 1
      Expected: 1st contact in the list is archived. Details of the archived contact shown in the status message. Timestamp in the status bar is updated.

    3. Test case: archive 0
      Expected: No person is archived. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect archive commands to try: archive, archive one, archive x (where x is larger than the list size), archive n (where n is a name of an existing contact), archive .
      Expected: Similar to previous.

F.9. Selecting an archived person

  1. Selecting a person while all archived persons are listed

    1. Prerequisites: List all archived persons using the archivelist command. Multiple persons in the list.

    2. Test case: archiveselect 2
      Expected: 2nd contact in the list is selected. Address location of the selected contact is displayed on the Google Maps™ browser window panel (if applicable).

    3. Test case: archiveselect 0
      Expected: No person is selected. Error details shown in the status message.

    4. Other incorrect archiveselect commands to try: archiveselect, archiveselect one, archiveselect x (where x is larger than the list size), archiveselect n (where n is a name of an existing archived contact), archiveselect .
      Expected: Similar to previous.

  2. Selecting a person from an archivesearch command result

    1. Prerequisites: Enter archivelist. Search for archived persons using the archivesearch command. Persons that match the search are displayed in the list.

    2. Test case: archiveselect 1
      Expected: 1st contact in the list is selected. Address location of the selected contact is displayed on the Google Maps™ browser window panel (if applicable).

    3. Test case: archiveselect 0
      Expected: No person is selected. Error details shown in the status message.

    4. Other incorrect archiveselect commands to try: archiveselect, archiveselect one, archiveselect x (where x is larger than the list size), archiveselect n (where n is a name of an existing archived contact), archiveselect .
      Expected: Similar to previous.

F.10. Unarchiving a person

  1. Unrchiving a person while all archived persons are listed

    1. Prerequisites: List all archived persons using the archivelist command. Multiple persons in the list.

    2. Test case: unarchive 2
      Expected: 2nd contact in the list is unarchived. Details of the unarchived contact shown in the status message. Timestamp in the status bar is updated.

    3. Test case: unarchive 0
      Expected: No person is unarchived. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect unarchive commands to try: unarchive, unarchive x (where x is larger than the list size), unarchive n (where n is a name of an existing contact), unarchive .
      Expected: Similar to previous.

  2. Unarchiving a person from an archivesearch command result

    1. Prerequisites: Enter archivelist. Search for archived persons using the archivesearch command. Persons that match the search are displayed in the list.

    2. Test case: unarchive 1
      Expected: 1st contact in the list is unarchived. Details of the unarchived contact shown in the status message. Timestamp in the status bar is updated.

    3. Test case: unarchive 0
      Expected: No person is unarchived. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect unarchive commands to try: unarchive, unarchive x (where x is larger than the list size), unarchive n (where n is a name of an existing contact), unarchive .
      Expected: Similar to previous.

F.11. Pinning a person

  1. Pinning a person from contact list to pin list.

    1. Prerequisite: There are multiple persons in the contact list.

    2. Test case: pin 3
      Expected: Third contact in the contact list is put to the pin list. Address location of the pinned contact is displayed on the Google Maps™ window panel(if applicable).

    3. Test case: pin 0
      Expected: No person is pinned. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect unpin commands to try: pin, pin x(where x is larger than the contact list size) Expected: Similar to previous.

F.12. Unpinning a person

  1. Unpinning a person from pin list to contact list.

    1. Prerequisite: There are multiple persons in the pin list.

    2. Test case: unpin 1
      Expected: First contact in the pin list is put back to the contact list. Address location of the unpinned contact is displayed on the Google Maps™ window panel(if applicable).

    3. Test case: unpin 0
      Expected: No person is unpinned. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect unpin commands to try: unpin, unpin x(where x is larger than the pin list size) Expected: Similar to previous.

F.13. Selecting a person in the pin list

  1. Selecting a person in the pin list

    1. Prerequisite: There are multiple persons in the pin list.

    2. Test case: pinselect 2
      Expected: Second contact in the pin list is selected. Address location of the selected contact is displayed on the Google Maps™ window panel(if applicable).

    3. Test case: pinselect 0
      Expected: No person is selected. Error details shown in the status message. Status bar remains the same.

    4. Other incorrect pinselect commands to try: pinselect, pinselect x(where x is larger than the pin list size) Expected: Similar to previous.