data_coNdUctorS Developer Guide

Table of Contents

• Acknowledgements
• Setting up, getting started
• Design
  • Architecture
  • UI Component
  • Logic Component
  • Model Component
  • Storage Component
  • Common Classes
• Implementation
  • Pagination
    • Implementation of Constructor
    • Steps to Update the List when there is a Change
  • Status Bar Footer
• Documentation, Logging, Testing, Configuration, Dev-Ops
• Appendix: Requirements
  • Product Scope
  • User Stories
  • Use Cases
    • Add a Contact
    • Listing All Contacts
    • Deleting a Contact
    • Deleting a Contact in a Filtered List
    • Editing a Contact
    • Editing a Contact in a Filtered List
    • Finding a Contact by Details
    • Clearing All Contacts
    • Help Information
  • Non-Functional Requirements
  • Glossary
• Appendix: Instructions for Manual Testing
  • Launch and Shutdown
  • Adding a Contact
  • Listing All Contacts
  • Deleting a Contact
  • Editing a Contact
  • Finding a Contact
  • Help Command
  • Saving Data
  • GUI Components
  • Additional Notes
• Appendix: Planned Enhancements
  • Advanced Error Messages
  • Case Insensitivity for All Contact Fields
  • Display Index of Newly Added Contact
• Appendix: Effort
  • Difficulty Level
  • Challenges Faced
  • Effort Required
  • Achievements

---

Acknowledgements

• Sample data for testing purpose developed by Wu Zengfu: https://github.com/wuzengfu/tp_util
• JavaFX Pagination documentation: https://docs.oracle.com/javase/8/javafx/api/javafx/scene/control/Pagination.html
• Inspired by Code given for camel Case conversion (Chua Tse Hui uses it): https://www.baeldung.com/java-string-to-camel-case
• Understands how to sort a set for implementing a set of Roles (Chua Tse Hui uses it): https://stackoverflow.com/questions/17826854/creating-a-sorted-set
• ChatGPT used to assist in many ways (Chua Tse Hui, Winston, Ernest uses it)

ChatGPT usage - Winston and Ernest

• To assist in writing Javadocs.
• To assist in writing parts of User Guide and Developer Guide and test code

ChatGPT usage - Tse Hui

• Used to assist in writing a snippet of code in ContactCard.java
• Used to assist in writing Regex for Name.java
• Used to assist in creating class diagram via PlantUML

---

Setting up, getting started

Refer to the guide Setting up and getting started.

---

Design

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.

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, ContactListPanel, 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 Contact 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("delete 1") 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., DeleteCommandParser) 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., DeleteCommand) which is executed by the LogicManager.
3. The command can communicate with the Model when it is executed (e.g. to delete a contact).
   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, DeleteCommandParser, ...) 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 Contact objects (which are contained in a UniqueContactList object).
• stores the currently 'selected' Contact objects (e.g., results of a search query) as a separate filtered list which is exposed to outsiders as an unmodifiable ObservableList<Contact> 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 address book 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)

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.

Pagination

The pagination makes use of javafx.scene.control.Pagination component which is inherited by PaginationPanel. The PaginationPanel.java stores all logic and attributes related to Pagination.

The PaginationPanel contains the following member/class variables:

• ROWS_PER_PAGE: Represents the number of items to display in a single page.
• currentPageIndex: Represents the index (0-indexed) of the current page, it is shared among all instances and hence static.
• contactList: A reference of ObservableList<Person> from Logic during the initialization of UI.

Implementation of Constructor

The constructor of PaginationPanel takes in a reference of ObservableList<Person> and stores it as a member variable. Since it is observable, the pagination listens to the event when there is an update of contactList, this is implemented by this.contactList.addListener(this::onListItemsChanged). Then the constructor initializes the pagination component.

Steps to Update the List when there is a Change

Since the constructor adds a listener that listens to onListItemsChanged event on contactList. The onListItemsChanged simply invokes initPagination to re-render the list displayed. It takes the following steps to make the update:

