Mobilize - Developer Guide

Make sure you have the following before getting started:

Follow these steps to get started:

To verify that the project has been set up correctly:

The Architecture Diagram given below displays the high-level design of the Application.

Figure 2.1.1 : Architecture Diagram

Given below is a quick overview of each component:

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

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

The rest of the Application consists of four components.

Each of the four components:

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

Figure 2.1.2 : Class Diagram of the Logic Component

The events-driven nature of the design enables events to be 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 Sequence Diagram below illustrates an example, showing how the components interact for the scenario where the user issues the command delete 1.

Figure 2.1.3a : Component interactions for delete 1 command (part 1)

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

Figure 2.1.3b : Component interactions for delete 1 command (part 2)

The next few sections give more details of each component.

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

The switchMode mechanism is facilitated by the ChangeModeCommand class which inherits from Command class. It allows the user switch between 2 sets of command for either addressbook or taskmanager.

Suppose the user has just executed the ChangeMode using:

In any command mode, the execute() function of the LogicManager class is first called, which calls Model.getCommandMode() to check the current command mode and goes on to pass the command string and command mode string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the ChangeModeCommand feature is being evoked and calls the ChangeModeCommandParser to parse the string and compare with the current set of command: addressbook(ab) or taskmanager(tm). After validating the input with command mode prefix, ChangeModeCommand(input) is created and calles the excute() feature in ChangeModeCommand which then call Model.changeCommandMode(input) to change the current command mode and return a CommandResult object.

A diagram is shown below to illustrate this mechanism.

Addition of the birthday parameter is facilitated by the AddCommand class which inherited from the UndoableCommand class. It allows user to add the birthday of the contact by putting another parameter into the AddCommand.

Suppose the user has just executed the AddCommand using AddCommand using the following:

The AddCommandParser class will check for the validity of the parameter entered. Afterwards, the LogicManager invokes the method AddCommand, which creates a new person and update the storage.

The detag mechanism is facilitated by the DetagCommand class which is inherited from the UndoableCommand class. It allows for the removal of existing tags from multiple contacts, i.e. detag. The minimum number of contacts that can be specified is 1 and the maximum number is the number of contacts in the current list.

Suppose the user executes the command detag using the following code:

The DetagCommandParser class will check for the validity of the indices specified, i.e. within the range of the filtered list. Afterwards, the LogicManager invokes the method deleteTag, which removes the specific tag from the Set of tags from the specified contacts, and updates the storage.

Aspect: Implementation of DetagCommand
Alternative 1 (current choice): Directly removes the tag from Set of contact(s)
Pros: Easier and more specific command to remove a tag, and allows removal from multiple contacts in one command
Cons: Introduction of new command specifically for the removal of a tag may not be necessary.
Alternative 2: Just use the EditCommand to change the tag
Pros: Use of one command to edit any details of a person is more organised.
Cons: Cannot not remove tags of multiple contacts, and it is mandatory to retype the tags that do not need to be removed.

The FindTag mechanism is facilitated by the FindCommand class which inherits from the Command class. It allows the user to find contacts using tags. Users can search using multiple tags too.

Suppose the user has just executed the FindCommand using:

At first, the execute() function of the LogicManager class is called, which goes on to pass the command string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the FindCommand feature is being evoked and calls the FindCommandParser to parse the string and compare the tags. These are validated and formatted by the TagContainsKeywordsPredicate and returned as a TagContainsKeywordsPredicate object to be used to call the FindCommand class. The LogicManager then calls the execute() in the FindCommand class which creates and returns a CommandResult object.

Commands that are not undoable are implemented this way:

FindCommand will call this class:

The Tag mechanism is a specialised form of the edit feature that allows users to tag multiple contacts with multiple tags. The mechanism is facilitated by the TagCommand class which inherits from the UndoableCommand class, indicating that it can be undone.

Suppose the user has just executed the TagCommand using:

At first the command is called, which causes LogicManager to pass the command string to the parseCommand() function of the AddressBookParser class. This determines that the TagCommand feature is being evoked and calls the TagCommandParser class.

Here, the arguments are validated and tokenized and new TagCommand object is returned with parsed indices and tags.

The ModelManager class in the Model component is then called to update all the tags of the respective people using the updatePersonTags() method.

The Storage and UI are subsequently updated with the new information.

The following sequence diagram summarizes how this operation works:

The TagCommand skips over the invalid indices and attempts to tag the contacts who are in the valid indices. If no valid indices are found, then an error is thrown. This is done by the following:

This works in a similar way to the above.

The Add Task mechanism is facilitated by the AddTaskCommand class which inherits from the UndoableCommand class. It allows for the addition of new tasks to the application with a starting date and a deadline. Both dates are optional and may be omitted.

