TrueRental Developer Guide

Table of Contents

---

Acknowledgements

This project is built on top of AddressBook-Level3 Project. Special thanks and appreciation for the team of AddressBook-Level 3.

ChatGPT was used to create the TrueRental application logo, as well as for debugging and documentation purposes only.

Setting up, getting started

Setting up the project in your computer

First, fork this repo, and clone the fork into your computer.

If you plan to use Intellij IDEA (highly recommended):

1. Configure the JDK: Follow the guide [se-edu/guides] IDEA: Configuring the JDK to ensure Intellij is configured to use JDK 17.
2. Import the project as a Gradle project: Follow the guide [se-edu/guides] IDEA: Importing a Gradle project to import the project into IDEA.
   Note: Importing a Gradle project is slightly different from importing a normal Java project.
3. Verify the setup:
   1. Run the seedu.address.Main and try a few commands.
   2. Run the tests to ensure they all pass.

Running Tests

There are two ways to run tests.

• 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 test (Mac/Linux: ./gradlew clean test)

---

Before writing code

1. Configure the coding style

   If using IDEA, follow the guide [se-edu/guides] IDEA: Configuring the code style to set up IDEA's coding style to match ours.

   Tip: Optionally, you can follow the guide [se-edu/guides] Using Checkstyle to find how to use the CheckStyle within IDEA e.g., to report problems as you write code.

2. Set up CI

   This project comes with a GitHub Actions config files (in .github/workflows folder). When GitHub detects those files, it will run the CI for your project automatically at each push to the master branch or to any PR. No set up required.

3. Learn the design

   When you are ready to start coding, we recommend that you get some sense of the overall design by reading about TrueRental’s architecture.

Design

Architecture

The Architecture Diagram given above explains the high-level design of the application.

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 application launch and shut down.

• At application 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 application 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 cadd n/John ... (details of command are omitted).

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 API interface 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 the UI relies on the Logic to execute commands.
• depends on some classes in the Model component, as it displays Person object residing in the Model.

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("rview 1") API call as an example.

The sequence diagram below illustrates the interactions within the Logic component, taking execute("cadd n/John Doe p/91231231 e/john@example.com") API call as an example.

How the Logic component works:

1. When Logic is called upon to execute a command, it is passed to an AddressBookParser object which in turn creates a parser that matches the command (e.g., DeleteClientCommandParser) and uses it to parse the command.
2. This results in a Command object (more precisely, an object of one of its subclasses e.g., DeleteClientCommand) which is executed by the LogicManager.
3. The command can communicate with the Model when it is executed (e.g. to delete a client).
   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 the Model) to achieve.
4. The result of the command execution is encapsulated as a CommandResult object which is returned back from Logic.

Here are the other classes in Logic (omitted from the class diagram above) that are used for parsing a user command:

How the parsing works:

• When called upon to parse a user command, the AddressBookParser class creates an XYZCommandParser (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 a XYZCommand object (e.g., AddCommand) which the AddressBookParser returns back as a Command object.
• All XYZCommandParser classes (e.g., AddCommandParser, DeleteClientCommandParser, ...) inherit from the Parser 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 a UniquePersonList 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 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.
• stores a UserPref object that represents the user’s preferences. This is exposed to the outside as a ReadOnlyUserPref 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)

Storage component

API : Storage.java

The Storage component,

• can save both TrueRental's data and user preference data in JSON format, and read them back into corresponding objects.
• inherits from both AddressBookStorage and UserPrefStorage, 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 the Storage component's job is to save/retrieve objects that belong to the Model).
• has a separate portion to store the current session's command history into a text file.

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.

Confirmation prompts

Some commands such as clear, cdelete and rdelete prompts the user for confirmation.

How confirmation prompts work:

• The CommandResult class now has different types:
  • ORDINARY: A regular result, representing a command's success.
  • SHOW_HELP: The help window should be shown to the user.
  • EXIT: The app should exit.
  • PROMPT: The app should prompt the user for confirmation.