1. Calculate the number of pages by contactList.size() and ROWS_PER_PAGE. The Math::max ensures that there is at least one page even when there is no item. Then it updates the page count of the pagination.
2. Calculate the starting index of sublist from contactList.
3. Calculate the end index of sublist from contactList. The Math::min makes sure that the index does not go beyond the list size. Hence, when there is less than the default ROWS_PER_PAGE number of items to render, it can correctly render all remaining items without the risk of triggering ArrayIndexOutOfBoundException.
4. Get the sublist to be rendered based on the calculated fromIndex and endIndex.
5. Render the updated sublist.

Status Bar Footer: how to reflect the total number of contacts

The ModelManager class also stores allContacts attribute, on top of the filteredList attribute present initially. It represents the full list of contacts which the model can keep track on. A listener is added to allow StatusBarFooter to indirectly listen for any changes made to the allContacts. If changes are detected, the StatusBarFooter can update the total number of contacts accordingly.

---

Documentation, Logging, Testing, Configuration, Dev-Ops

Please refer to the following documents for further information:

• Documentation guide
• Testing guide
• Logging guide
• Configuration guide
• DevOps guide

---

Appendix: Requirements

Product Scope

Target User Profile:

Administrative Directors of CCAs in NUS who wish to manage a database of the CCA members more effectively. The database size is around 50 students. These directors are tech savvy who can type fast.

Value Proposition: Enables users to efficiently and easily manage large CCA membership database (including creation, edition, and deletion of data entries).

---

User Stories

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

---

Use Cases

(For all use cases below, the application is the data_coNdUctorS and the User is the user, unless specified otherwise)

Use case: Add a Contact

MSS

1. User launches the application.
2. User enters the add command with contact details, including name, Telegram handle, email, student status, role(s), and optional nickname.
3. Application validates input fields (e.g., unique email and Telegram handle).
4. Application adds the contact to the address book.
5. Application displays a confirmation message: "Contact added successfully." Use case ends.

Extensions

• 2a. User provides incomplete or invalid data (e.g., incorrect email format).
  • 2a1. Application displays an error message indicating the issue (e.g., "Error: Invalid email format"). Use case ends.
• 3a. Duplicate contact details detected (e.g., duplicate email or Telegram handle).
  • 3a1. Application displays an error message indicating the duplication.
  • 3a2. User either corrects the details or cancels the add operation. Use case ends.

---

Use Case: Listing All Contacts

MSS

1. User launches the application.
2. User enters the list command with no additional parameters.
3. Application displays all stored contacts. Use case ends.

---

Use Case: Deleting a Contact

MSS

1. User enters the delete command with the contact’s index or unique full name.
2. Application deletes the specified contact.
3. Application displays a confirmation message with the deleted contact’s details. Use case ends.

Extensions

• 1a. User provides an invalid index or name.
  • 1a1. Application displays an error message: "Error: Contact not found." Use case ends.
• 1b. User enters a name that is not unique in the address book.
  • 1b1. Application prompts the user to delete by index instead.
  • 1b2. User enters index of contact to delete. Use case resumes at step 2.

---

Use Case: Deleting a Contact in a Filtered List

MSS

1. User performs a search using find to filter contacts.
2. User enters the delete command with the contact’s index or unique full name from the filtered list.
3. Application deletes the specified contact from the filtered list.
4. Application displays a confirmation message with the deleted contact's details. Use case ends.

Extensions

• 2a. User provides an invalid index or name not in the filtered list.
  • 2a1. Application displays an error message: "Error: Contact not found." Use case ends.
• 2b. User enters a name that is not unique in the address book.
  • 2b1. Application prompts the user to delete by index instead.
  • 2b2. User enters index of contact to delete. Use case resumes at step 2.

---

Use Case: Editing a Contact

MSS

1. User enters the edit command with the contact’s index or unique full name, specifying the fields to update.
2. Application validates the updated details (e.g., unique Telegram handle).
3. Application updates the contact’s details in the address book.
4. Application displays a confirmation message: "Contact edited successfully." Use case ends.

Extensions

• 1a. User provides incomplete, invalid, or duplicate data.
  • 1a1. Application displays an error message indicating the issue. Use case ends.
