Alden - Project Portfolio

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.