LoanBook - Developer Guide

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with ours but it uses a different import order from ours. To rectify,

Optionally, you can follow the UsingCheckstyle.adoc document to configure Intellij to check style-compliance as you write code.

After forking the repo, the documentation will still have the SE-EDU branding and refer to the se-edu/addressbook-level4 repo.

If you plan to develop this fork as a separate product (i.e. instead of contributing to se-edu/addressbook-level4), you should do the following:

Set up Travis to perform Continuous Integration (CI) for your fork. See UsingTravis.adoc to learn how to set it up.

After setting up Travis, you can optionally set up coverage reporting for your team fork (see UsingCoveralls.adoc).

Optionally, you can set up AppVeyor as a second CI (see UsingAppVeyor.adoc).

When you are ready to start coding, you may move on to Section 2.1, “Architecture” to get some sense of the overall design.

The undo/redo mechanism is facilitated by VersionedLoanBook. It extends LoanBook with an undo/redo history, stored internally as a loanBookStateList and currentStatePointer. Additionally, it implements the following operations:

These operations are exposed in the Model interface as Model#commitLoanBook(), Model#undoLoanBook() and Model#redoLoanBook() respectively.

Given below is an example usage scenario and how the undo/redo mechanism behaves at each step.

Step 1. The user launches the application for the first time. The VersionedLoanBook will be initialized with the initial loan book state, and the currentStatePointer pointing to that single loan book state.

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

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

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

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoLoanBook(), which shifts the currentStatePointer once to the right, pointing to the previously undone state, and restores the loan book to that state.

Step 5. The user then decides to execute the command list. Commands that do not modify the loan book, such as list, will usually not call Model#commitLoanBook(), Model#undoLoanBook() or Model#redoLoanBook(). Thus, the loanBookStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitLoanBook(). Since the currentStatePointer is not pointing at the end of the loanBookStateList, all loan book states after the currentStatePointer will be purged. We designed it this way because it no longer makes sense to redo the add n/David …​ command. This is the behavior that most modern desktop applications follow.

The following activity diagram summarizes what happens when a user executes a new command:

In the current implementation, the Loan IDs are represented using integers. The added loans will be assigned IDs in increasing order starting from 0 (i.e. the first loan will be assigned ID 0, the second loan will be assigned ID 1, the third loan, ID 2, and so on).

The running ID mechanism is facilitated by the LoanIdManager class, which is a component within the LoanBook class. After initialization using the last used Loan ID value, it stores a running integer value which increments whenever the next Loan ID is generated using getNextAvailableLoanId().

Since the LoanIdManager is a component within the LoanBook class, this makes it possible to capture the internal state of the LoanIdManager at any point for future use. It allows for simple integration with the existing undo/redo mechanism, and can be stored within the same XML file that contains all other Loanbook details.

The following steps are taken when the user adds a new Loan using the add command:

Step 1: After typing an add command, the AddCommandParser will parse the user input and construct a new Loan instance with a placeholder Loan ID, which is then used to construct a new AddCommand instance.

Step 2: When AddCommand gets executed, the next available Loan ID will be generated via the Model interface. This will increment the internal running ID within the LoanIdManager of the VersionedLoanBook.

Step 3: A new Loan instance will be generated using the generated Loan ID value. This new Loan instance gets inserted into the VersionedLoanBook and gets committed.

The following sequence diagram shows how the add command functions, including the retrieval of the next Loan ID from the Model:

The authentication mechanism is provided by the Password class. It implements the following operations that facilitates authentications:

Given below is an example usage scenario and how the authentication mechanism behaves at each step:

Step 1. The user launches the application for the first time. UserPref will be initialised with a randomly generated salt by calling Password#generateSalt(), and a default hashed password from a12345.

Example of a hashing salt is:

Step 2. The user executes setpass a12345 newP4sS command to change the password to newP4sS.

Step 3. Input password will be checked against the app’s password using Password#isSamePassword() to ensure that the user has sufficient elevation to change the password of the app.

Step 4 Password class will encrypt the new password using Password#encrypt(), and call Model#setPass() to changes the password of the application in UserPref.

Example of an encrypted password:

Step 5. Password in UserPref is saved to the encrypted value of the new password input.

The following sequence diagram shows how the setpass operation works:

The following activity diagram summarizes what happens when a user executes setpass:

Step 6. The user executes a critical command delete i/1 x/a12345.

Step 7. This command runs Model#getPass() to retrieve the current password. It then call Password#isSamePassword() to determine if the input password in the command is the same as the existing password.

Step 8. Deletion of loan at index 1 will occur.

The following sequence diagram shows how the new delete operation works:

The following activity diagram summarizes what happens when a user executes delete:

The source code for this implementation can be found in ReturnCommand.java.

Returning a loan is done by setting the corresponding status of the loan to LoanStatus.RETURNED. Other than setting the enum to be returned, the cost of the loan will also be calculated and displayed to the user.

The steps that have to be done by LoanBook is as follows.

This is summarized in the following Activity Diagram:

These steps would change the given Loan object, and update the properties of the Loan object. The appropriate values stored within the Loan object would therefore change accordingly.

Given below is an example usage scenerio and how the internals of the Loan would behave:

Step 1. The user would have to do a search for which loan they would like to return. This will pull up a list of loans from which the user would be able to select the correct loan.

Step 2. Using the current system time as the endTime, the duration of the loan will be calculated. Should the duration ever be negative, an error message will be thrown. This is because such a scenario would not ever be possible in the LoanBook.

Step 3. The user decides to return the current loan (in the case of the above image, the user wants to return loan at index 3, as selected). User will therefore key in return i/3.

The LoanBook will save the current time into the LoanTime endTime field. This would be done by calling the constructor LoanTime(). Also, the loanStatus field would also be updated from ONGOING to RETURNED.