• 1b. User specifies a non-unique full name for editing.
  • 1b1. Application prompts the user to edit by index.
  • 1b2. User enters index of contact to delete. Use case resumes at step 2.
• 1c. Contact not found (e.g., incorrect index or name not in list).
  • 1c1. Application displays an error message: "Error: Contact not found." Use case ends.

---

Use Case: Editing a Contact in a Filtered List

MSS

1. User performs a search using find to filter contacts.
2. User enters the edit command with the contact’s index or unique full name, specifying the fields to update from the filtered list.
3. Application updates the specified contact’s details in the filtered list.
4. Application displays a confirmation message: "Contact edited successfully." Use case ends.

Extensions

• 2a. User provides incomplete, invalid, or duplicate data.
  • 2a1. Application displays an error message indicating the issue. Use case ends.
• 2b. User specifies a non-unique full name for editing.
  • 2b1. Application prompts the user to edit by index.
  • 2b2. User enters index of contact to delete Use case resumes at step 2.
• 2c. Contact not found (e.g., incorrect index or name not in filtered list).
  • 2c1. Application displays an error message: "Error: Contact not found." Use case ends.

---

Use Case: Finding a Contact by Details

MSS

1. User enters the find command with specific criteria, such as name or role etc.
2. Application searches for contacts that match the criteria.
3. Application displays a list of contacts that meet the search criteria, along with a status message: "Found contacts matching criteria." Use case ends.

Extensions

• 1a. Search input does not match any contact in the AddressBook.
  • 1a1. Application shows an error message and prompts user to try searching under another field. Use case ends.
• 1b. User specifies an invalid role or student status.
  • 1b1. Application displays an error message of invalid role/student status inputted. Use case ends.
• 1c. User did not provide the search input
  • 1c1. Application displays error message to input search criteria. Use case ends.

---

Use Case: Clearing All Contacts

MSS

1. User enters the clear command.
2. Application deletes all contacts. Use case ends.

---

Use Case: Help Information

MSS

1. User enters the help command.
2. Application displays a general help message detailing available commands and how to access specific command help.
3. User reads the displayed help message for command information. Use case ends.

Extensions

• 1a. User enters help COMMAND_WORD (e.g., help add) to get detailed information on a specific command.
  • 1a1. Application displays detailed usage information for the specified command, including the command format, required fields, and examples. Use case continues to step 3.
• 1b. User enters help with extraneous parameters (e.g., help extra).
  • 1b1. Application shows an error message and prompts user to try help or help COMMAND_WORD. Use case ends.

Alternate Paths

• 2a. User requests further assistance by following the provided link to the complete User Guide.
  • 2a1. Application opens the User Guide in the default web browser, allowing the user to view more comprehensive instructions. Use case ends.

---

Non-Functional Requirements

• The application should function on any mainstream operating system (Windows, macOS, and Linux) that supports Java 17 or above.

• The application should handle up to 1,000 members without noticeable performance lag for standard operations such as adding, editing, and searching contacts.

• A user with an above-average typing speed for English text should be able to execute commands and accomplish tasks more quickly than by relying solely using commands than using a mouse.

• The application should operate fully offline, with no reliance on an internet connection for core functionalities, including saving and retrieving contact information.

• Comprehensive documentation should be available, including a User Guide, command references, and troubleshooting instructions, to support users and developers alike.

• The GUI should be well-organised, user-friendly, and easy to navigate for users of all experience levels, with intuitive layouts and accessible help options.

• The application should handle common user errors effectively, displaying clear error messages and suggestions to help users correct their input where possible.

• The application should support English as the default language, with future releases allowing for additional languages if necessary.

• The application should support future integration with external contact management systems, allowing for seamless data transfer if needed.

• The application should periodically create a backup of contact data, enabling users to restore from the most recent backup in the event of data loss or corruption.

• The application should be able to retrieve and display member data within 2 seconds.

• The application should validate data entries to ensure consistency and correctness (eg. check that email format is correct etc.)

---

Glossary

• Application Programming Interface (API): A collection of protocols and rules that enables different software applications to communicate and work together.

