search

sirin05137 / CSE364_Project

2 stars 0 forks source link

readme

CSE364 Group11

Table of Contents

About the Project

This project is for the capstone project in SW Engineering (CSE364) at UNIST, developed by Yeongjun Kwak, Sanghun Lee and Yujin Lee. This will be further inplemented as a movie recommendation system. Currently under the development···

Built with

Repository Structure

CSE364_Project/
├── data/                             # Source data
├── scripts/                          # Documentation files
├── src/                              # Source files
│   ├── main/
│   │   └── java/
│   │       └── group11/
│   │       │   └── restservice/
│   │       └── resources/
│   └── test/
│       ├── java/
│       │   └── group11/
│       └── resources/   
├── target/                           # Generated when mvn install
│   └── site/
│       └── jacoco/                           
│           └── index.html            # JaCoCo Code Coverage Report                
├── pom.xml                           # Maven configuration
├── mvnw                              # Maven configuration
├── mvnw.cmd                          # Maven configuration
└── README.md

Getting Started

Instructions for setting up the project locally.

Prerequisites

Installation

  1. Download dockerfile and run.sh in the same directory.
  2. (In the terminal) Build Docker Image and Container by running the following commands. 
    $ docker build -t new_image_name /path/to/dockerfile
    $ docker run -it new_image_name
  3. (In the Docker Container) Run . run.sh 
    root@containerID:~/project# . run.sh

Milestone 1

Goal : Environment setup, data loading, data preprocessing

Explanation of the Algorithm

On Milestone 1, the code calculates and returns the average rating from ratings data for specified occupation and genre.

Running the Test

Continued from Installation steps.

  1. (In the Docker Container) Run Java command with 2 arguments (InputStr1 InputStr2), accordingly Genre and Occupation input. 
    root@containerID:~/project# java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project InputStr1 InputStr2

Examples

When valid inputs are passed, the output message will look like this :

// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Adventure Educator
// Output
3.42
// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Animation Doctor
// Output
3.68

Supported Inputs

Genre total:18
Action Crime Horror Thriller
Adventure Documentary Musical War
Animation Drama Mystery Western
Children's Fantasy Romance
Comedy Film-Noir Sci-Fi
Occupation total : 21
Academic (Educator) Executive (Managerial) Programmer Technician (Engineer)
Artist Farmer Retired Tradesman (Craftsman)
Clerical (Admin) Homemaker Sales (Marketing) Unemployed
Collegestudent (College, Grad, Gradstudent) K-12student Scientist Writer
Customerservice Lawyer Self-employed Other
Doctor (Healthcare)

Rules for the Inputs

Combination of Multiple Genres as an Input

Error Codes

Possible errors thrown by invalid user input.

Table 1 Invalid input errors
Error Code Message Description
InputEmptyError 1 No argument has passed. 2 arguments are required. (InputStr1 InputStr2) Thrown when no input has entered.
InputNumError 2 Only 1 input has passed. 2 arguments are required. Thrown when only 1 input has entered.
InputNumError 3 More than 2 arguments have passed. 2 arguments are required. Thrown when more than 2 inputs have entered.
InputInvalidError 4 Entered genre input is invalid Thrown when the entered genre (combination) is invalid.
InputInvalidError 5 Entered genre (inputString) doesn't exist. ( Invalid word : input_string ) Thrown when the word in the entered genre (OR the word in genre combination) is invalid.
Table 2 Invalid input warning
Warning Code Message Description
InputInvalidWarning 6 Entered occupation doesn't exist. Rating by 'other' is shown instead. Thrown when the 2nd input is invalid.
Table 3 No data exist error
Error Code Message Description
NoDBError 7 Rating data matching the input pair doesn't exist. Thrown when there's no available Rating data for the genre-occupation pair OR When there's no Movie data matching the entered genre (combination).

Examples for the Error Codes

Error code : 1~3
% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project 

InputEmptyError : No argument has passed. 2 arguments are required. (InputStr1 InputStr2)
Error code: 1

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Drama