• There is a new Supplier<CommandResult> field in the CommandResult class, which will be applied when the user confirms the prompt.
• In commands that will prompt for confirmation, the execute method returns a CommandResult that contains an additional Supplier<Command> and prompt message.
• The LogicManager detects if the result of a command is of the type PROMPT, and enters a state where it waits for a confirmation.
• LogicManager also keeps track of the most recent CommandResult. When a confirmation is obtained, it will apply the supplier in the previous CommandResult.

The sequence diagram below illustrates the interactions involved in confirmation prompts, taking the command clear as an example:

Importing and Exporting data

The user is able to import data from and export data to external files.

How import and export work:

• A FileChooser resides in the MainWindow container.
• The CommandResult class now has two new types:
  • IMPORT: The FileChooser window should be shown to the user to choose a file for import.
  • EXPORT: The FileChooser window should be shown to the user to choose a file for export.
• CommandResult of the above types store an extra Supplier<CommandResult> that will be applied if import or export was successful.
• The MainWindow detects if a result returned by LogicManager is of type IMPORT or EXPORT, and shows the correct FileChooser window based on the type.
• After the user chooses a file, MainWindow passes the file to LogicManager by calling the processFile method.
• LogicManager passes the file to the Storage component to import or export data via the readAddressBook and saveAddressBook methods.
• If the import or export was successful, LogicManager applies the supplier in the most recent CommandResult.

The sequence diagram below illustrates the interactions within the Logic, UI and Storage components when importing or exporting data, taking the command export as an example:

---

Appendix: Requirements

Product scope

Target user profile:

• are letting agents
• has a need to manage a significant number of client's personal and rental information
• prefer desktop apps over other types
• can type fast
• prefers typing to mouse interactions
• is reasonably comfortable using CLI apps

Value proposition: manage many client's personal and rental information, such as name, phone number, address, rental start date, rental end date, monthly rent amount, etc.

User stories

Priorities: High (must have) - * * *, Medium (nice to have) - * *, Low (unlikely to have) - *

Use cases

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

Use case 1: Add a client

MSS

1. User chooses to add a client

2. User enters client's information

3. System validates user input

4. System adds new client information

5. System notifies user upon successful add operation

   Use case ends.

Extensions

• 3a. System detects error for invalid instruction

  • 3a1. System prompts error for invalid instruction
  • 3a2. User enters new instruction
  • Steps 3a1-3a2 are repeated until instruction is valid

  Use case continues from step 3.

• 3b. System detects error in client's information

  • 3b1. System prompts error for invalid client's information
  • 3b2. User enters new client's information
  • Steps 3b1-3b2 are repeated until client's information is valid

  Use case continues from step 3.

• 3c. System detects duplicated client's information

  • 3c1. System prompts error for duplicated client's information
  • 3c2. User enters new non-duplicated client's information
  • Steps 3c1-3c2 are repeated until client's information is valid

  Use case continues from step 4.

• *a. At any time, user chooses not proceed on with the operation.

  Use case ends.

Use case 2: Add a client's rental information

MSS

1. User chooses to add rental information

2. User selects client

3. User enters client's rental information

4. System validates user input

5. System updates new client information

6. System notifies user upon successful add operation

   Use case ends.

Extensions

• 4a. System detects error for invalid instruction

  • 4a1. System prompts error for invalid instruction
  • 4a2. User enters new instruction
  • Steps 4a1-4a2 are repeated until instruction is valid

  Use case continues from step 4.

• 4b. System detects error for invalid client

  • 4b1. System prompts error for invalid client
  • 4b2. User selects new client
  • Steps 4b1-4b2 are repeated until selected client is valid

  Use case continues from step 4.

• 4c. System detects error in client's rental information

  • 4c1. System prompts error for invalid client's rental information
  • 4c2. User enters new client's rental information
  • Steps 4c1-4c2 are repeated until client's rental information is valid

  Use case continues from step 4.

• 4d. System detects duplicated client's rental information

  • 4d1. System prompts error for duplicated client's rental information
  • 4d2. User enters new non-duplicated client's rental information
  • Steps 4d1-4d2 are repeated until client's rental information is valid

  Use case continues from step 5.