• Command Line Interface (CLI): A method of interacting with a program by typing commands into a terminal or command window.

• Confidential Contact Information: Contact details intended to remain private and not shared with others.

• Extensible Markup Language (XML): A language for defining document structures that are readable by both humans and computers, enabling data sharing.

• Graphical User Interface (GUI): A user interaction method that involves visual elements like buttons, menus, and windows to operate a program.

• JavaScript Object Notation (JSON): A simple data format that allows information to be stored and exchanged in a lightweight, text-based structure.

• Main Success Scenario (MSS): The primary sequence of actions in a use case that achieves the intended result.

• Mainstream OS: Windows, Linux, Unix, MacOS.

• Pagination: A technique for organising large sets of data or lists into discrete pages, making it easier to navigate and view information one section at a time.

• User Interface (UI): The part of an application that users see and interact with to operate the software.

• Co-curricular activity (CCA): A non-academic activity that students can participate.

• National University of Singapore (NUS): A national public research university in Singapore.

• Footer: A footer is the bottom section of an application.

• Component: A component is a collection of functions that provide a single responsibility to the application.

---

Appendix: Instructions for Manual Testing

This section provides a guide for performing manual testing on the data_coNdUctorS application. Each test case includes expected results and possible error messages for invalid inputs.

---

Launch and Shutdown

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.

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.

---

Adding a Contact

• Adding a valid contact

  • Prerequisites: Application is open with no contacts in the list. (Execute clear to clear all contacts.)

  • Test case: add n/John Doe th/johnd123 e/john.doe@example.com ss/undergraduate 1 r/Admin nn/johny
    Expected: A new contact named "John Doe" is added to the contact list. Status message shows "Contact added successfully."

  • Test case: add n/John Doe th/johnd123 e/john.doe@example.com ss/undergraduate 1 r/Admin nn/johny executed twice
    Expected: No contact is added. Error message will be displayed due to duplicate fields

  • Test case: add n/John Doe th/johnd123 e/john.doe(at)example.com ss/undergraduate 1 r/Admin
    Expected: No contact is added. Error message displayed due to incorrect email format

  • Other incorrect add commands to try: add, add n/, add th/username e/email.com
    Expected: Error message displayed indicating missing or incorrect parameters.

---

Listing All Contacts

• Listing contacts with no additional parameters

  • Prerequisites: Application is open with multiple contacts in the list.

  • Test case: list
    Expected: All contacts are displayed in the list view. Status message shows "Listed all contacts."

  • Other variations to try: list all, list contacts or any variation of all and/or contacts after list
    Expected: Similar outcome to list command. All contacts are displayed.

---

Deleting a Contact

• Deleting a contact while ALL contacts are being shown

  • Prerequisites: List all contacts using the list command. Multiple contacts 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.

  • Test case: delete 0
    Expected: No contact is deleted. Error details shown in the status message.

  • Test case: delete UNIQUE_FULL_NAME
    Expected: If UNIQUE_FULL_NAME is in the Address Book and there is only one FULL_NAME, deletes that contact.

  • Test case: delete NOT_UNIQUE_FULL_NAME
    Expected: If NOT_UNIQUE_FULL_NAME is in the Address Book but not unique, no contact is deleted and error details shown in the status message for user to delete via index.

  • Test case: delete FULL_NAME_NOT_IN_LIST
    Expected: If FULL_NAME_NOT_IN_LIST is not in Address Book, no contact is deleted and error details shown in the status message.

  • Test case: delete NOT_FULL_NAME
    Expected: No contact is deleted and error details shown to delete by the full name of delete by index.

  • Other incorrect delete commands to try: delete, delete x (where x is larger than the list size)
    Expected: No contact is deleted. Error details shown in the status message for missing or invalid fields