InputNumError : Only 1 input has passed. 2 arguments are required.
Error code: 2

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Drama Scientist Scientist

InputNumError : More than 2 arguments have passed. 2 arguments are required.
Error code: 3
Error code: 4
% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "|Adventure|Action" Scientist          

InputInvalidError : Entered genre input is invalid.
Error code: 4

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "Adventure|Action|" Scientist 

InputInvalidError : Entered genre input is invalid.
Error code: 4
Error code: 5
% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "Adventure|Action|Horrrror" Scientist

InputInvalidError : Entered genre (horrrror) doesn't exist.
Error code: 5
Error code: 6
% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project Adventure Librarian                  

InputInvalidWarning : Entered occupation doesn't exist. Rating by 'other' is shown instead.

The rating of adventure rated by other : 3.43
Error code: 7
% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "War|Crime" Academic  

NoDBError : Rating data matching the input pair doesn't exist.
Error code: 7

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.project "Action|Animation|Children's|Sci-Fi|Thriller|War" retired

NoDBError : Rating data matching the input pair doesn't exist.
Error code: 7

About Junit Test

The Junit test (and regarding csv test resources) for Milestone 1 has been moved to scripts/. For more information, please refer to this issue #20

Contribution by Area

Area Contribution
Setting up a Git Repository Yeongjun Kwak
Environment Setup dockerfile, pom.xml
Yujin Lee
Java Implementation Models and Data Structures
👑 Yeongjun Kwak
Exception Handling
👑 Sanghun Lee, Yeongjun Kwak
Unit Test Building
Yujin Lee
Final Reviewer
Sanghun Lee, Yeongjun Kwak
Documentation README.md
👑 Yujin Lee, Sanghun Lee


Milestone 2

Goal : Implement Top 10 Movies Recommendation Features

Explanation of the Algorithm

On Milestone 2, the code returns the recommendation of Top 10 movies for specified gender, age, occupation or genre(s). First, to recommend 'relevant' movies, the code makes use of 1) Bayesian Estimate, which is used to calculate Top 250 movies by IMDB as well, when calculating and comparing the ratings of movies. Also, to set the 'similar' users (in case there aren't enough ratings that match gender, age and occupation), we have set 2) Priority rule for including similar users.

To briefly explain how the algorithm works :

  1. First, it makes the ArrayList(valid_user_list) of users that matches the inputs from users.dat.
  2. And then, it extracts the ratings information and movie data from ratings.dat and movies.dat using valid_user_list.
  3. Check if there aren't sufficient amount of movie candidates to be ranked (On here, it is set to 100 movies) for specified user data OR when m is too small for the movie candidates (On here, it is set to 10 votes), If the conditions are not met -> 4. If all the conditions are met -> 5.
  4. 'Similar' users will be added to valid_user_list in order of precedence (priority) by function make_intersection_list_macro. After adding the similar users, it will repeat the steps from 2 with added valid_user_list again (Until the conditions on Step 3 is met).
  5. Print out Rank Top 10 movies based on calculated Weighted Rating(R).

1) Bayesian Estimate

Bayesian Estimate is an estimator that can help minimizing the risk of including that minimizes the posterior expected value of a loss function. By making use of Bayesian Estimate, the algorithm calculates Weighted Rating (W) and arranges movies with W. In this way, the movies with very few ratings or below-average ratings will have comparably light weight.

In Detail, the calculation of Weighted Rating(W) is implemented by

The original reference for Baysian Estimate can be found here. However, in this project, the estimation method and variables has been set differently to adjust the differences in requirements.

W = (vR+mC)/(v+m)

Variables Explanation
W Weighted rating
v Total number of ratings for the movie = (votes)
m Minimum number of ratings required to be listed in the Top 10
R Average rating for the movie as a number from 0 to 5 (mean)
C Average rating across all the movies

2) Priority rule for including similar users

The algorithm firstly makes the ArrayList(valid_user_list) of users that matches the inputs from users.dat. And then, this list is used to extract the ratings information and movie data from ratings.dat and movies.dat.

However,