• *a. At any time, user chooses not proceed on with the operation.

  Use case ends.

Use case 3: Find a client

MSS

1. User chooses to find a client

2. User enters keyword

3. System validates user input

4. System filters list of client based on keyword

   Use case ends.

Extensions

• 3a. System detects error for invalid instruction

  • 3a1. System prompts error for invalid instruction
  • 3a2. User enters new instruction
  • Steps 3a1-3a2 are repeated until instruction is valid

  Use case continues from step 3.

• 3b. System detects error for invalid keyword

  • 3b1. System prompts error for invalid keyword
  • 3b2. User enters new keyword
  • Steps 3b1-3b2 are repeated until keyword is valid

  Use case continues from step 4.

• 4a. The list is empty.

  Use case ends.

• *a. At any time, user chooses not proceed on with the operation.

  Use case ends.

Use case 4: Edit a client's information

MSS

1. User chooses to edit a client's information.

2. User enters the client information that he / she wants to update.

3. System validates user input.

4. System updates the client's information as requested.

5. System notifies user for successful modification.

   Use case ends.

Extensions

• 3a. System detects error for invalid instruction.

  • 3a1. System prompts error for invalid instruction.
  • 3a2. User enters new instruction.
  • Steps 3a1-3a2 are repeated until the instruction is valid.

  Use case resumes from step 3.

• 3b. System detects error for invalid client information.

  • 3b1. System prompts error for invalid client information.
  • 3b2. User enters new client information.
  • Steps 3b1-3b2 are repeated until the client information is valid.

  Use case resumes from step 3.

• *a. At any time, User chooses not to proceed with the operation.

  Use case ends.

Use case 5: Edit a client's rental information

MSS

1. User chooses to edit a client's rental information.

2. User enters the rental information that he / she wants to update.

3. System validates user input.

4. System updates the client's rental information as requested.

5. System notifies user for successful modification.

   Use case ends.

Extensions

• 3a. System detects error for invalid instruction.

  • 3a1. System prompts error for invalid instruction.
  • 3a2. User enters new instruction.
  • Steps 3a1-3a2 are repeated until the instruction is valid.

  Use case resumes from step 3.

• 3b. System detects error for invalid rental information.

  • 3b1. System prompts error for invalid rental information.
  • 3b2. User enters new rental information.
  • Steps 3b1-3b2 are repeated until the rental information is valid.

  Use case resumes from step 3.

• *a. At any time, User chooses not to proceed with the operation.

  Use case ends.

Use case 6: Delete a client

MSS

1. User chooses to delete a client and all related rental information

2. User types in a command consisting the index of the client

3. System prompts the user for confirmation

4. User confirms the deletion

5. System deletes that client and all related rental information

   Use case ends.

Extensions

• 2a. The provided index is not valid

  • 2a1. System prompts error for invalid index
  • 2a2. User enters new instruction
  • Steps 2a1-2a2 are repeated until the instruction is valid

  Use case resumes from step 3.

• 4a. User cancels the deletion

  Use case ends.

Use case 7: Delete a rental information from a client

MSS

1. User chooses to delete a specific rental information from a client

2. User types in a command consisting the index of the client and rental information

3. System prompts the user for confirmation

4. User confirms the deletion

5. System deletes that rental information

   Use case ends.

Extensions

• 2a. The provided index is not valid

  • 2a1. System prompts error for invalid index
  • 2a2. User enters new instruction
  • Steps 2a1-2a2 are repeated until the instruction is valid

  Use case resumes from step 3.

• 4a. User cancels the deletion

  Use case ends.

Use case 8: Revisit previously entered commands

MSS

1. User previously entered multiple commands

2. User presses up-arrow key to re-visit previous command

3. System fills command box with respective command

4. User presses down-arrow key to re-visit next command

5. System fills command box with respective command

6. User presses enter to submit the command

7. System performs the action relating to the command

   Use case ends.

Extensions

• 2a. There are no more previous command within the command history

  • 2a1. System stays at current command

  Use case resumes from step 3.

• 3a. There are no more next command within the command history

  • 3a1. System fills command box with empty command

  Use case ends.