• Deleting a contact while SOME contacts are being shown

  • Prerequisites: Find some contacts using the find command. Multiple contacts in the filtered list.

  • Test case: delete 1
    Expected: Similar to above.

  • Test case: delete 0
    Expected: Similar to above.

  • Test case: delete UNIQUE_FULL_NAME
    Expected: If UNIQUE_FULL_NAME is in the filtered Address Book and there is only one FULL_NAME, deletes that contact.

  • Test case: delete NOT_UNIQUE_FULL_NAME
    Expected: If NOT_UNIQUE_FULL_NAME is in the filtered Address Book but not unique, no contact is deleted and error details shown in the status message for user to delete via index.

  • Test case: delete FULL_NAME_NOT_IN_LIST
    Expected: If FULL_NAME_NOT_IN_LIST is not in filtered Address Book, no contact is deleted even if the name is present in the unfiltered Address Book and error details shown in the status message.

  • Test case: delete NOT_FULL_NAME
    Expected: No contact is deleted and error details shown to delete by the full name of delete by index.

  • Other incorrect delete commands to try: delete, delete x (where x is larger than the list size), delete NOT_FULL_NAME
    Expected: Similar to above.

---

Editing a Contact

• Editing a contact while ALL contacts are being shown

  • Prerequisites: List all contacts using the list command. Multiple contacts in the list.

  • Test case: edit 1 n/Jane Smith th/jane_smith
    Expected: First contact’s name changes to "Jane Smith" and Telegram handle to "jane_smith." Status message shows "Contact edited successfully."

  • Test case: edit 99 n/Jane Smith
    Expected: No contact is edited. Error message displayed: "Error: Contact not found. Please provide a valid index."

  • Test case: edit UNIQUE_FULL_NAME th/john_doe
    Expected: If UNIQUE_FULL_NAME is in the Address Book and there is only one FULL_NAME, edits that contact.

  • Test case: edit NOT_UNIQUE_FULL_NAME th/john_doe
    Expected: If NOT_UNIQUE_FULL_NAME is in the Address Book but not unique, no contact is edited and error details shown in the status message for user to edit via index.

  • Test case: edit FULL_NAME_NOT_IN_LIST th/john_doe
    Expected: If FULL_NAME_NOT_IN_LIST is not in Address Book, no contact is edited and error details shown in the status message.

  • Test case: edit NOT_FULL_NAME th/john_doe
    Expected: No contact is edited and error details shown to edit by the full name of edit by index.

  • Other incorrect edit commands to try: edit, edit 1, edit 1 e/invalidemail.com
    Expected: Error message displayed for missing or invalid fields.

• Editing a contact while SOME contacts are being shown

  • Prerequisites: Find some contacts using the find command. Multiple contacts in the filtered list.

  • Test case: edit 1 n/Jane Smith th/jane_smith
    Expected: Similar to above.

  • Test case: edit 99 n/Jane Smith
    Expected: Similar to above.

  • Test case: edit UNIQUE_FULL_NAME th/john_doe
    Expected: If UNIQUE_FULL_NAME is in the filtered Address Book and there is only one FULL_NAME, edits that contact.

  • Test case: edit NOT_UNIQUE_FULL_NAME th/john_doe
    Expected: If NOT_UNIQUE_FULL_NAME is in the filtered Address Book but not unique, no contact is edited and error details shown in the status message for user to edit via index.

  • Test case: edit FULL_NAME_NOT_IN_LIST th/john_doe
    Expected: If FULL_NAME_NOT_IN_LIST is not in filtered Address Book, no contact is edited even if the name is present in the unfiltered Address Book and error details shown in the status message.

  • Test case: edit NOT_FULL_NAME th/john_doe
    Expected: No contact is edited and error details shown to edit by the full name of edit by index.

  • Other incorrect edit commands to try: edit, edit 1, edit 1 e/invalidemail.com
    Expected: Similar to above.

---

Finding a Contact

• Finding a contact by details

  • Prerequisites: Multiple contacts are present in the contact list.

  • Test case: find n/John r/Admin
    Expected: Contacts matching "John" with role "Admin" are displayed in the list. Status message shows "Found contacts matching criteria."

  • Test case: find n/NAME_NOT_IN_LIST r/Admin
    Expected: No contacts are displayed. Status message shows "No contacts found matching the criteria."

  • Other incorrect find commands to try find, find n/NAME_NOT_IN_LIST r/ROLE_NOT_IN_LIST
    Expected: If no contacts match, a message appears indicating no contacts found. If an invalid role is entered, an error message displays: "Error: Invalid role specified."

