Coupon Stash v1.4 - Developer Guide

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 CouponStash will be initialized with the initial coupon stash state, and the currStateIndex pointing to that single coupon stash state.

Step 2. The user executes delete 5 command to delete the 5th coupon in the coupon stash. The delete command calls Model#commitCouponStash(String commandText), causing the modified state of the coupon stash after the delete 5 command executes to be saved in the couponStashStateList, and the delete 5 command text to be stored in the commandTextHistory. currStateIndex is shifted to the newly inserted coupon stash state.

Step 3. The user executes add n/OMO STORE …​ to add a new coupon. The add command also calls Model#commitCouponStash(String commandText), causing another modified coupon stash state and command text to be saved into the couponStashStateList and commandTextHistory respectively.

Step 4. The user now decides that adding the coupon was a mistake, and decides to undo that action by executing the undo command. The undo command will call Model#undoCouponStash(), which will shift the currStateIndex once to the left, pointing it to the previous coupon stash state, and restores the coupon stash to that state. Plus, the command text is returned, thus allowing for the display of the command that was undone. In this case, the command undone is add n/OMO STORE…​.

The following sequence diagram shows how the undo operation works:

The redo command does the opposite — it calls Model#redoCouponStash(), which shifts the currStateIndex once to the right, pointing to the previously undone state and command text, and restores the coupon stash to that state. Finally, it returns the redone command text.

Step 5. The user then decides to execute the command list. Commands that do not modify the coupon stash, such as list, will not call Model#commitCouponStash(). Thus, the couponStashStateList remains unchanged.

Step 6. The user executes clear, which calls Model#commitCouponStash(). Since the currStateIndex is not pointing at the end of the couponStashStateList, all coupon stash states and command text history after the currStateIndex will be purged. We designed it this way because it no longer makes sense to redo the add n/OMO STORE …​ 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 text:

The Calendar component provides a visual representation of the stored coupons that are expiring over a month. It is facilitated by CalendarPane, DateCell, ObservableList<Coupon> and ObservableMonthView.

The CalendarPane is the controller of the Calendar on display. Users can change the month on display to show the coupons that expire during a specific month year by clicking on the arrows at the sides of the calendar’s title or by using the goto command.

Each DateCell represents each date of the month that is currently on display. Each DateCell uses the ObservableList<Coupon> to keep a list of the coupon(s) that expires on each date. A DateCell with coupon(s) expiring on the date are highlighted in red and a Datecell that represents the system’s date is highlighted blue.

The ObservableList<Coupon> is the list of filtered coupons that are currently on display in the CouponListPanel. They are obtained by calling the Logic#getFilteredCouponList() method. The list can be filtered to view all active, archived or used coupons using the expiring command .

The ObservableMonthView is the current month & year on display in the Calendar Pane. It is obtained by calling the Logic#getMonthView() method.

The class diagram below shows the interaction between classes that affects the Calendar:

The sequence diagrams below show how the Calendar works:

The two scenarios below are examples of how the Calendar mechanism behaves at each step of each scenario.

The archiving of coupons is facilitated by the Archived attribute of a coupon. The following methods in the CouponStash, Coupon, Usage, UsedCommand class and the Model interface facilitates this feature:

Given below is two example usage scenarios and how the archiving mechanism behaves at each step of each scenario. An activity diagram is provided first to describe the general events that will lead to an automatic archiving of coupons by Coupon Stash.

Archiving of Expired Coupons

Expired coupons are automatically archived by Coupon Stash upon start up of the application. The following steps describe how this behaviour is implemented.

Step 1. The user launches the application for the first time. The initiation of ModelManager will also trigger the initiation of CouponStash with any available saved data.

Step 2. The method CouponStash#archiveExpiredCoupons will be called from the newly initiated CouponStash, and have its UniqueCouponList mapped to a function that archive coupons that has expired before the date of opening the application, and returns a new updated CouponStash. This mapping function is facilitated by Coupon#hasExpired() and Coupon#archive().

Step 3. The ModelManager will proceed to filter out the archived coupons from the newly updated CouponStash, and return a filtered list of active coupons. This filtering is facilitated by the predicate Model#PREDICATE_SHOW_ALL_ACTIVE_COUPONS.

Archiving of Exhausted Coupons

Coupons that have exhausted its usages will be automatically archived by the application. The following steps describe how this behaviour is implemented.