Use case 9: Sort a client list by name

MSS

1. User chooses to sort a client list by name

2. User types in the respective command.

3. System sorts the client list by name

   Use case ends.

Non-Functional Requirements

1. Should work on any mainstream OS as long as it has Java 17 or above installed.
2. Should be able to hold up to 1000 clients 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.
4. A user should be able to see clearly with reasonably large texts.
5. The user interface should be simple, functional, and visually inoffensive to the majority of users.
6. A new user should be able to view information intuitively, even if they do not know the commands used to perform tasks.
7. Should be able to type up to 2000 characters without a noticeable lag.

Glossary

• Mainstream OS: Windows, Linux, Unix, MacOS
• Private contact detail: A contact detail that is not meant to be shared with others
• User: A letting agent that is using TrueRental to manage the contact information of their clients
• Client: A person whose properties are managed by a letting agent
• Letting agent: An individual that facilitates a property rental agreement
• System: TrueRental desktop application
• Client's information: A client's information containing name, phone number , email and list of rental information, not meant to be shared with others.
• Rental information: A client's rental information containing address, rental start date, rental end date, rent due date, monthly rent amount, deposit amount, customer list, not meant to be shared with others.
• Customer List: The list of tenant(s) who are renting a property.
• MSS: Main Success Scenario.

Back to top

Appendix: Instructions for manual testing

Given below are instructions to test the app manually.

Launch and shutdown

1. Initial launch

   1. Download the latest truerental.jar file from here and copy into an empty folder
   2. Open a command terminal, cd into the folder that you previously saved the .jar file in.
   3. Use java --versionto ensure your java version is Java 17.
   4. Use java -jar truerental.jar command to run the application.
   5. Expected: A GUI similar to the image shown below should appear within a few seconds. The application will contain some sample data.

2. Shut down

   1. Click on the cross at the top of the application window.
      1. MacOS: Red cross button at the top-left of the application window.
      2. Windows / Linux: Red cross button at the top-right of the application window.
         Expected: The application will exit and close safely.
   2. Enter exit into the command box of the application.
      Expected: The application will exit and close safely.
      

3. Subsequent Launches

   1. Relaunch the application by cd into the respective folder with the truerental.jar file.
   2. Use java --version to ensure your java version is Java 17.
   3. Use java -jar truerental.jar command to run the application.
   4. Expected: The application should retain all changes made to the data within the application previously.
      

4. 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 typing java -jar truerental.jar.
      Expected: The most recent window size and location is retained.

Basic Usage

Adding a client

Adding a client while all clients are being shown.

Adding a client's rental information

Adding a client's rental information while all clients are being shown.

Viewing a client's rental information

Viewing a client's rental information while all clients are being shown.

Editing a client

Editing a client's rental information

Editing a client's rental information.

Listing all clients

Listing all clients within the application.

Find clients based on criteria

Find clients based on certain criteria such as name contains Amy, is tagged with Friends, etc. Additionally, find clients whose details or rental information contains a keyword.

Deleting a client

Deleting a client.

Deleting a client's rental information

Deleting a client's rental information.

Command History Feature

Retrieving previously entered commands.

Autofill Commands Feature

1. Autofill command name.

2. Autofill parameter prefix for a command.

3. Autofills value for parameter.

Sort all clients by name

Sorting the entire True Rental's database by name.

Clear

Clearing the entire True Rental's database, wiping all clients and their respective rental information (if any).

Exit

Safely exiting TrueRental application.

---

Duplicate Client Detection and Handling

A client is only considered as duplicate if and only if all three parameters NAME, PHONE_NUMBER and EMAIL_ADDRESS are exactly the same (including case sensitivity).

This is to allow the user to have a greater flexibility of manipulating the client's information.

For example: All the clients stated below the initial client are NOT CONSIDERED as duplicates.

Duplicate Rental Information Detection and Handling

Rental information is considered a duplicate if and only if the ADDRESS parameter is exactly the same, including case sensitivity.

This is to allow you to have a greater flexibility of manipulating the rental information.

For example:

---

Appendix: Future Enhancements