---

Help Command

1. Get the instruction of a command

   1. Prerequisites: Application is running.

   2. Test case: help
      Expected: Displays the instruction of help command and pops up a window which contains a link to the user guide.

   3. Test case: help list
      Expected: Displays the instruction and example commands for list.

   4. Test case: help add
      Expected: Displays the instruction and example commands for add.

   5. Test case: help edit
      Expected: Displays the instruction and example commands for edit.

   6. Test case: help delete
      Expected: Displays the instruction and example commands for delete.

   7. Test case: help find
      Expected: Displays the instruction and example commands for find.

---

Saving Data

• Automatic Data Saving

  • Prerequisites: Application is running, and a contact has been added, edited, or deleted.

  • Test case: Close and reopen the application.
    Expected: The changes made to contacts persist after reopening. The saved contacts appear as they were before closing the app.

• Data File Integrity

  • Prerequisites: The data file (addressbook.json) is accessible for manual editing.

  • Test case: Manually edit the JSON file to include an invalid format or structure (e.g., remove a required field).
    Expected: Upon launching, the application detects the corrupted data and either resets to an empty state or prompts an error message like "Error: Invalid data format detected. Data reset to empty state."

---

GUI Components

• Pagination

  • Prerequisites: Add enough contacts to exceed a single page (e.g., 11 or more contacts as each page displays 10).

  • Test case: Use pagination controls (next, previous) or page navigation to view contacts on multiple pages.
    Expected: Pagination controls work as expected, allowing the user to navigate through the contact list. The status bar reflects the current page and total contacts.

• Footer Status Bar

  • Prerequisites: Add or delete a contact to observe changes in the footer.

  • Test case: Add a contact, then delete a different contact.
    Expected: The footer updates in real-time, displaying the current total contacts and the path of the data file. Status message shows the results of the last action.

---

Additional Notes

• Testing Edge Cases

  • Prerequisites: Application is running with an open contact list.

  • Test case: Add or edit a contact with special characters in fields, very long inputs, or boundary values (e.g., maximum allowed length for fields).
    Expected: The application handles special characters, lengthy inputs, and boundary values without crashing or error. If any input exceeds limits, a message such as "Error: Input exceeds allowed length" is shown.

• Common Mistakes

  • Prerequisites: Application is open and ready for input.

  • Test case: Enter commonly mistaken commands or leave required fields blank (e.g., delete with no index, find with no criteria).
    Expected: Error messages are clear and descriptive, guiding the user to correct the input format. Status bar remains unaffected by failed commands.

• Data Reset

  • Prerequisites: The application has saved data that the user wishes to reset.

  • Test case: Delete or replace the data JSON file and restart the application.
    Expected: The app initialises with an empty contact list, and a message indicates that no saved data was found, prompting a fresh start.

---

This appendix provides a comprehensive approach to testing the data_coNdUctorS app, ensuring each core feature and edge case is addressed. Error messages will appear on the screen if incorrect inputs are entered, helping users to correct their input efficiently.

Appendix: Planned Enhancements

This section outlines the planned future enhancements for the data_coNdUctorS application to improve functionality, usability, and scalability.

---

Advanced Error Messages

Informing the User what is their specific issue with the command that they have inputted.

• Goal: Quality of Life for users to understand which part of the command they inputted wrongly so they don't have to waste time.

• Example 1: Editing a contact with the same NAME and NICKNAME as an existing contact will result in an error message: "This Contact already exists in the address book". This is not very clear so in the future, we could display the said contact to the user and inform them which fields are duplicated.