Suppose the user has just executed the add command using:

At first, the command is called is called, which causes the LogicManager to pass the command string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the AddTask feature is being evoked and calls the AddTaskCommandParser to parse the String and separate it into three components: Description, StartDate and Deadline. These are validated and formatted by the Task class and returned as a Task object to be used to call the AddTaskCommand class. The LogicManager then calls the executeUndoableFunction() in the AddTaskCommand class which creates and returns a CommandResult object.

The following sequence diagram summarizes how this operation works:

All parameters except the description are set to be optional wherein an empty string is added when no value is stated by a user.

Natural Language Input is processed by the PrettyTime NLP, in the ParserUtil class in the following way:

Aspect: Creating classes for StartDate and Deadline
Alternative 1 (current choice): Use Strings to contains the StartDates and Deadlines.
Pros: * Easy to assign an empty string to the instance variable so that the dates are optional and do not show up in the UI. In addition, dates can be stored after being formatted to a more user-friendly style (i.e. Tue, Oct 24, '17). This prevents dates from becoming confusing (i.e. distinguishing between dd-MM-yyyy and mm-DD-yyyy)
Cons: Dates are not stored the correct format. This makes it more difficult to compare and validate later on as they have to be reformatted into Date objects every time. For example, in validating whether a start date is indeed before a deadline.
Alternative 2: Use java.time.LocalDate class.
Pros: Dates are in correct format. Validation becomes easier and reformatting is not necessary.
Cons: LocalDate cannot be initialized when no input is given. Using a phony value of 00:00 or the current date might cause errors in validation and sorting of dates.
Alternative 3: Use java.util.Optional class for instance variables along with the LocalDate class.
Pros: Easy to understand reasoning, for new developers looking to contribute. Easy to format specifically for display (once) and allows empty values when no dates are supplied.
Cons The general agreement in the software engineering community seems to be that it is better not to use extra wrapping for an instance variable, that might pose problems in unwrapping later on.

Aspect: Natural Language Processing
Alternative 1 (current choice): Use an external library (PrettyTime) to process dates in natural language after they have been tokenized by their respective prefixes and categorized according to type.
Pros Dates are sure to be instantiated according to the correct class.
Cons Command format becomes less flexible.
Alternative 2: Parse all dates first then scan the argument string for keywords.
Pros More flexible command format and consequently, more user-friendly.
Cons Open to more mistakes in setting starting dates and deadlines.

Aspect: Setting prefixes for adding tasks
Alternative 1 (current choice): Use natural language prefixes i.e. from, to, by
Pros Easier to type and remember.
Cons Difficult to implement as descriptions containing these words must be separated from dates.
Alternative 2 Use slashes such as in task commands i.e. f/, o/, b/ etc.
Pros Faster to type.
Cons Description might contain slashes. t/ (to) would clash with t/ prefix for tags so to/ would have to be used. Limits possibilities of adding new prefixes and making the format more flexible in the future.

The EditTask Mechanism is facilitated by the EditTaskCommand class and allows th euser to edit any parameter of a given task.

Suppose the user has just executed the command:

edit 1 finish homework by sunday at 9 am to 12 pm ---

The command is passed by the LogicManager class to the AddressBookParser which goes on to pass it to the EditTaskCommandParser class. Here a new EditTaskDescriptor is created using the newly specified parameters while old parameters are copied. Finally, a newly edited person is created and the Model is called to update the task using the UpdateTask() method.

The following sequence diagram summarizes how this operation works:

The optional parameters are assigned in the following manner in the EditTaskCommandParser:

The Delete Task mechanism is facilitated by the DeleteTaskCommand class which inherits from the UndoableCommand class. It allows for the removal of a task at a specified index.

Suppose the user has just executed the delete command using:

At first, the execute() function of the LogicManager class is called, which goes on to pass the command string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the Delete feature is being evoked and calls the DeleteTaskCommandParser to parse the index and validate that the index provided is not out of bounds and returns a new task object to call the DeleteTaskCommand class. The LogicManager then calls the executeUndoableFunction() in the DeleteTaskCommand class which creates and return a CommandResult object.

The FindTask mechanism is facilitated by the FindTaskCommand class which inherits from Command class. It allows the user to find tasks using descriptions. User can search using multiple descriptions too.

Suppose the user has just executed the FindTaskCommand using:

At first, the execute() function of the LogicManager class is called, which goes on to pass the command string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the FindTaskCommand feature is being evoked and calls the FindTaskCommandParser to parse the string and compare the descriptions. These are validated and formatted by the TaskContainsKeywordsPredicate and return as a TaskContainsKeywordsPredicate object to be used to call the FindTaskCommand class. The LogicManager then calls the execute() in the FindTaskCommand class which creates and return a CommandResult object.

Aspect: Implementation of FindTaskCommand
Alternative 1 (current choice): Use String Util.containsword() to find tasks.
Pros: Easy to find matching descriptions among all the tasks accurately.
Cons: The keywords have to be exactly the save i.e friend is not the same as friends.
Alternative 2: Use string.contains() to find tasks.
Pros: Keywords do not have to be exactly the same as those in the description of tasks.
Cons: The search result might not be accurate. For e.g. if the user searches using the keyword 'a' all the tasks’descriptions that contains the character 'a' will appear.

The ListTask mechanism is facilitated by the ListTaskCommand class which inherits from Command class. It allows the user to list out all the current tasks.

Suppose the user has just executed the ListTaskCommand using:

At first, the execute() function of the LogicManager class is called, which goes on to pass the command string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the ListTaskCommand feature is being evoked and calls the execute() in the ListTaskCommand class which update the current list to show all tasks creates and return a CommandResult object.

The SelectTask mechanism is facilitated by the SelectTaskCommand class which inherits from Command class. It allows the user to select the task at specific index.

Suppose the user has just executed the SelectTaskCommand using:

At first, the execute() function of the LogicManager class is called, which goes on to pass the command string into the parseCommand() function of the AddressBookParser class. This, in turn, determines that the SelectTaskCommand feature is being evoked and calls the SelectTaskCommandParser to parse the string and check if the index is valid. After validation the SelectTaskCommand class is been called. SelectTaskCommand will then paraphrase the tag of selected task and pass it through conductSearch. conductSearch will call model.updateFilteredPersonList() with PersonContainsKeywordsPredicate with keyword tag as parameter to find the tag among person list and update person list. If there are no match found, all person will be listed. Then LogicManager then calls the execute() in the SelectTaskCommand class which calls EventCenter with the parameter of JumpToTaskListRequestEvent class to highlight selected task card in Ui at target index. Then execute() creates and return a CommandResult object.

The calendar mechanism is facilitated by the DatePickerSkin skin instance which capture the pop-up content from the DatePicker control in JavaFX. It allows the user to have a calendar view of all contacts' Birthday and tasks' Deadline.

Suppose the address book is modified (e.g. using add, edit, addtask, deletetask).

After the modification of Mobilize’s address book (i.e. saving of data to the addressbook.xml file), ObservableList of Person and Task classes stored in the address book are passed into the CalendarPanel Ui through Model.

Next, getDayCellFactory will format the DateCell of the DatePicker. The formatting is done with birthday and deadline as conditions and colour and tooltip of DateCell as variables to be change by the formatter.

By selecting the date on the calendar, the date value from the DatePicker will be captured and be parsed as a string. The string is then passed to Logic to execute the FindCommand which will show all contacts and tasks having Birthday and Deadline on that specific date.

[NOTE] Implementation of CLI for the calendar is still ongoing.

The following are examples of colour and tooltip of the calendar:

Figure 4.11.a: Tooltip and colour for Deadline

Figure 4.11.b: Tooltip and colour for Birthday

Aspect: Implementation of Calendar
Alternative 1 (current choice): Use DatePickerSkin to get the calendar look and function.
Pros: Less coding needed as the template, DatePicker, is already available. Thus, more time can be spent on other functions related to the calendar.
Cons: Overall look is fixed.
Alternative 2: Design a calendar using JavaFX
Pros: Fully customizable.
Cons: Much effort required to ensure it is bug free.

Aspect: Loading of data to Calendar
Alternative 1 (current choice): Use address book data that is passed to the CalendarPanel through Model
Pros: Able to retrieve updated data from UniquePersonList and UniqueTaskList that are already available.
Cons: Increase coupling with Person and Task.
Alternative 2: Create a separate UniqueMarkDateList that stores required dates with relevant information (e.g. Person’s name and Task’s description)
Pros: Reduces coupling as the data will be stored during initialisation of address book and addition/deletion of person/task.
Cons: We must ensure that the data stored is bound to the individual person and task, such that editing of such person/task will be reflected.

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

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

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

Commands that are not undoable are implemented this way:

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

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

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

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

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

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

The following sequence diagram shows how the undo operation works:

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

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

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

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

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

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

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

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.

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

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.

Figure 5.6.1 : Saving documentation as PDF files in Chrome

There are three ways to run tests.

Method 1: Using IntelliJ JUnit test runner

Method 2: 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)

We have two types of tests:

Problem: HelpWindowTest fails with a NullPointerException.

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

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

Here are the steps to create a new release.

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)

MSS

Extensions

MSS

MSS

Extensions

Extensions

Extensions

Extensions