Step 1. The user uses a Coupon in the current observable CouponStash with the command used 1. UsedCommand is created with the parsed arguments, and executed. The particular Coupon will then have its Usage increased by one by calling Coupon#increaseUsageByOne().

Step 2. The Coupon will then be checked if its Usage has reached its Limit, using the Usage#isAtLimit() method. For the purpose of this explanation, we assume that the coupon being used has a usage Limit of 1 and a previous Usage value of 0, with savings in MonetaryAmount.

Step 3. The Coupon will have a new Archived value, which will be set to true if the Usage has indeed reached its Limit. This is facilitated by Coupon#archive().

Step 4. The CouponStash will be updated with this used Coupon with the ModelManager#setCoupon() method. Under the hood of this method, the current FilteredList will be updated to show active Coupons only, facilitated by the predicate Model#PREDICATE_SHOW_ALL_ACTIVE_COUPONS.

The retrieving of command history via the up and down arrow keys is facilitated by the CommandTextHistory class. The command history is stored internally as a LinkedList used as a stack with a currIndex tracking the next command in the history to return. The following methods and attributes in the CommandTextHistory class facilitates this feature:

Given below is an example usage scenario and how the up/down button presses behaves at each step.

Step 1. The user launches the application for the first time. The CommandTextHistory is initialized with a stack containing only an empty string (""), and the currIndex is set to 0.

Step 2. The user executes delete 1. CommandBox#handleCommandEntered() will call CommandTextHistory#add(String commandText) to save the entered command into the stack contained in CommandTextHistory. The top of the stack (i.e. the empty string) is popped off first, before the entered command is pushed onto the stack. Then, the empty string is pushed onto the stack again, thus ensuring that the empty string stays at the top of the stack. Note that currIndex is not affected.

Step 3. The user executes delete 2. CommandBox#handleCommandEntered() will also save the entered command into the stack contained in CommandTextHistory. As in the previous step, the new command is pushed to the top of the stack, just below the empty string.

Step 3. Now, the user decides to delete the second coupon again. We press the arrow key up once, and CommandBox#commandTextField has a listener that calls CommandTextHistory#getUp(). The currIndex is incremented, and then the command text pointed to by currIndex is returned and displayed in the program command box.

Step 4. The user then executes the retrieved command (delete 2). As in the previous steps, this newly executed command is pushed to the top of the stack just below the empty string. However, in such a case when the currIndex is not 0 and does not point to the top of the stack, it is reset to 0.

The down arrow key does the opposite, it will lead to the calling of CommandTextHistory#getDown(), which shifts the currIndex one item higher (i.e. decrement the currIndex by 1), before returning the command text pointed by the updated currIndex.

Below is a sequence diagram describing the events that happen when a user presses a key.

Below is a sequence diagram describing the events that happen when a executes a command text, thus triggering the saving of a command text into CommandTextHistory.

The sorting of coupons in the coupon stash is facilitated by the following static variables in the SortCommand class and this methods in the Model interface and SortedList class.

When a sort command is executed, the field to sort by is indicated by the inputted prefix. The sequence diagram below describes what happens when a sort command is run.

Depending on the prefix to sort by, ModelManager#sortCoupons() will be called with the relevant comparator as its argument. The ModelManager#sortCoupons() method subsequently calls the SortedList#setComparator() method (not shown in the above diagram), which leads to a change of the comparator of the SortedList stored in ModelManager , thus triggering a sort of the SortedList.

The following activity diagram depicts what happens when the user runs a edit command to edit a coupons’s RemindDate.

After establishing the remind dates for all the coupons, the next step is ensure that there will be a reminder pop up (if necessary) upon opening the application.

The following steps describe how to reminder pop up works:

Aspect: How to keep track of coupon remind date

All in all, we chose alternative 1 as we feel that it is good for users to be able to view the remind date of a coupon in the coupon view. Additionally, all speed-ups and efficiency of storing the remind dates in a separate data file is nullified by the fact that we still need to loop through all coupons to display their remind dates on the calendar component. Thus, to make it easier to extend the program in the future, we decided against adding another data file which can make extension more complicated, and chose to work with alternative 1.

Just for reference, the image below shows the class diagram for the Savings class. It is compulsory for each Coupon to contain an Savings object, that represents what the user would gain from 1 use of that Coupon.