The similar users with priority are the users with :

  1. Same Gender, Occupation and Gender
  2. Same Gender and Occupation
  3. Same Age range and Occupation
  4. Same Occupation
  5. Same Gender and Age range
  6. Same Gender
  7. Same Age range
  8. All the users

The priority has set as above to give a more weighting on Occupation, and less on Gender and Age Range.


Running the Test

Continued from Installation steps.

  1. (In the Docker Container) Run Java command with 3 or 4 arguments. The Arguments(InputStr1 InputStr2 InputStr3 InputStr4) are accordingly Gender, Age, Occupation, (and Genre). 
    root@containerID:~/project# java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 InputStr1 InputStr2 InputStr3 InputStr4

Examples

When valid inputs are passed, the output message will look like this :

Testing with 3 inputs
// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent"

// Output
Sixth Sense, The (1999) (http://www.imdb.com/title/tt0167404)
Matrix, The (1999) (http://www.imdb.com/title/tt0133093)
Shawshank Redemption, The (1994) (http://www.imdb.com/title/tt0111161)
Usual Suspects, The (1995) (http://www.imdb.com/title/tt0114814)
Silence of the Lambs, The (1991) (http://www.imdb.com/title/tt0102926)
Close Shave, A (1995) (http://www.imdb.com/title/tt0112691)
Wrong Trousers, The (1993) (http://www.imdb.com/title/tt0108598)
Cinema Paradiso (1988) (http://www.imdb.com/title/tt0095765)
American Beauty (1999) (http://www.imdb.com/title/tt0169547)
Raiders of the Lost Ark (1981) (http://www.imdb.com/title/tt0082971)
Testing with 4 inputs
// Input
java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent" "Action|Comedy"

// Output
Matrix, The (1999) (http://www.imdb.com/title/tt0133093)
Close Shave, A (1995) (http://www.imdb.com/title/tt0112691)
Wrong Trousers, The (1993) (http://www.imdb.com/title/tt0108598)
American Beauty (1999) (http://www.imdb.com/title/tt0169547)
Shakespeare in Love (1998) (http://www.imdb.com/title/tt0138097)
Raiders of the Lost Ark (1981) (http://www.imdb.com/title/tt0082971)
Cinema Paradiso (1988) (http://www.imdb.com/title/tt0095765)
Eat Drink Man Woman (1994) (http://www.imdb.com/title/tt0111797)
Raising Arizona (1987) (http://www.imdb.com/title/tt0093822)
Breakfast Club, The (1985) (http://www.imdb.com/title/tt0088847)

Supported Inputs

InputStr1 InputStr2 InputStr3 (InputStr4)
Gender Age Occupation (Genre)
Testing with 3 inputs
// Examples of Supported Inputs
“F” “25” “Gradstudent”
“M” “30” “Athletes”
“F” “” “retired”
“” “15” “”
“” “” “”

// Examples of Wrong Inputs
"F" "25"           // Empty part must be explicitly specified by ""
"25" "Gradstudent" // Empty part must be explicitly specified by ""
Testing with 4 inputs
// Examples of Supported Inputs
“F” “25” “Grad student” “Action|Comedy”
“M” “30” “Athletes” “Children’s”
“F” “” “retired” “Animation|Drama|Fantasy”
“” “15” “” “Sci-Fi”
“” “” “” “Romance|Comedy”

// Examples of Wrong Inputs
“F” “25” “Grad student” “”  // The genre must not be left empty.
“F” “25” “Grad student” “Action|Comedy” "Drama" // Extra arguments are not allowed.


Error Codes

Possible errors thrown by invalid input.

Table 1 Invalid input errors
Error Message Description
InputNumError The input must be in this format : "gender" "age" "occupation" "genre" (genre is optional). Thrown when the number of argument is not 3 or 4.
InputInvalidError Entered gender input is invalid. Thrown when the entered gender is invalid.
InputInvalidError Entered age input is invalid. Age must be a natural number. Thrown when the entered age is invalid.
InputInvalidError Entered occupation (inputString) doesn't exist. Thrown when the entered occupation is invalid.
InputInvalidError Entered genre input is invalid. Thrown when the entered genre is invalid. (e.g. Location of pipeline |)
InputInvalidError Entered genre (inputString) doesn't exist. Thrown when the entered genre is invalid.
InputEmptyError Genre input hasn't passed. Genre must not be empty Thrown when the "" is passed for the genre input.
Table 2 No data exist error
Error Message Description
NoDBError There are no movie available for more than m votes Thrown when there's no available movie list. This error is not likely to happen but implemented to prevent any error.
NoDBError There are no movie available for specified inputs. Thrown when there's no available movie list or there exist movie(s) with no votes only. This error is not likely to happen but implemented to prevent any error.

Examples for the Error Codes

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 
InputNumError: The input must be in this format : "gender" "age" "occupation" "genre" (genre is optional).

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "Female" "25" "Gradstudent"
InputInvalidError : Entered gender input is invalid.

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "12.5" "Gradstudent"
InputInvalidError : Entered age input is invalid. Age must be a natural number.

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Lizard"       
InputInvalidError : Entered occupation (Lizard) doesn't exist.

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent" "Action|Adventure|"
InputInvalidError : Entered genre input is invalid.

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent" "ACCCCCTION"
InputInvalidError : Entered genre (accccction) doesn't exist.

% java -cp target/cse364-project-1.0-SNAPSHOT-jar-with-dependencies.jar group11.milestone2 "F" "25" "Gradstudent" ""          
InputEmptyError : Genre input hasn't passed. Genre must not be empty


About JUnit Test

The JaCoCO plugin (ver : 0.8.2) is used for this JUnit Test to generate the code coverage report. The Code coverage goal for this project has been set to 0.9 (90%). The code coverage report index.html can be found in target/site/jacoco/ directory and viewed with chrome or other extensions.

Example of Report

image

Contribution by Area

Area Contribution
Java Implementation Models and Data Structures
👑 Yeongjun Kwak
Exception Handling
👑 Sanghun Lee, Yeongjun Kwak
Unit Test Building
👑 Yujin Lee
Documentation README.md
👑 Yujin Lee


Milestone 3

Goal :

  • Implement RESTful web service
  • Movies Recommendation Feature based on the Movie title (and limit).

Explanation of the Algorithm

On Milestone 3, the new feature has added to provide movies recommendation from the Movie title input. The code returns the input-specified numbers(limit, default = 10) of movies for the specified movie title.

The algorithm is built based on the two concepts below : 1) Item-based Collaborative Filtering 2) Genre-based Recommendation

1) Item-based Collaborative Filtering

Collaborative Filtering recommends movies by calculating the similarity between the specified movie (input) and the others. Collaborative Filtering are subdivided to two methods ; User-based and Item-based. ([reference](Recommender Systems — User-Based and Item-Based Collaborative Filtering))

This program uses Item-based Collaborative Filtering. i.e. if a user group who highly rated Movie A have rated Movie B highly, the Movie A and Movie B are considered to be similar.

Step-by-step Explanation of Algorithm

  1. First, to measure the similarity between movies, Pearson correlation coefficient has used. The details for Pearson correlation coefficient can be found here. The formula to get Pearson correlation coefficient is as below : image

    The method in program (milestone3.java) that implements the Pearson correlation coefficient is as below :

    static double get_pearson_similarity(HashMap<String, Integer> rating, HashMap<String, Integer> rating_of_input, double mean_rating_of_input, double distance_of_input)


  2. After getting the similarity between movies by Pearson correlation coefficient, the movies are sorted by decreasing similarity order.

    Example - Movies sorted by decreasing similarity order

    image

    When the sorting has finished, the program adds (1.5 * limit) numbers of items from this list to ArrayList<Movie_data_node> movie_data_table. (If the input was "Superman (1978)", it excludes the same movie when adding as the same movie as input should be excluded in the recommendation result.)


  1. After then, the program calculates the Weighted Rating by adding Pearson correlation coefficient and IMDB Weighted Rating. (The IMDB weighted rating here is same from milestone2.)

    • Recap for IMDB Weighted Rating W = (vR+mC)/(v+m)
      Variables Explanation
      W Weighted rating
      v Total number of ratings for the movie = (votes)
      m Minimum number of ratings required to be listed in the Top 10
      R Average rating for the movie as a number from 0 to 5 (mean)
      C Average rating across all the movies

    • The reason of adding Pearson correlation coefficient and IMDB Weighted Rating is that it can give more weight on the movies with higher similarity.

      For example, when the input is "Superman (1978), the movies "Superman II (1980)" and "Superman III (1983)" get to have high similarity with the input from the method above.

      However, these movies have comparably low average rating (from users). To give more weight on these movies (high similarity but low rating), Pearson correlation coefficient and IMDB Weighted Rating has added.

    • The value of v and R above can be easily calculated from Movie_data_node. And the value of m and C can be calculated from the methods each below :

      static int percentile(ArrayList<Movie_data_node> movie_rating_matrix, double p)
      static double total_average_rating(ArrayList<Movie_data_node> movie_rating_matrix)

      The two methods above are imported from the milestone2. And the value of p in Percentile method is set to 0 (zero) here. (If p > 0, the movies with high similarity can be ignored)

  2. Lastly, the classified_table(ArrayList) are made by selecting the items with more than m vote counts from movie_data_table. And then, the program sorts the list with decreasing Weighted Rating value and prints out the upper limit number of movies.


2) Genre-based Recommendation

Intro - The Weakness of Item-based Collaborative Filtering

The Genre-based Recommendation has implemented to complement the weakness of Item-based Collaborative Filtering. The weaknesses of Item-based Collaborative Filtering are :

In these cases, the recommendation output is not reliable or cannot be calculated. To complement this weaknesses, when the number of ratings for the movie input is less than 100, Genre-based recommendation is used.

Genre-based recommendation generates movie recommendation by calculating the similarity between the genre(s) of input movie's and others'.

Step-by-step Explanation of Algorithm

  1. First, To measure the similarity, the algorithm uses Jaccard similarity. The formula to get Jaccard similarity is as below : image

    The method in program (milestone3.java) that implements the Pearson correlation coefficient is as below :

    static double get_jaccard_similarity(ArrayList<String> movie_data ,ArrayList<String> genre_of_input_list)

  2. After getting the similarity between movies by Jaccard similarity, the movies are sorted by decreasing similarity order. On here, there's 3 cases regarding the similarity and number of movies to recommend (limit).

    • Case 1, The similarity of (limit1.5)th movie is not 0 (A : the similarity of (limit1.5)th movie) Add all the movies with similarity 1~A to ArrayList<Movie_data_node> movie_data_table. In this case, the length of List is bigger than (limit*1.5) as the movies with similarity A are also added.
    • Case 2, The similarity of (limit1.5)th movie is 0 but (limit)th movie's is not 0 (B : the similarity of (limit)th movie) Add all the movies with similarity 1~B to ArrayList<Movie_data_node> movie_data_table. In this case, the length of List is bigger than (limit) and smaller than (limit1.5) as the movies with similarity B are also added.
    • Case 3, The similarity of (limit)th movie is 0 Add all the movies with non-zero similarity to ArrayList<Movie_data_node> movie_data_table. Calculate the IMDB weighted rating for the movies with zero similarity and Add (limit - listlength) number of movies to movie_data_table. The same movie with the movie input is excluded for the recommendation when adding movies to movie_data_table.

  3. After then, the program calculates the Weighted Rating (in IMDB weighted rating way) The value of p here in Percentile method is calculated from the method below :

    static double get_ratio(int a, int b)

  4. Lastly, the classified_table(ArrayList) are made by selecting the items with more than m vote counts from movie_data_table. And then, the program sorts the list with decreasing Weighted Rating value and prints out the upper limit number of movies.

Interpretation of the Algorithm Output

When the Item-based collaborative filtering is used, the program sorts the movies in decreasing similarity order and rank the 1 ~ (limit*1.5)th movies with altered IMDB weighted rating. However, this rank gets differ greatly depends on the size of limit.

If there's movie A and movie B, as limit gets bigger and bigger, the highly placed movies in output gets similar.

Running the Test

Continued from Installation steps.

  1. (In the Docker Container) Run ./mvnw spring-boot:run 
    root@containerID:~/project# ./mvnw spring-boot:run
  2. Open another terminal and type the curl command there. 
    // sample command
curl -X GET 'http://localhost:8080/movies/recommendations' \
-H 'Content-type: application/json' \
-d '{ "title": "Toy Story (1995)", "limit": 3 }'

    To access the docker that is running on #1, On another terminal, use docker ps to get the running container's ID and type docker exec -it (containerID) (your_own_bash_command). i.e. you can put the curl command on the your_own_bash_command field above.

Examples

When valid inputs are passed, the output message will look like this :

[ {
  "title" : "Toy Story 2 (1999)",
  "genre" : "Animation|Children's|Comedy",
  "imdb" : "http://www.imdb.com/title/tt0120363"
}, {
  "title" : "Bug's Life, A (1998)",
  "genre" : "Animation|Children's|Comedy",
  "imdb" : "http://www.imdb.com/title/tt0120623"
}, {
  "title" : "Beauty and the Beast (1991)",
  "genre" : "Animation|Children's|Musical",
  "imdb" : "http://www.imdb.com/title/tt0101414"
} ]
Testing for the Milestone 2 feature

Movie recommendation based on gender / age / occupation / genre

Below is curl command example for GET requests passing the user input in JSON type Test with different json body parts as your need.

// Input
curl -X GET 'http://localhost:8080/users/recommendations' \
-H 'Content-type: application/json' \
-d '{"gender":"F", "age":"25", "occupation":"Grad student", "genre":"Action"}'

// Output - Top 10 movies are returned.
[ {
  "title" : "Princess Bride, The (1987)",
  "genre" : "action|adventure|comedy|romance",
  "imdb" : "http://www.imdb.com/title/tt0093779"
}, {
  "title" : "Matrix, The (1999)",
  "genre" : "action|sci-fi|thriller",
  "imdb" : "http://www.imdb.com/title/tt0133093"
}, {
  "title" : "Raiders of the Lost Ark (1981)",
  "genre" : "action|adventure",
  "imdb" : "http://www.imdb.com/title/tt0082971"
},
...
Testing for the Milestone 3 feature

Movie recommendation based on the movie title / limit

Below is curl command example for GET requests passing the movie input in JSON type Test with different json body parts as your need.

// Input
curl -X GET 'http://localhost:8080/movies/recommendations' \
-H 'Content-type: application/json' \
-d '{ "title": "Toy Story (1995)", "limit": 3 }' 

// Output - (limit) number of movies are returned.
// (when limit is not specified, 10 movies are returned.)                          
[ {
  "title" : "Toy Story 2 (1999)",
  "genre" : "Animation|Children's|Comedy",
  "imdb" : "http://www.imdb.com/title/tt0120363"
}, {
  "title" : "Bug's Life, A (1998)",
  "genre" : "Animation|Children's|Comedy",
  "imdb" : "http://www.imdb.com/title/tt0120623"
}, {
  "title" : "Beauty and the Beast (1991)",
  "genre" : "Animation|Children's|Musical",
  "imdb" : "http://www.imdb.com/title/tt0101414"
} ]%

Supported Inputs

Testing for the Milestone 2 feature
Testing for the Milestone 3 feature


Error Codes

Possible errors thrown by invalid json body input.

When invalid input is put, the web service returns the error message (json body) with Http Status code 400 (Bad Request)

Examples for the Error Codes

For the Milestone 2 feature

Input (json body)

{
    "gender": "ABCD",
    "age": "EFG",
    "occupation": "HIJK",
    "genre": "LMN|OP"
}

Output (json body) - Status code 400 Bad Request

{
    "error": "InputInvalidError",
    "message": [
        "Entered gender input (ABCD) is invalid.",
        " Entered age input (EFG) is invalid.",
        " Entered occupation input (HIJK) is invalid.",
        " Entered genre input (LMN|OP) is invalid."
    ]
}
For the Milestone 3 feature

Input (json body)

{
    "title": "Toy Story",
    "limit": -5
}

Output (json body) - Status code 400 Bad Request

{
    "error": "InputInvalidError",
    "message": [
        "Entered title input (Toy Story) is invalid.",
        " Entered limit input (-5) is invalid."
    ]
}


About JUnit Test

The JaCoCO plugin (ver : 0.8.2) is used for this JUnit Test to generate the code coverage report. The Code coverage goal for this project has been set to 0.9 (90%). The code coverage report index.html can be found in target/site/jacoco/ directory and viewed with chrome or other extensions.

Example of Report

(Below example is from Milestone 2) image

Contribution by Area

Area Contribution
Java Implementation Models and Data Structures
👑 Yeongjun Kwak
Exception Handling
👑 Sanghun Lee, Yeongjun Kwak
Unit Test Building
👑 Yujin Lee
REST service Implementation & Dependancy management 👑 Yujin Lee
Documentation README.md
👑 Yujin Lee



Milestone 4 - User Documentation

This part contains User Documentation denoted for regular end-users and is focused on endpoints for those users.

User Documentation Contents


Overview : AnOtterMovie, a robust, scalable, and user-centered movie recommendation system

image

AnOtterMovie is a Robust, Scalable, and user-centered movie recommendation engine and a user can get movie recommendation results by putting his demographic profile (gender, age, occupation, and genre preference) or movie metadata (movie title).


System architecture

image

AnOtterMovie is based on Microservice architeture, which is an architectural style that structures an application as a collection of services that are. (Microservices - Wikipedia)

The detailed system architecture is as above, and

are used respectively.


Installation

Prerequisites
  1. Download dockerfile, run.sh, and *.war file in the same directory. dockerfile, run.sh and *.war filecan be downloaded from here.

For Part 1, 2 of Milestone 4 (Spring)

  1. Build and Run dockerfile 
    $ docker build -t image_name /location/of/dockerfile
$ docker run -it -p 8080:8080 image_name bash
  2. (In the Docker Container) Run . run.sh 
    root@containerID:~/project# . run.sh

For Part 3 of Milestone 4 (Deployment, Tomcat)

  1. Build and Run dockerfile 
    $ docker build -t image_name /location/of/dockerfile
$ docker run -d -p 8080:8080 image_name


How to use

image After the installation, to use a service, either 1) URL (Website) or 2) CURL Command can be used. In this documentation, the method using URL (Website) will be explicitly guided (as this documentation is for general users).

Step 1 : Access http://localhost:8080/index.html or http://localhost:8080/cse364-project/.

Depending on the Installation steps you took above

Main page

image If you see the main page as above, you successfully finished your installation steps. You are able to toggle between User-based recommendtation and Movie-based recommendtation by using the User-based button and Movie-based button below the logo.

Main page : User-based recommendtation

image For User-based recommendation, there are shown 4 fields ; Gender, Age, Occupation, Genre. Those 4 fields are all not required to fill in.

Main page : Movie-based recommendtation

image For Movie-based recommendation, there are shown 2 fields ; Title, Limit. Title field is required to fill in, and Limit isn't (Limit will set to 10 when not specified).

Main page : Field Errors

image Then next, press the Submit button. If you typed wrong input (or didn't fill in the title for Movie-based), you will get error messages via tooltip or alert as can be seen above.

Step 2 : Press the Submit button and get the recommendation result.

On the Result pages, you are also allowed to make another request using the fields on the header.

Result : User-based recommendtation

image For User-based recommendation, you will get recommendation of 10 movies as can be seen above.

Result : Movie-based recommendtation

image For Movie-based recommendation, you will get recommendation of Limit (if not specified, 10) movies as can be seen above.

Remainder

An Awesome-Otter-Spinning-Loader

image The system might take a bit of time when there are much data to process (especially when inputs are not specified in User-based mode). When the system is under the process, you will see an awesome-otter-spinning-loader, so please take your time :)



Team Members

License & Acknowledgements