Note that originally the loan has a null value for end time. Note that the endTime and loanStatus values has been updated.

Step 4. The function now calculates the cost of the loan. This price would be based on the amount of time the loan was active for, as well as the loanRate that was set, by multiplying the time with the rate.

The result is then displayed into the GUI for the user as the cost price of the loan.

The sequence diagram has been split into 2 parts.
First, the sequence diagram of command parsing:

Second, the sequence diagram of command execution:

The source code for this implementation can be found in SummaryCommand.java.

Getting the summary of all the loans is simply done by looping through all the stored loans before and aggregating the statistics of all the loans.

Currently, the summary command displays to the user the following statistics:

This would give a very handy summary page as well as a printable audit page for the bicycle shop owners.

Given below is an example usage scenario and how the internals of the LoanBook behaves:

Step 1. The user simply has to type the summary keyword into the CLI.

Step 2. The LoanBook proceeds to loop through all the loans and aggregate the statistics of the loans.

Step 3. The LoanBook updates the display with the aggregated statistics, and this can be screenshotted by the user as a summary page.

We plan to include a feature which allows users to summarize the LoanBook based on certain parameters. For example, in future implementations, the user will be able to filter the statistics based on the identity of a bicycle.

These are the proposed features you would be able to search based on:

As well, having to recalculate all the loans would be a bad idea when the LoanBook contains many loans. A proposed solution would be to cache the results of the main summary method, so that the LoanBook would only have to recalculate the numbers based on loans that have not been added to the final tally.

Another idea would be to display all the loans in a printable table, when the summary feature is called. Perhaps this would generate a pdf file which shows all the list of loans that the LoanBook is keeping track of. Users can then take use this as a more stringent auditing tool.

addbike checks if there is a Bike with the same name already in the LoanBook, and rejects the command if so.

On the other hand, add does not check for "duplicate loans" as loans are automatically differentiated via their LoanID, even if all other parameters are the same.

editbike similarly checks if the Bike to be edited exists within the LoanBook, and whether the Bike 's new name, if specified, is the same as another Bike in the LoanBook.

Deleting Bike s from the LoanBook is currently quite unrestrictive: no constraints are imposed on the Bike that is being deleted.

The only purpose of the listbikes command is to toggle the UI to show the list of bikes. To return to viewing the list of loans, use the list command.

Internally, the MainWindow class of LoanBook keeps track of two separate UI elements: a BikeListPanel and a LoanListPanel, both inheriting from a ListPanel object. It also keeps track of which list is currently active (i.e. displayed to the user) by using a ListPanel pointer, so that only the ListPanel referred to by this pointer is displayed. When the MainWindow receives a signal (an event thrown by list or listbikes) to toggle which list is being displayed, it simply reassigns this pointer and rebuilds the display.

Hidden private information is facilitated by an interface called Censor. It is implemented by classes Nric, Phone and Email.

When showing a new loan, it will do the following operations:

Given below is an example usage scenario and how this mechanism behaves at each step.

Step1. The user adds a new loan to the LoanBook. A new LoanCard object will be created.
The LoanCard object will contain information on the loan: LoanID, BikeID, Name, Nric, Phone, Email, LoanRate and LoanTime.

Step2. Assign the value of each of the components to their corresponding labels.
For example: name.setText(loan.getName().value); will directly assign the name String of this loan to the name label.

However, the values of Nric, Phone and Email need censoring before assigning their values, so they will call their own getCensored() method in their class.
getCensored() in each of these class will call their corresponding doCensoring(int) method. Then combine the censored part and remain part and return.
For example: phone.setText(loan.getPhone().getCensored().value); will censor the value of the phone String of this loan and then assign the censored value to the phone label.

The following sequence diagram shows how this operation works:

Aspect: How to execute getCensored() and doCensoring(int)

The email sending mechanism is supported by the JavaMail library. This feature is composed of three commands: checkemail, setemail and remind.

Given below is an example usage scenario and how the reminder email mechanism behaves at each step.

Step 1. The user launches the application for the first time. The user’s email address is invalid by default.

Step 2. The user executes checkemail. The following sequence diagram shows how checkemail works:

The command executes Model#getMyEmail(), which calls UserPrefs#getDefaultEmail() and returns user’s email stored in UserPref. The app checks if user’s email equals to "default". In this case, they are equal, so it throws a CommandException.

Step 3. The user executes setemail e/EMAIL x/PASSWORDFORAPP. This command does a few checks first:

Step 4. The user forgets what email has been set before, so the user executes checkemail again. The procedure is the same as in Step 2. However, the app detects that user’s email is not the default invalid string this time, so it creates an Email(userEmail) object and executes Email#getCensored(). Then, the function returns a CommandResult with a success message and the censored user email.

Step 5. The user sends a reminder email to a customer by executing remind pw/EMAILPASSWORD id/LOAN_ID. This command implements the following operations:

Aspect: use user’s personal email vs share an immutable common email

We plan to add a feature that can automatically send an e-receipt to the customer after return ing a loan.

The e-receipt will contain the Name, BikeID, LoanStartTime, LoanEndTime and TotalCost of the loan.

When the user deletes a loan from the LoanBook, it deletes the correct loan, then commits the result into memory. What this entails is that the entire XML file gets overwritten when each delete command is being called.

From above, there is already a LoanStatus that has been implemented. What this does is that it allows the loan to be marked as deleted by setting the enum to the appropriate value. This would result in the LoanBook not needing to recommit every change.

From here, when the user decides to close the LoanBook, it will then loop through all the loans and filter out the ones which have not been deleted. These are the loans that would be kept and saved in the LoanBook.

Aspect: Deleting a loan