A Savings object can hold a PercentageAmount, MonetaryAmount or Saveables, which represents discounts like "$5 off", "10% off" and "free door gift" respectively.

The table below shows which are valid Savings objects, and which are not.

As can be seen from the table, Savings cannot be completely empty, and Savings cannot have both a MonetaryAmount and PercentageAmount (it does not make much sense to have a voucher that says "10% and $5 off").

In order to calculate the total amount saved, Coupons also store information about how much the user saves, and storage is done at the moment the user uses the coupon. This information is stored in the form of PureMonetarySavings, which is a subclass of Savings that never holds PercentageAmounts. The class diagram below illustrates this.

The reason why PercentageAmounts are not allowed in accumulated savings is because a percentage discount is a relative value that depends on the original price of the product, and cannot be easily added up in a way that allows users to accurately measure how much they have saved from their coupons.

PureMonetarySavings are stored in a DateSavingsSumMap, which is a hash table that links the current date (LocalDate) to the savings earned (PureMonetarySavings) on that date. Each Coupon holds a DateSavingsSumMap. The next image shows the class diagram of the DateSavingsSumMap.

The following section describes the processes that follow whenever a user marks a Coupon as "used" with the used command.

When the user enters a used command, the actions taken by Coupon Stash change depending on whether the Coupon’s Savings stores a MonetaryAmount of PercentageAmount. The following activity diagram shows what happens when the user runs a used command.

In terms of the implementation, the next two images shows the sequence diagram that models the successful execution of a used command within the actual program components.

More specifically, the used command executed is used 1 $100, and the state of the system is such that a Coupon with PercentageAmount in its Savings (no MonetaryAmount) and with Usage not at its Limit is located at index 1. Also, the money symbol set in the user preferences would be $, which makes this command a valid one that will execute successfully.

The money symbol set in the user preferences is retrieved by CouponStashParser, which passes it to UsedCommandParser that will use this symbol to parse the used command.

Also, within UsedCommand, the UsedCommand#execute() method will cause the creation of a new Coupon with the correct recorded number of uses and amount of savings earned. The next sequence diagram shows how a successful UsedCommand#execute() method produces the new total savings value for the new Coupon.

In the end, the total savings value of the Coupon is updated. This total savings is represented by a DateSavingsSumMap.

One key implementation within the UsedCommand is the checks that it has to make to ensure the valid usage of a Coupon. Below is an activity diagram to show the flow of checks within the UsedCommand#execute() method.

Now that we have seen how the used command works, we can look at how the saved command works. While used stores the amount of savings that the user has earned on a particular day, saved retrieves the amount of savings earned as recorded by Coupon Stash, given a particular time period.

The saved command works similarly to the used command, where a SavedCommandParser will be created by Logic to split up the raw String into its arguments, creating a SavedCommand. Let’s look at how a SavedCommand would be executed.

Hence the SavedCommand loops through all Coupons to add up the savings earned from a particular time period, or from all dates if no time period is specified.

Based on the User Stories, there is a desire for tracking how much one has saved by using Coupon Stash, as well as for viewing total savings easily. Below are some alternative implementations of savings tracking and viewing that were considered by the developers, but were rejected in favour of the current implementation.

Alternatives:

This would make the implementation of Savings much simpler, as there would not be a need for separate classes like PercentageAmount, MonetaryAmount and Saveables. However, this might burden the user with calculating how much they would save in terms of dollars and cents, when many coupons and discounts come in the form of certain percentage reductions of the original price, as well as free gifts or benefits that cannot be translatable to a concrete monetary amount.

Hence, it was decided to rely on a few different representations of Savings that can be earned from using a Coupon, as well as a Savings class that could refer to any of these representations, or even a logical combination of these representations.

This would eliminate the need for the intermediary Savings class and reduce complication in the program code slightly. But, it would be difficult to ensure that at least one such field exists in the Coupon, or guarantee that the Coupon would have one such field.

The Coupon class would have to hold the logic for determining whether it had a valid combination of MonetaryAmount, PercentageAmount and Saveables, which does violate Single Responsibility Principle as the Coupon class now has another reason to change (if we would want to allow both MonetaryAmount and PercentageAmount on a Coupon for instance).

Hence the Savings class was decided to handle this responsibility, as well as abstract away the implementation details of the multiple possible values and combinations of these values. This allows the Coupon to think in terms of an entire Savings object, rather than handle multiple different scenarios depending on which fields it has.