diff --git a/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java b/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java index 7888ff760..ec62ff514 100644 --- a/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java +++ b/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java @@ -109,7 +109,8 @@ import org.yamj.api.common.http.CommonHttpClient; /** * The MovieDb API *

- * This is for version 3 of the API as specified here: http://help.themoviedb.org/kb/api/about-3 + * This is for version 3 of the API as specified here: + * http://help.themoviedb.org/kb/api/about-3 * * @author stuart.boston */ @@ -132,8 +133,12 @@ public class TheMovieDbApi { private static final String BASE_KEYWORD = "keyword/"; private static final String BASE_JOB = "job/"; private static final String BASE_DISCOVER = "discover/"; + private static final String URL_MOVIES = "/movies"; + private static final String URL_IMAGES = "/images"; // Jackson JSON configuration private static ObjectMapper mapper = new ObjectMapper(); + // Constants + private static final String MOVIE_ID = "movie_id"; /** * API for The Movie Db. @@ -203,7 +208,7 @@ public class TheMovieDbApi { if (isDeleteRequest) { //TODO: Handle delete request - throw new MovieDbException(MovieDbExceptionType.UNKNOWN_CAUSE, "Unable to proces delete request",url); + throw new MovieDbException(MovieDbExceptionType.UNKNOWN_CAUSE, "Unable to proces delete request", url); } webpage = httpClient.requestContent(httpGet); @@ -272,7 +277,8 @@ public class TheMovieDbApi { * @param moviedb The moviedb object to compare too * @param title The title of the movie to compare * @param year The year of the movie to compare - * @param maxDistance The Levenshtein Distance between the two titles. 0 = exact match + * @param maxDistance The Levenshtein Distance between the two titles. 0 = + * exact match * @param caseSensitive true if the comparison is to be case sensitive * @return True if there is a match, False otherwise. */ @@ -388,13 +394,16 @@ public class TheMovieDbApi { // /** - * This method is used to generate a valid request token for user based authentication. + * This method is used to generate a valid request token for user based + * authentication. * * A request token is required in order to request a session id. * - * You can generate any number of request tokens but they will expire after 60 minutes. + * You can generate any number of request tokens but they will expire after + * 60 minutes. * - * As soon as a valid session id has been created the token will be destroyed. + * As soon as a valid session id has been created the token will be + * destroyed. * * @return * @throws MovieDbException @@ -414,7 +423,8 @@ public class TheMovieDbApi { } /** - * This method is used to generate a session id for user based authentication. + * This method is used to generate a session id for user based + * authentication. * * A session id is required in order to use any of the write methods. * @@ -445,14 +455,18 @@ public class TheMovieDbApi { /** * This method is used to generate a guest session id. * - * A guest session can be used to rate movies without having a registered TMDb user account. + * A guest session can be used to rate movies without having a registered + * TMDb user account. * - * You should only generate a single guest session per user (or device) as you will be able to attach the ratings to a TMDb user - * account in the future. + * You should only generate a single guest session per user (or device) as + * you will be able to attach the ratings to a TMDb user account in the + * future. * - * There are also IP limits in place so you should always make sure it's the end user doing the guest session actions. + * There are also IP limits in place so you should always make sure it's the + * end user doing the guest session actions. * - * If a guest session is not used for the first time within 24 hours, it will be automatically discarded. + * If a guest session is not used for the first time within 24 hours, it + * will be automatically discarded. * * @return * @throws MovieDbException @@ -472,7 +486,8 @@ public class TheMovieDbApi { } /** - * Get the basic information for an account. You will need to have a valid session id. + * Get the basic information for an account. You will need to have a valid + * session id. * * @param sessionId * @return @@ -515,7 +530,7 @@ public class TheMovieDbApi { apiUrl.addArgument(PARAM_SESSION, sessionId); Map body = new HashMap(); - body.put("movie_id", movieId); + body.put(MOVIE_ID, movieId); body.put("favorite", isFavorite); String jsonBody = convertToJson(body); @@ -562,7 +577,7 @@ public class TheMovieDbApi { apiUrl.addArgument(PARAM_SESSION, sessionId); Map body = new HashMap(); - body.put("movie_id", movieId); + body.put(MOVIE_ID, movieId); body.put("movie_watchlist", add); String jsonBody = convertToJson(body); @@ -584,7 +599,8 @@ public class TheMovieDbApi { * * It will return the single highest rated poster and backdrop. * - * MovieDbExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no movies found. + * MovieDbExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no + * movies found. * * @param movieId * @param language @@ -623,7 +639,8 @@ public class TheMovieDbApi { * * It will return the single highest rated poster and backdrop. * - * MovieDbExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no movies found. + * MovieDbExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no + * movies found. * * @param imdbId * @param language @@ -658,7 +675,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve all of the alternative titles we have for a particular movie. + * This method is used to retrieve all of the alternative titles we have for + * a particular movie. * * @param movieId * @param country @@ -720,7 +738,8 @@ public class TheMovieDbApi { } /** - * This method should be used when you’re wanting to retrieve all of the images for a particular movie. + * This method should be used when you’re wanting to retrieve all of the + * images for a particular movie. * * @param movieId * @param language @@ -729,7 +748,7 @@ public class TheMovieDbApi { * @throws MovieDbException */ public TmdbResultsList getMovieImages(int movieId, String language, String... appendToResponse) throws MovieDbException { - ApiUrl apiUrl = new ApiUrl(apiKey, BASE_MOVIE, "/images"); + ApiUrl apiUrl = new ApiUrl(apiKey, BASE_MOVIE, URL_IMAGES); apiUrl.addArgument(PARAM_ID, movieId); if (StringUtils.isNotBlank(language)) { @@ -753,7 +772,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve all of the keywords that have been added to a particular movie. + * This method is used to retrieve all of the keywords that have been added + * to a particular movie. * * Currently, only English keywords exist. * @@ -783,7 +803,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve all of the release and certification data we have for a specific movie. + * This method is used to retrieve all of the release and certification data + * we have for a specific movie. * * @param movieId * @param language @@ -813,7 +834,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve all of the trailers for a particular movie. + * This method is used to retrieve all of the trailers for a particular + * movie. * * Supported sites are YouTube and QuickTime. * @@ -848,7 +870,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve a list of the available translations for a specific movie. + * This method is used to retrieve a list of the available translations for + * a specific movie. * * @param movieId * @param appendToResponse @@ -876,9 +899,11 @@ public class TheMovieDbApi { } /** - * The similar movies method will let you retrieve the similar movies for a particular movie. + * The similar movies method will let you retrieve the similar movies for a + * particular movie. * - * This data is created dynamically but with the help of users votes on TMDb. + * This data is created dynamically but with the help of users votes on + * TMDb. * * The data is much better with movies that have more keywords * @@ -990,11 +1015,13 @@ public class TheMovieDbApi { * * By default, only the last 24 hours of changes are returned. * - * The maximum number of days that can be returned in a single request is 14. + * The maximum number of days that can be returned in a single request is + * 14. * * The language is present on fields that are translatable. * - * TODO: DOES NOT WORK AT THE MOMENT. This is due to the "value" item changing type in the ChangeItem + * TODO: DOES NOT WORK AT THE MOMENT. This is due to the "value" item + * changing type in the ChangeItem * * @param movieId * @param startDate the start date of the changes, optional @@ -1092,7 +1119,8 @@ public class TheMovieDbApi { /** * This method is used to retrieve the movies currently in theatres. * - * This is a curated list that will normally contain 100 movies. The default response will return 20 movies. + * This is a curated list that will normally contain 100 movies. The default + * response will return 20 movies. * * TODO: Implement more than 20 movies * @@ -1164,7 +1192,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve the top rated movies that have over 10 votes on TMDb. + * This method is used to retrieve the top rated movies that have over 10 + * votes on TMDb. * * The default response will return 20 movies. * @@ -1262,9 +1291,11 @@ public class TheMovieDbApi { // /** - * This method is used to retrieve all of the basic information about a movie collection. + * This method is used to retrieve all of the basic information about a + * movie collection. * - * You can get the ID needed for this method by making a getMovieInfo request for the belongs_to_collection. + * You can get the ID needed for this method by making a getMovieInfo + * request for the belongs_to_collection. * * @param collectionId * @param language @@ -1299,7 +1330,7 @@ public class TheMovieDbApi { * @throws MovieDbException */ public TmdbResultsList getCollectionImages(int collectionId, String language) throws MovieDbException { - ApiUrl apiUrl = new ApiUrl(apiKey, BASE_COLLECTION, "/images"); + ApiUrl apiUrl = new ApiUrl(apiKey, BASE_COLLECTION, URL_IMAGES); apiUrl.addArgument(PARAM_ID, collectionId); if (StringUtils.isNotBlank(language)) { @@ -1350,7 +1381,8 @@ public class TheMovieDbApi { } /** - * This method is used to retrieve all of the cast & crew information for the person. + * This method is used to retrieve all of the cast & crew information for + * the person. * * It will return the single highest rated poster for each movie record. * @@ -1387,7 +1419,7 @@ public class TheMovieDbApi { * @throws MovieDbException */ public TmdbResultsList getPersonImages(int personId) throws MovieDbException { - ApiUrl apiUrl = new ApiUrl(apiKey, BASE_PERSON, "/images"); + ApiUrl apiUrl = new ApiUrl(apiKey, BASE_PERSON, URL_IMAGES); apiUrl.addArgument(PARAM_ID, personId); @@ -1412,7 +1444,8 @@ public class TheMovieDbApi { * * By default, only the last 24 hours of changes are returned. * - * The maximum number of days that can be returned in a single request is 14. + * The maximum number of days that can be returned in a single request is + * 14. * * The language is present on fields that are translatable. * @@ -1489,7 +1522,8 @@ public class TheMovieDbApi { // /** - * This method is used to retrieve the basic information about a production company on TMDb. + * This method is used to retrieve the basic information about a production + * company on TMDb. * * @param companyId * @return @@ -1514,7 +1548,8 @@ public class TheMovieDbApi { /** * This method is used to retrieve the movies associated with a company. * - * These movies are returned in order of most recently released to oldest. The default response will return 20 movies per page. + * These movies are returned in order of most recently released to oldest. + * The default response will return 20 movies per page. * * TODO: Implement more than 20 movies * @@ -1525,7 +1560,7 @@ public class TheMovieDbApi { * @throws MovieDbException */ public TmdbResultsList getCompanyMovies(int companyId, String language, int page) throws MovieDbException { - ApiUrl apiUrl = new ApiUrl(apiKey, BASE_COMPANY, "/movies"); + ApiUrl apiUrl = new ApiUrl(apiKey, BASE_COMPANY, URL_MOVIES); apiUrl.addArgument(PARAM_ID, companyId); @@ -1583,9 +1618,11 @@ public class TheMovieDbApi { /** * Get a list of movies per genre. * - * It is important to understand that only movies with more than 10 votes get listed. + * It is important to understand that only movies with more than 10 votes + * get listed. * - * This prevents movies from 1 10/10 rating from being listed first and for the first 5 pages. + * This prevents movies from 1 10/10 rating from being listed first and for + * the first 5 pages. * * @param genreId * @param language @@ -1595,7 +1632,7 @@ public class TheMovieDbApi { * @throws MovieDbException */ public TmdbResultsList getGenreMovies(int genreId, String language, int page, boolean includeAllMovies) throws MovieDbException { - ApiUrl apiUrl = new ApiUrl(apiKey, BASE_GENRE, "/movies"); + ApiUrl apiUrl = new ApiUrl(apiKey, BASE_GENRE, URL_MOVIES); apiUrl.addArgument(PARAM_ID, genreId); if (StringUtils.isNotBlank(language)) { @@ -1625,13 +1662,16 @@ public class TheMovieDbApi { // /** - * Search Movies This is a good starting point to start finding movies on TMDb. + * Search Movies This is a good starting point to start finding movies on + * TMDb. * * @param movieName - * @param searchYear Limit the search to the provided year. Zero (0) will get all years + * @param searchYear Limit the search to the provided year. Zero (0) will + * get all years * @param language The language to include. Can be blank/null. * @param includeAdult true or false to include adult titles in the search - * @param page The page of results to return. 0 to get the default (first page) + * @param page The page of results to return. 0 to get the default (first + * page) * @return * @throws MovieDbException */ @@ -1711,7 +1751,8 @@ public class TheMovieDbApi { /** * This is a good starting point to start finding people on TMDb. * - * The idea is to be a quick and light method so you can iterate through people quickly. + * The idea is to be a quick and light method so you can iterate through + * people quickly. * * @param personName * @param includeAdult @@ -1783,8 +1824,8 @@ public class TheMovieDbApi { /** * Search Companies. * - * You can use this method to search for production companies that are part of TMDb. The company IDs will map to those returned - * on movie calls. + * You can use this method to search for production companies that are part + * of TMDb. The company IDs will map to those returned on movie calls. * * http://help.themoviedb.org/kb/api/search-companies * @@ -1934,7 +1975,7 @@ public class TheMovieDbApi { */ public boolean isMovieOnList(String listId, Integer movieId) throws MovieDbException { ApiUrl apiUrl = new ApiUrl(apiKey, BASE_LIST, listId + "/item_status"); - apiUrl.addArgument("movie_id", movieId); + apiUrl.addArgument(MOVIE_ID, movieId); URL url = apiUrl.buildUrl(); String webpage = requestWebPage(url); @@ -1948,7 +1989,8 @@ public class TheMovieDbApi { } /** - * This method lets users add new movies to a list that they created. A valid session id is required. + * This method lets users add new movies to a list that they created. A + * valid session id is required. * * @param sessionId * @param listId @@ -1961,7 +2003,8 @@ public class TheMovieDbApi { } /** - * This method lets users remove movies from a list that they created. A valid session id is required. + * This method lets users remove movies from a list that they created. A + * valid session id is required. * * @param sessionId * @param listId @@ -2015,7 +2058,8 @@ public class TheMovieDbApi { } /** - * This method lets users delete a list that they created. A valid session id is required. + * This method lets users delete a list that they created. A valid session + * id is required. * * @param sessionId * @param listId @@ -2073,7 +2117,7 @@ public class TheMovieDbApi { * @throws MovieDbException */ public TmdbResultsList getKeywordMovies(String keywordId, String language, int page) throws MovieDbException { - ApiUrl apiUrl = new ApiUrl(apiKey, BASE_KEYWORD, "/movies"); + ApiUrl apiUrl = new ApiUrl(apiKey, BASE_KEYWORD, URL_MOVIES); apiUrl.addArgument(PARAM_ID, keywordId); if (StringUtils.isNotBlank(language)) { @@ -2102,10 +2146,12 @@ public class TheMovieDbApi { // /** - * Get a list of movie ids that have been edited. By default we show the last 24 hours and only 100 items per page. The maximum - * number of days that can be returned in a single request is 14. You can then use the movie changes API to get the actual data - * that has been changed. Please note that the change log system to support this was changed on October 5, 2012 and will only - * show movies that have been edited since. + * Get a list of movie ids that have been edited. By default we show the + * last 24 hours and only 100 items per page. The maximum number of days + * that can be returned in a single request is 14. You can then use the + * movie changes API to get the actual data that has been changed. Please + * note that the change log system to support this was changed on October 5, + * 2012 and will only show movies that have been edited since. * * @param page * @param startDate the start date of the changes, optional @@ -2168,30 +2214,42 @@ public class TheMovieDbApi { // /** - * Discover movies by different types of data like average rating, number of votes, genres and certifications. + * Discover movies by different types of data like average rating, number of + * votes, genres and certifications. * - * You can alternatively create a "discover" object and pass it to this method to cut out the requirement for all of these - * parameters + * You can alternatively create a "discover" object and pass it to this + * method to cut out the requirement for all of these parameters * * @param page Minimum value is 1 * @param language ISO 639-1 code. - * @param sortBy Available options are vote_average.desc, vote_average.asc, release_date.desc, release_date.asc, - * popularity.desc, popularity.asc + * @param sortBy Available options are vote_average.desc, vote_average.asc, + * release_date.desc, release_date.asc, popularity.desc, popularity.asc * @param includeAdult Toggle the inclusion of adult titles - * @param year Filter the results release dates to matches that include this value - * @param primaryReleaseYear Filter the results so that only the primary release date year has this value - * @param voteCountGte Only include movies that are equal to, or have a vote count higher than this value - * @param voteAverageGte Only include movies that are equal to, or have a higher average rating than this value - * @param withGenres Only include movies with the specified genres. Expected value is an integer (the id of a genre). Multiple - * values can be specified. Comma separated indicates an 'AND' query, while a pipe (|) separated value indicates an 'OR'. - * @param releaseDateGte The minimum release to include. Expected format is YYYY-MM-DD - * @param releaseDateLte The maximum release to include. Expected format is YYYY-MM-DD - * @param certificationCountry Only include movies with certifications for a specific country. When this value is specified, - * 'certificationLte' is required. A ISO 3166-1 is expected. - * @param certificationLte Only include movies with this certification and lower. Expected value is a valid certification for - * the specified 'certificationCountry'. - * @param withCompanies Filter movies to include a specific company. Expected value is an integer (the id of a company). They - * can be comma separated to indicate an 'AND' query. + * @param year Filter the results release dates to matches that include this + * value + * @param primaryReleaseYear Filter the results so that only the primary + * release date year has this value + * @param voteCountGte Only include movies that are equal to, or have a vote + * count higher than this value + * @param voteAverageGte Only include movies that are equal to, or have a + * higher average rating than this value + * @param withGenres Only include movies with the specified genres. Expected + * value is an integer (the id of a genre). Multiple values can be + * specified. Comma separated indicates an 'AND' query, while a pipe (|) + * separated value indicates an 'OR'. + * @param releaseDateGte The minimum release to include. Expected format is + * YYYY-MM-DD + * @param releaseDateLte The maximum release to include. Expected format is + * YYYY-MM-DD + * @param certificationCountry Only include movies with certifications for a + * specific country. When this value is specified, 'certificationLte' is + * required. A ISO 3166-1 is expected. + * @param certificationLte Only include movies with this certification and + * lower. Expected value is a valid certification for the specified + * 'certificationCountry'. + * @param withCompanies Filter movies to include a specific company. + * Expected value is an integer (the id of a company). They can be comma + * separated to indicate an 'AND' query. * @return * @throws MovieDbException */ @@ -2219,7 +2277,8 @@ public class TheMovieDbApi { } /** - * Discover movies by different types of data like average rating, number of votes, genres and certifications. + * Discover movies by different types of data like average rating, number of + * votes, genres and certifications. * * @param discover A discover object containing the search criteria required * @return