• Example 2: Executing this command add n/John Doe th/johnny_9876_haha e/johnd@example.com ss/undergraduate 3 r/Admin r/President [nn/altName] will output an error message saying invalid Role. Instead, should tell the user that the Role they implemented is President [ which is not recognised as a role.

• Expected Outcome: Users will waste less time debugging their inputs, especially for large address books.

---

Case Insensitivity for All Contact Fields

Some Contact fields are case-sensitive so errors arise during duplicate contacts being loaded into the address book

• Goal: Reduce accidental duplicates to enhance the user experience when interacting with the contact list.

• Case 1: Nickname is case-sensitive (e.g., nn/alice and nn/Alice are considered distinct). After this enhancement, nn/alice and nn/Alice will be treated as identical, reducing potential conflicts caused by casing differences. Contacts will be flagged as having the same identity if both Name and Nickname match in a case-insensitive manner.

• Case 2: Telegram Handle and Email are also case-sensitive. In the enhanced version, these fields will also become case-insensitive, ensuring no two contacts can have the same Telegram Handle, Email, or Nickname, even if they differ only by letter casing.

• Expected Outcome: Reduce errors and confusion due to case variations. Ensure that no two contacts have the same Telegram Handle, Email, or Nickname regardless of case, thereby improving data integrity.

---

Display Index of Newly Added Contact

Users may be uncertain about where a newly added contact appears within the contact list.

• Goal: Clearly indicate the index of the newly added contact so that users can easily locate and verify the contact’s information without unnecessary searching.

• Example: When a contact is added, the UI will default to displaying the first page. However, since contacts are listed in alphabetical order, the new contact may not be visible on this page if it appears further down the list. Users may end up scrolling through multiple pages to locate the newly added contact, especially if they are unfamiliar with other contacts in the system.

• Expected Outcome: Users can instantly see the index of the added contact, allowing them to navigate directly to its location without spending extra time searching through the list.

Appendix: Effort

Difficulty Level

If the Individual Project (IP) was rated a difficulty of 5/10, this Data_coNdUctorS Team Project (TP) would be a solid 9/10. While we didn't implement highly advanced features, the project posed significant challenges, especially for our team of mostly non-Computer Science majors. Transitioning from the IP to the TP required adapting to complex structures, such as multiple CommandParsers, working with .fxml files for UI design, and fully utilising GitHub's collaborative tools. These elements presented a steep learning curve and demanded a lot of adjustment.

---

Challenges Faced

• Pagination: As we modified the AddressBook3 (AB3) UI, we aimed to introduce pagination to help users navigate large contact lists efficiently. Although we found some resources and code snippets online, implementing comprehensive test cases for the pagination feature proved challenging. This lowered our overall CodeCov score, as we struggled to find suitable ways to test this UI-centric functionality.

• Test Coverage: Maintaining high test coverage was a significant challenge, especially due to the new UI features and pagination, which reduced our overall CodeCov score. As we were still learning to work with automated testing, achieving comprehensive test coverage for these features required more experience than we initially had.

• JavaFX Framework: JavaFX was entirely new to the team, and we found it challenging to implement the necessary UI enhancements. We devoted considerable time to learning JavaFX basics, which delayed some of our intended progress but ultimately provided us with valuable skills.

• IntelliJ Integration: For most of us, IntelliJ was a new development environment, and we initially struggled to navigate its features. Many of us used CLI commands in the terminal until around week 11, when we discovered that IntelliJ could streamline many processes, including Git commands. This realisation greatly improved our workflow and efficiency for the remainder of the project.

---

Effort Required

The project required consistent, focused effort from each team member.

Each week, we met as a team 2 to 3 times. The first meeting was usually to distribute tasks, with a check-in meeting closer to the submission deadline and a final meeting on the due date to ensure everything was ready for submission. These meetings accounted for approximately 4-6 hours per week. Additionally, each team member spent an average of 7 hours per week working independently on the project. Tse Hui went above and beyond, dedicating 12-14 hours weekly to drive our progress forward.

---

Achievements

Despite the challenges, we achieved several milestones that we're proud of:

• Realistic Goal Setting and Achievement: Although we didn't add an extensive list of features, we set realistic project goals and are proud to have met them. This includes valuable learning outcomes, such as mastering GitHub for version control, exploring IntelliJ’s integrated tools, and learning how to collaborate effectively on a software project as a team.
• Skill Development: Our work on this project allowed each team member to grow technically and collaboratively, strengthening our foundational skills in Java, JavaFX, and project management practices.