Developer Guide
- Acknowledgements
- Setting up, getting started
- Design
- Implementation
- Documentation, logging, testing, configuration, dev-ops
- Appendix: Requirements
- Appendix: Planned Enhancements
- Appendix: Instructions for manual testing
Acknowledgements
- This project is based on the AddressBook-Level3 project created by the SE-EDU initiative.
- Several features was inspired from common programs and/or other CS2103/T teams projects features.
Setting up, getting started
Refer to the guide Setting up and getting started.
Design
.puml
files used to create diagrams in this document docs/diagrams
folder. Refer to the PlantUML Tutorial at se-edu/guides to learn how to create and edit diagrams.
Architecture
The Architecture Diagram given above explains the high-level design of the App.
Given below is a quick overview of main components and how they interact with each other.
Main components of the architecture
Main
(consisting of classes Main
and MainApp
) is in charge of the app launch and shut down.
- At app launch, it initializes the other components in the correct sequence, and connects them up with each other.
- At shut down, it shuts down the other components and invokes cleanup methods where necessary.
The bulk of the app’s work is done by the following 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.
Commons
represents a collection of classes used by multiple other components.
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
.
execute()
method in fact takes in a CommandString
object that represents a command string,
instead of a literal string. Refer to the implementation detail of “highlight error” feature for
more details.
Each of the four main components (also shown in the diagram above),
- defines its API in an
interface
with the same name as the Component. - implements its functionality using a concrete
{Component Name}Manager
class (which follows the corresponding APIinterface
mentioned in the previous point.
For example, the Logic
component defines its API in the Logic.java
interface and implements its functionality using the LogicManager.java
class which follows the Logic
interface. Other components interact with a given component through its interface rather than the concrete class (reason: to prevent outside component’s being coupled to the implementation of a component), as illustrated in the (partial) class diagram below.
The sections below give more details of each component.
UI component
The API of this component is specified in Ui.java
The UI consists of a MainWindow
that is made up of parts e.g.CommandBox
, ResultDisplay
, PersonListPanel
, StatusBarFooter
etc. All these, including the MainWindow
, inherit from the abstract UiPart
class which captures the commonalities between classes that represent parts of the visible GUI.
The UI
component uses the 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. - keeps a reference to the
Logic
component, because theUI
relies on theLogic
to execute commands. - depends on some classes in the
Model
component, as it displaysPerson
object residing in theModel
.
Logic component
API : Logic.java
Here’s a (partial) class diagram of the Logic
component:
The sequence diagram below illustrates the interactions within the Logic
component, taking execute("delete 1")
API call as an example.
DeleteCommandParser
should end at the destroy marker (X) but due to a limitation of PlantUML, the lifeline continues till the end of diagram.
execute()
method in fact takes in a CommandString
object that represents a command string,
instead of a literal string. Refer to the implementation detail of “highlight error” feature for
more details.
How the Logic
component works:
- When
Logic
is called upon to execute a command, it is passed to anAddressBookParser
object which in turn creates a parser that matches the command (e.g.,DeleteCommandParser
) and uses it to parse the command. - This results in a
Command
object (more precisely, an object of one of its subclasses e.g.,DeleteCommand
) which is executed by theLogicManager
. - The command can communicate with the
Model
when it is executed (e.g. to delete a person).
Note that although this is shown as a single step in the diagram above (for simplicity), in the code it can take several interactions (between the command object and theModel
) to achieve. - The result of the command execution is encapsulated as a
CommandResult
object which is returned back fromLogic
.
Here are the other classes in Logic
(omitted from the class diagram above) that are used for parsing a user command:
XYZCommandParser
, and CommandBox
in UI
component) also depends on CommandPart
to indicate which part of the command causes the error,
however to avoid cluttering the diagram, the dependency is not shown.
How the parsing works:
- When called upon to parse a user command, the
AddressBookParser
class creates anXYZCommandParser
(XYZ
is a placeholder for the specific command name e.g.,AddCommandParser
) which uses the other classes shown above to parse the user command and create aXYZCommand
object (e.g.,AddCommand
) which theAddressBookParser
returns back as aCommand
object. - All
XYZCommandParser
classes (e.g.,AddCommandParser
,DeleteCommandParser
, …) inherit from theParser
interface so that they can be treated similarly where possible e.g, during testing.
Model component
API : Model.java
The Model
component,
- stores the address book data i.e., all
Person
objects (which are contained in aUniquePersonList
object). - stores the currently ‘selected’
Person
objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiableObservableList<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. - stores a
UserPref
object that represents the user’s preferences. This is exposed to the outside as aReadOnlyUserPref
objects. - does not depend on any of the other three components (as the
Model
represents data entities of the domain, they should make sense on their own without depending on other components)
Note: An alternative (arguably, a more OOP) model is given below. It has a Tag
list in the AddressBook
, which Person
references. This allows AddressBook
to only require one Tag
object per unique tag, instead of each Person
needing their own Tag
objects.
Storage component
API : Storage.java
The Storage
component,
- can save both address book data and user preference data in JSON format, and read them back into corresponding objects.
- inherits from both
AddressBookStorage
andUserPrefStorage
, which means it can be treated as either one (if only the functionality of only one is needed). - depends on some classes in the
Model
component (because theStorage
component’s job is to save/retrieve objects that belong to theModel
)
Common classes
Classes used by multiple components are in the seedu.address.commons
package.
Implementation
This section describes some noteworthy details on how certain features are implemented.
Highlight error feature
This feature would automatically highlight (select) the part of the command that contains the error in the command box, so that the user can edit it more quickly.
For example, if the user type edit 1 p/12 c/CS2103T
, since the phone number is invalid (but the course code CS2103T
is valid), then 12
will be highlighted, which speeds up the process of data entry because the user no longer have to press [←]
several times to navigate to 12
.
Implementation
First, many functions that originally takes the command string, will now take CommandString
, which is a class
containing a string.
Compare the old and the new sequence diagram below for the execution of a command. This is the old sequence diagram.
And this is the new sequence diagram.
A class CommandPart
is used to maintain a part of a command. For example, if s
is a CommandString
with value edit 1 p/12 c/CS2103T
, then new CommandPart(s).substring(9, 11)
returns a CommandPart
whose toString()
representation is 12
, but it also remembers the index into the original CommandString
object.
Then, ParseException
and CommandExecutionException
are two exception classes that implements the CommandException
interface. A CommandException
has an getErroneousPart()
method that returns an Optional<CommandPart>
.
When the UI catches a ParseException
or CommandExecutionException
, it will call getErroneousPart()
on the
exception object. If the result is not Optional.empty()
, it will select the corresponding part in the command box.
Various methods in the parser and the command executor is modified to include the correct command part.
For backwards compatibility, not all CommandException
object need to know what part of the command causes the error.
Design considerations
Aspect: How to represent a command string:
-
Alternative 1 (current choice): Name the class
CommandString
.
Aspect: How to represent a part of the command string:
-
Alternative 1 (current choice): Name the class
CommandPart
, and make it specifically only represent a part of a command.- Pros: Descriptive class name.
- Cons: See the pros of alternative 2.
-
Alternative 2: Name the class
StringPart
or equivalent, and make it represent a part of any string.- Pros: Later if the need to maintain a substring with reference to the original string shows up in another part of the code, the class can be reused.
- Cons: See the pros of alternative 1.
Aspect: How to implement common getErroneousPart()
method for the exception classes:
-
Alternative 1 (current choice): Make an interface
CommandException
, which exposesgetErroneousPart()
.- Pros: Caller can call
getErroneousPart()
without checking and casting it toCommandExecutionException
toParseException
. - Cons: Ambiguous semantic. There’s no guarantee a class implementing
CommandException
also extendsException
.
- Pros: Caller can call
-
Alternative 2: Make an abstract class
CommandException
, and make both classes inherit from that.- Pros: Allows a common implementation for
getErroneousPart()
without duplicating the code across classes. - Pros: Allows code to write
catch (CommandException e)
instead ofcatch (ParseException | CommandExecutionException e)
. - Cons:
ParseException
already inherit fromIllegalValueException
, and Java does not allow diamond inheritance.
- Pros: Allows a common implementation for
-
Alternative 3: Same as alternative 2, but make
ParseException
no longer inherit fromIllegalValueException
.- Pros: Same as in alternative 2.
- Cons: Breaks backwards compatibility, because some part of the code may expect
catch (IllegalValueException)
to also catch aParseException
.
Documentation, logging, testing, configuration, dev-ops
Appendix: Requirements
Product scope
Target user profile:
- has a need to manage a significant number of contacts of NUS students, tutors, and professors
- prefer desktop apps over other types
- can type fast
- prefers typing to mouse interactions
- is reasonably comfortable using CLI apps
Value proposition:
- manage contacts faster than a typical mouse/GUI driven app
- allow NUS students to save and search up contacts of students/tutors/instructors and the courses they are in. (e.g. tutorial/lecture groupings)
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 a new contact | |
* * * |
user | delete a contact | remove entries that I no longer need |
* * * |
user | edit a contact | change incorrect or new information about a contact |
* * * |
user | find a contact by name | locate details of contact without having to go through the entire list |
* * * |
user | find a contact by course code | locate contact from a specific course without having to go through the entire list |
* |
user | find a contact by tag | find contacts with similar roles quickly |
* * * |
user | list all contacts | see all contacts at a glance |
* * |
user | undo the previous command | revert the previous action |
* * |
user | redo the previous command | redo the previous action |
* * |
user | tag contacts with custom labels | easily identify their roles in my academic life |
* * |
user | press [↑] to fill the command-line box with previous commands from command history | edit the last-typed erroneous command quickly |
* |
user | share a contact with my classmates | collaborate more easily on group assignments |
* |
user | set reminders to contact instructors before important deadlines | ensure timely communication |
* |
user | rate and review my interactions with instructors | keep track of my personal experiences and preferences |
Use cases
(For all use cases below, the System is the NUSContacts
and the Actor is the user
, unless specified otherwise)
UC1: Add a contact
MSS
- User requests to add a contact
- User provides the contact’s details
-
NUSContacts adds the contact
Use case ends.
Extensions
- 2a. The contact already exists.
-
2a1. NUSContacts informs the user of the error.
Use case ends.
-
UC2: Delete a contact
MSS
- User requests to list tutors
- NUSContacts shows a list of tutors
- User requests to delete a specific contact in the list
-
NUSContacts deletes the contact
Use case ends.
Extensions
-
2a. The list is empty.
Use case ends.
-
3a. The given index is invalid.
-
3a1. NUSContacts shows an error message.
Use case resumes at step 2.
-
UC3: Edit a contact
MSS
- User requests to edit a contact
- User provides the field to edit and the new value
-
NUSContacts edits the contact
Use case ends.
Extensions
- 2a. User provides an empty address for a PROFESSOR.
-
2a1. NUSContacts shows an error message.
Use case resumes at step 2.
-
- 2b. User gives a contact without an address the PROFESSOR role.
-
2b1. NUSContacts shows an error message.
Use case resumes at step 2.
-
- 2c. User provides an invalid index such as -1.
- 2c1. NUSContacts points out where the index is in the command and shows an error message.
Use case resumes at step 2.
- 2d. User provides a phone number that does not conform to the expected format.
- 2d1. NUSContacts points out where the phone number is in the command and shows a warning.
- 2d2. User specify that the warning is to be ignored.
Use case resumes at step 3.
UC4: Find a contact by name
MSS
- User requests to find a contact
- NUSContacts prompts search criterion (name or course code)
- User provides the search criterion (name)
-
NUSContacts shows the contact(s) that match the criterion
Use case ends.
Extensions
- 4a. No contact matches the criterion.
-
4a1. NUSContacts informs the user of the error.
Use case ends.
-
UC5: Find a contact by course code
MSS
- User requests to find a contact
- NUSContacts prompts search criterion (name or course code)
- User provides the search criterion (course code)
-
NUSContacts shows the contact(s) that match the criterion
Use case ends.
Extensions
- 4a. No contact matches the criterion.
-
4a1. NUSContacts informs the user of the error.
Use case ends.
-
UC5: Clear all contacts
MSS
- User requests to clear all contacts
-
NUSContacts clears all contacts
Use case ends.
UC6: Clear all contacts
MSS
- User requests to clear all contacts
-
NUSContacts clears all contacts
Use case ends.
Extensions
- 2a. The contact already exists.
-
2a1. NUSContacts informs the user of the error.
Use case ends.
-
Non-Functional Requirements
- Should work on any mainstream OS as long as it has Java
11
or above installed. - Should be able to hold up to 1000 contacts without a noticeable sluggishness in performance for typical usage.
- A user with above average typing speed for regular English text (i.e. not code, not system admin commands) should be able to accomplish most of the tasks faster using commands than using the mouse.
- Error messages displayed to application window should be easily understood by most users.
- System should respond to user actions within 1 second.
- For databases with less than 1000 contacts, fetching and saving of contacts to/from it should not exceed 200 milliseconds.
- System should handle data corruption or loss without crashing the application.
- System architecture should support future updates and extensions without major restructures.
- System should support comprehensive testing for all components and features.
Glossary
- Mainstream OS: Windows, Linux, Unix, MacOS
- Private contact detail: A contact detail that is not meant to be shared with others
Appendix: Planned Enhancements
Team size: 5
- Currently, if any component (name, email, etc.) is too long, it will be hidden on the screen. We plan to implement appropriate mechanism to show the full component.
- Currently,
undo
only supports undoing one command. We plan to support undoing multiple commands. - Currently, using the
edit
command to edit the tag list will delete all the existing tags and replace it with the new tags. We plan to have ways to edit it incrementally later. - Currently, there’s no way to make
search
more targeted; for example, if there are 3 entries in the address book with nameJohn Doe
,Jane Doe
andJohn Smith
, then there’s no way to search for specificallyJohn Doe
. In the future, we plan to have a way to specify that multiple words must match exactly, and have a priority system where contacts that matches more keywords are shown earlier. - Currently, duplicate phone number and email are not detected. We plan to detect them and warn the user of the error.
- Currently, the result display cannot be resized to view the text in case the text is long. We plan to implement it later.
- Currently, address is mandatory if the role is
Professor
, but some profs/lecture track professors might not have offices. We plan to implement a way to allow user have an empty address forProfessor
by usingf/
. - Currently,
f/
bypasses all invalid field value errors, not one of the errors. We plan to implement a way to bypass one by one.
Appendix: Instructions for manual testing
Given below are instructions to test the app manually.
Launch and shutdown
-
Initial launch
-
Download the jar file and copy into an empty folder.
-
Double-click the jar file.
Expected: Shows the GUI with a set of sample contacts. The window size may not be optimum.
-
-
Saving window preferences
-
Resize the window to an optimum size. Move the window to a different location. Close the window.
-
Re-launch the app by double-clicking the jar file.
Expected: The most recent window size and location is retained.
-
Adding contacts
-
Adding a contact while all contacts are being shown
Prerequisites: All existing contacts are to be cleared using
clear
command. This is to ensure no clashing of contact names while testing.-
Test case:
add n/Joe Bama e/e0123456@u.nus.edu r/STUDENT c/CS2103T a/In the walls p/91234567
Expected: New contact with the specified descriptions added to the list and shown in the application. -
Test case:
add n/Donald Frump e/spammail@gmail.com r/TA c/CS2101
Expected: Similar to previous, except the “phone” and “address” fields now show(no phone number)
and(no address)
respectively. -
Test case:
add n/Hilarious Blipton e/e6969420@u.nus.edu c/DSA1101
Expected: Contact is not added. Error details shown in the status message. -
Test case:
add n/Hilarious Blipton e/FAKEEMAIL r/STUDENT c/DSA1101
Expected: Similar to previous. -
Test case:
add n/Joe Bama e/e0123456@u.nus.edu r/STUDENT c/CS2103T a/In the walls p/91234567
Expected: Similar to previous. (This test must be done after the first test case) -
Test case:
add n/Hilarious Blipton n/Not Elden Clinton e/e6969420@u.nus.edu r/STUDENT c/DSA1101
Expected: Similar to previous. -
Other incorrect add commands to try:
add
,adding ...
,...
.
Expected: Similar to previous.
-
Deleting contacts
-
Deleting a contact while all contacts are being shown
Prerequisites: List all contacts using the
list
command. Multiple contacts already in the list.-
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. -
Test case:
delete 0
Expected: No contact is deleted. Error details shown in the status message. Status bar remains the same. -
Other incorrect delete commands to try:
delete
,delete x
,...
(where x is larger than the current list size).
Expected: Similar to previous.
-
-
Deleting multiple contacts while all contacts are being shown
Prerequisites: List all contacts using the
list
command. Multiple contacts already in the list.-
Test case:
delete 1 2
Expected: No contact is deleted. Error details shown in the status message. Status bar remains the same. -
Test case:
delete 1, 2
Expected: First 2 contacts are deleted from the list. Details of the deleted contacts shown in the status message. Timestamp in the status bar is updated. -
Other incorrect delete commands to try:
delete 1, 0
,delete 1, 3, x
,...
(where x is larger than the current list size)
Expected: Similar to the first test case.
-
Saving data
-
Dealing with missing/corrupted data files
-
Close the application, and delete the data file (if it exists).
-
Re-launch the application.
Expected: The data file is re-created and populated with sample data. -
Close the application, and modify the data to be invalid.
-
Re-launch the application.
Expected: The program reports the data file is corrupted, and start with an empty address list. -
Add some entry into the address book.
Expected: The new data is saved into the save file.
-