EzWatchlist - Developer Guide

The mark/unmark as watched mechanism is facilitated by WatchCommand which can be found under the commands package. It extends Command and uses the WatchCommandParser to process the command entered by the user.

Given below is an example usage scenario and how the mark/unmark as watched mechanism works at each step.

Step 1. The user launches the application, and executes watch 1 s/2 e/3 command to update the latest watched episode of the first show in the list.

Step 2. Entering the command calls WatchListParser#parseCommand(), which in turn returns a new WatchCommandParser and the WatchCommandParser#parse() command is called.

Step 3. A new WatchCommand is created, with the index of the show being parsed as a field of the WatchCommand. A new WatchShowDescriptor is also created to relay the episode number and season number to the WatchCommand object.

Step 4. The WatchCommand#execute() method is called, referencing the current model, and the show that is in the current FilteredShowList is referenced based off the current model.

Step 5. A copy of the show is created through the use of WatchCommand#createEditedShow(), with the new total number of seasons and episodes updated if there are any changes. A new isWatched value of the show is also determined based on the number of episodes that are watched.

The following activity diagram below summarizes the calculation of the number of episodes watched:

Step 6. The show in the current show list is updated to the newly created copy with the updated watched status and latest episode watched, and a CommandResult with the new watched status of the show is created.

The following sequence diagram shows how the watch operation works:

The statistics feature is facilitated by Statistics object. It extends EzWatchlist with a summary of the users' personal preferences and footprint including the most watched genre, shows that you might have forgotten to watch, and the recommendations generated for you. It is stored internally as an Statistics object containing a ModelManager. Additionally, it implements the following operations:

Given below is a usage scenario of a user checking his/her statistics page.

Step 1. The user launches the application. The Statistics object will be initialized with ModelManager containing the current watchlist and watched list. Behind the scenes, the 3 statistics will be calculated and the statistics panel will be populated with the result.

Step 2. The user clicks on the statistic button and sees the content.

This is the sequence diagram of getFavouriteGenre().

This is the sequence diagram of getForgotten().

This is the sequence diagram of getRecommendation().

The following activity diagram summarizes the workflow of Statistics:

All interactions with the third party library are facilitated by the interface ApiInterface. Methods in ApiInterface are the main way the application retrieves any online information from the database.

Methods in ApiInterface

ApiManager is an implementation of ApiInterface and is dependent on a java wrapper for the TMDB api implemented by Holger Brandl. Allowing us to retrieve information in the java code.

Given below is an example of how the application might want to retrieve movie information through ApiInterface.

Step 1. First an instance of a class implementing ApiInterface has to be created for the methods to be called such as ApiManager. When ApiManager is instantiated the class’s internal field Api Key 's is used to create a call object to the TMDB database. All information retrieved must go through this class’s api call object.

Step 2. The method getMovieByName("Name Of Movie") is called and the api call object is passed to the corresponding method in the class ApiUtil. The corresponding method then searches the for the movie in the database with the name given. A list of wrapped movies is given back, which is then read and used to create new instances of our application’s Show model with information wrapped in classes such as Name, Description, and Actor.

Step 3. To retrieve an image from the database, an image url is downloaded to the computer. The class ImageRetrieval does this. An ImageRetrieval instance is created by the method for each image, and is downloaded to a root folder determined by ImageRetrieval#defaultDirectory().

Step 4. A poster class is then created with the image path of the downloaded image. At any point, the poster object can be used to load images in the application.

Step 5. With the list of movies returned, the application can then read the internal Movie object returned. The Poster object in the Movie object can be used to load the poster of the movie, and the other fields can be shown to the user as seen in the figure below.

The relationship between all the classes, and their methods are shown in the following class diagram in the figure below:

Images are retrieved through the ImageRetrieval class. Which downloads the image into the computer, wrapping a Poster class with the local path of the image, for the application to access images.

Recommendations are generated through the RecommendationEngine class in the API package. Currently, recommendations are retrieved through the ApiInterface implemented in the API package.

The search mechanism is facilitated by SearchCommand which can be found under the commands package. It extends Command and uses the SearchCommandParser to process the command entered by the user.

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

Step 1. The user launches the application, goes to the Search page and executes search n/Avengers o/no command to search for shows named "Avengers" from the watchlist and watched-list.