1. Additional Parameter Constraints

Parameter	Description	Additional Constraints	Examples
NAME	The client's name.	Accommodate special characters in names, which includes, but not limited to / , ', ., ;.	Ravi S/O Ramasamy
PHONE_NUMBER	The client's phone number.	Accommodate country code, which includes, but not limited to +65 and limit to a certain number of characters such as 8 characters only for Singapore numbers.	98765421
EMAIL	The client's email address.	Accommodate well-established email companies only.	test@gmail.com
TAG	The tags associated with the client.	Limit up to 20 characters.	12345678901234567890
ADDRESS	The address of the property owned by the client.	Limit up to 150 Unicode characters.	18 Kaki Bt Rd 3 #05-16 Entrepreneur Business Centre S(415978), Singapore
MONTHLY_RENT	The monthly rent amount for the property owned by the client.	Restrict the value to the maximum representable value of a Double in Java.	999999999999
DEPOSIT	The security deposit amount for the property owned by the client, paid by the tenant at the start of the lease.	Restrict the value to the maximum representable value of a Double in Java.	999999999999
CUSTOMER_LIST	The name(s) of the tenant(s) for the property owned by the client.	Limit the usage of the ; separator to 49 occurrences, which can accommodate up to 50 names in total.	Alice;Bob;Charlie;David;Ella;Fiona;Geoge;Helen

2. cedit Command

The current version of cedit only supports replacing all tags with the updated tag provided by the cedit command. In the future, there will be an update to the cedit command, where the user is able to choose which tag to retain as well as which tag to edit.

3. redit Command

The current version of redit only supports replacing existing value to the newly specified value for all parameters used in redit. In the future, there will be an update to the redit command, where the user is able to choose whether to edit from the existing value or simply replace the existing value, offering greater convenience.

4. sort Command

The current version of sort is case-sensitive. In the future, there will be an update to the sort command, where the sorting will be case-insensitive.

5. RENT_DUE_DATE Parameter

The current RENT_DUE_DATE meant to refer to the specific day (of the month) on which the rent payment is due for the property owned by the client. However, the term DATE may be misleading, as users might assume it requires the format dd/mm/yyyy. In the future, there will be an update to the RENT_DUE_DATE parameter, where it will be renamed to RENT_DUE_DAY for greater clarity.

6. Error Message For Invalid Value Of MONTHLY_RENT Parameter

The current error message for an invalid value of MONTHLY_RENT is: Monthly Rent should only contain numbers, and in 2 decimal places if needed. This message may be misleading, as the term numbers is too vague. In the future, there will be an update to the error message for invalid value of MONTHLY_RENT, where it will be rephrased to Monthly Rent should only contain positive numbers (including 0, with no leading zeroes), and be formatted with exactly 2 decimal places if needed for greater clarity.

7. Error Message For Invalid Value Of DEPOSIT Parameter

The current error message for an invalid value of DEPOSIT is: Deposit should only contain numbers, and in 2 decimal places if needed. This message may be misleading, as the term numbers is too vague. In the future, there will be an update to the error message for invalid value of DEPOSIT, where it will be rephrased to Deposit should only contain positive numbers (including 0, with no leading zeroes), and be formatted with exactly 2 decimal places if needed for greater clarity.

8. Duplicate Rental Information Detection

Currently, rental information is considered a duplicate if and only if the ADDRESS parameter matches exactly, including case sensitivity. However, this approach may not be ideal as unique identifiers such as unit numbers can differentiate addresses that are otherwise the same. In the future, there will be an update to the duplicate rental information detection method, where rental information will be considered a duplicate if and only if the ADDRESS parameter matches (case-insensitively).

9. Handling Long Text In The UI

Currently, some long texts are truncated due to the window size constraints of the application, with excess text displayed as .... In the future, there will be an update to the UI and additional constraints on the parameter value. The UI will be updated such that all characters will be fully displayed without truncation or the use of ....

10. Storage Related Error Handling

In some very rare cases, reading from or writing to data file may fail due to various reasons. In the future, there will be an update to the application, where a prompt will be displayed to notify the user of such failures.