Step 2. Entering the command calls LogicManager#execute(), which in turns calls the WatchListParser#parseCommand().

Step 3. WatchListParser#parseCommand() returns a new SearchCommandParser and the SearchCommandParser#parse() command is called.

Step 4. A new SearchCommand is created, with the hash map containing the contents to be searched as a field of SearchCommand.

Step 5. The SearchCommand#execute() method is called, referencing the current model.

Step 6. The SearchCommand#searchByName() method is called, referencing the current model.

Step 7. The SearchCommand#addShowFromWatchListIfSameNameAs() method is called, referencing the current model and name of the show to be searched from the list of shows.

Step 8. The Model#getShowFromWatchlistIfHasName() method is called, referencing the name of the show to be searched. A list of shows with the name "Avengers" is retrieved.

Step 9. The SearchCommand#addShowToSearchResult() method is called, referencing the list of the shows found in Step 7. Shows are filtered based on the possible filters and added the the SearchCommand#searchResult

Step 10. A new CommandResult is created, referencing the search message to be shown to user. This CommandResult is returned to the LogicManager.

The following sequence diagram summarizes how the search operation works based on the example above:

The AddCommand extends Command and uses AddCommandParser to process the command entered by the user.

Scenario 1: Adding show in the WatchList.

Scenario 2. Adding show found from online search.

Given below is an example usage of scenario 1 and how the add mechanism behaves at each step.

Step 1. The user launches the application and executes add n/Joker…​ command to add a show in the WatchList with the name "Joker".

Step 2. Entering the command calls AddCommandParser#parse().

Step 3. A new AddCommand is created, with the show to be added in AddCommand.

Step 4. The AddCommand#execute() method is called, referencing the current model and add the show given by user to the filteredShowList found in model.

The following activity diagram summarises the workflow of Add:

Figure 3: Activity Diagram of `AddCommand`

In Figure 3, the user first launches the app. After the user input a add command, the program runs and add the show input by user into WatchList.

This add feature is an extension to the add feature found in previous feature. It is used after user has searched for a show using search feature and the user wants to add a certain show into his watchlist.

Given below is an example usage of add feature (Extension) and how the add mechanism behaves at each step.

Step 1. The user uses the search(Online) command and executes add INDEX command to add a show from search result page of INDEX in the WatchList.

Step 2. Entering the command calls AddCommandParser#parse().

Step 3. A new AddCommand is created, with the show to be added in AddCommand.

Step 4. The AddCommand#execute() method is called, referencing the current model and add the show given by user to the searchList of INDEX found in model.

The following sequence diagram shows how the add extension operation works:

The following activity diagram summarises the workflow of Add extension:

Figure 4: Activity Diagram of `AddCommand`

In Figure 4, User input search(online) command. User then input add INDEX command. Show of INDEX found in search result page is added to WatchList.

The Synchronise feature is facilitated by SyncCommand object which can be found under the commands package. It extends Command and uses the SyncCommandParser to process the command entered by the user.

Given below is an example usage scenario and how the Synchronise command work as Sync mechanism works at each step.

Pre-Condition: User has already added a certain show into watchlist manually. That show must have at least name and type parameters. Example of Pre-Condition: User has added Titanic movie into watchlist.

Step 1. The user launches the application, go to Search page and execute search n/titanic.

Step 2. The user execute sync 1 command to synchronise index 1 of result page with a show in watchlist with same name (case-insensitive).

Step 3. Entering the command calls SyncCommandParser#parseCommand(), which in turn returns a new SyncCommandParser and the SyncCommandParser#parse() command is called.

Step 4. A new SyncCommand is created, with the index of the show being parsed as a field of the SyncCommand.

Step 5. The SyncCommand#execute() method is called, referencing the current model, and the show that is in the current FilteredShowList is referenced based off the current model.

Step 6. A list of shows found in search page and watchlist are retrieved from model. The show according to the Index of the searchpagelist are retrieved as well. Then, the list of show in watchlist will be checked through to match the name of the index show.

Step 7. If a show in watchlist matched with the name of the index show, model.setShow will be called to replace the show found in watchlist with index show. CommandResult will be return which contains information regarding the feedback result. Else, CommandException is thrown to notify user no similar show name is found in watchlist as index show.

The following sequence diagram shows how the sync operation works:

The following activity diagram summarises the workflow of Sync: