diff --git a/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java b/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java index 217a0b1dc..a38e14734 100644 --- a/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java +++ b/src/main/java/com/omertron/themoviedbapi/TheMovieDbApi.java @@ -42,6 +42,8 @@ import com.omertron.themoviedbapi.methods.TmdbPeople; import com.omertron.themoviedbapi.methods.TmdbReviews; import com.omertron.themoviedbapi.methods.TmdbSearch; import com.omertron.themoviedbapi.methods.TmdbTV; +import com.omertron.themoviedbapi.methods.TmdbEpisodes; +import com.omertron.themoviedbapi.methods.TmdbSeasons; import com.omertron.themoviedbapi.model.Certification; import com.omertron.themoviedbapi.model.FindResults; import com.omertron.themoviedbapi.model.Genre; @@ -80,7 +82,9 @@ import com.omertron.themoviedbapi.model.person.PersonCredits; import com.omertron.themoviedbapi.model.person.PersonFind; import com.omertron.themoviedbapi.model.review.Review; import com.omertron.themoviedbapi.model.tv.TVBasic; +import com.omertron.themoviedbapi.model.tv.TVEpisodeInfo; import com.omertron.themoviedbapi.model.tv.TVInfo; +import com.omertron.themoviedbapi.model.tv.TVSeasonInfo; import com.omertron.themoviedbapi.results.ResultList; import com.omertron.themoviedbapi.results.ResultsMap; import com.omertron.themoviedbapi.tools.HttpTools; @@ -93,8 +97,7 @@ import org.yamj.api.common.http.SimpleHttpClientBuilder; /** * The MovieInfo 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 */ @@ -121,6 +124,8 @@ public class TheMovieDbApi { private static TmdbReviews tmdbReviews; private static TmdbSearch tmdbSearch; private static TmdbTV tmdbTv; + private static TmdbSeasons tmdbSeasons; + private static TmdbEpisodes tmdbEpisodes; /** * API for The Movie Db. @@ -170,12 +175,13 @@ public class TheMovieDbApi { tmdbReviews = new TmdbReviews(apiKey, httpTools); tmdbSearch = new TmdbSearch(apiKey, httpTools); tmdbTv = new TmdbTV(apiKey, httpTools); + tmdbSeasons = new TmdbSeasons(apiKey, httpTools); + tmdbEpisodes = new TmdbEpisodes(apiKey, httpTools); } // /** - * 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 @@ -341,16 +347,13 @@ 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 @@ -360,8 +363,7 @@ 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. * @@ -374,8 +376,7 @@ public class TheMovieDbApi { } /** - * This method is used to generate a session id for user based - * authentication. User must provide their username and password + * This method is used to generate a session id for user based authentication. User must provide their username and password * * A session id is required in order to use any of the write methods. * @@ -392,18 +393,14 @@ 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 @@ -439,8 +436,7 @@ public class TheMovieDbApi { /** * Get a list of Movie IDs that have been edited. * - * You can then use the movie changes API to get the actual data that has - * been changed. + * You can then use the movie changes API to get the actual data that has been changed. * * @param page * @param startDate the start date of the changes, optional @@ -455,8 +451,7 @@ public class TheMovieDbApi { /** * Get a list of TV IDs that have been edited. * - * You can then use the TV changes API to get the actual data that has been - * changed. + * You can then use the TV changes API to get the actual data that has been changed. * * @param page * @param startDate the start date of the changes, optional @@ -471,8 +466,7 @@ public class TheMovieDbApi { /** * Get a list of Person IDs that have been edited. * - * You can then use the person changes API to get the actual data that has - * been changed. + * You can then use the person changes API to get the actual data that has been changed. * * @param page * @param startDate the start date of the changes, optional @@ -487,11 +481,9 @@ 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 @@ -517,8 +509,7 @@ 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 @@ -531,8 +522,7 @@ 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. * * @param companyId * @param language @@ -579,8 +569,7 @@ public class TheMovieDbApi { } /** - * Get the list of supported timezones for the API methods that support - * them. + * Get the list of supported timezones for the API methods that support them. * * @return @throws MovieDbException */ @@ -595,14 +584,11 @@ public class TheMovieDbApi { *

* This is currently only supported with the new credit model found in TV. *
- * These IDs can be found from any TV credit response as well as the - * TV_credits and combined_credits methods for people.
- * The episodes object returns a list of episodes and are generally going to - * be guest stars.
+ * These IDs can be found from any TV credit response as well as the TV_credits and combined_credits methods for people.
+ * The episodes object returns a list of episodes and are generally going to be guest stars.
* The season array will return a list of season numbers.
- * Season credits are credits that were marked with the "add to every - * season" option in the editing interface and are assumed to be "season - * regulars". + * Season credits are credits that were marked with the "add to every season" option in the editing interface and are assumed to + * be "season regulars". * * @param creditId * @param language @@ -616,8 +602,7 @@ 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 @@ -628,8 +613,7 @@ 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 @@ -642,18 +626,16 @@ public class TheMovieDbApi { // /** - * You con use this method to find movies, tv series or persons using - * external ids. + * You con use this method to find movies, tv series or persons using external ids. * * Supported query ids are *

* * For details see http://docs.themoviedb.apiary.io/#find @@ -695,11 +677,9 @@ 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 @@ -766,8 +746,7 @@ 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 @@ -827,8 +806,7 @@ public class TheMovieDbApi { * * It will return the single highest rated poster and backdrop. * - * ApiExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no movies - * found. + * ApiExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no movies found. * * @param movieId * @param language @@ -845,8 +823,7 @@ public class TheMovieDbApi { * * It will return the single highest rated poster and backdrop. * - * ApiExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no movies - * found. + * ApiExceptionType.MOVIE_ID_NOT_FOUND will be thrown if there are no movies found. * * @param imdbId * @param language @@ -859,8 +836,8 @@ public class TheMovieDbApi { } /** - * This method lets a user get the status of whether or not the movie has - * been rated or added to their favourite or movie watch list. + * This method lets a user get the status of whether or not the movie has been rated or added to their favourite or movie watch + * list. * * A valid session id is required. * @@ -874,8 +851,7 @@ 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 @@ -900,8 +876,7 @@ 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 @@ -914,8 +889,7 @@ 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. * @@ -929,8 +903,7 @@ 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 @@ -943,8 +916,7 @@ 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. * @@ -959,8 +931,7 @@ 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 @@ -972,11 +943,9 @@ 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 * @@ -1026,8 +995,7 @@ 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. * @@ -1086,8 +1054,7 @@ 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. * * @param language * @param page @@ -1113,8 +1080,7 @@ 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. * @@ -1172,11 +1138,9 @@ public class TheMovieDbApi { /** * Get the TV credits for a specific person id. * - * To get the expanded details for each record, call the /credit method with - * the provided credit_id. + * To get the expanded details for each record, call the /credit method with the provided credit_id. * - * This will provide details about which episode and/or season the credit is - * for. + * This will provide details about which episode and/or season the credit is for. * * @param personId * @param language @@ -1191,11 +1155,9 @@ public class TheMovieDbApi { /** * Get the combined (movie and TV) credits for a specific person id. * - * To get the expanded details for each TV record, call the /credit method - * with the provided credit_id. + * To get the expanded details for each TV record, call the /credit method with the provided credit_id. * - * This will provide details about which episode and/or season the credit is - * for. + * This will provide details about which episode and/or season the credit is for. * * @param personId * @param language @@ -1232,8 +1194,7 @@ public class TheMovieDbApi { /** * Get the images that have been tagged with a specific person id. * - * We return all of the image results with a media object mapped for each - * image. + * We return all of the image results with a media object mapped for each image. * * @param personId * @param page @@ -1252,8 +1213,7 @@ 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. * @@ -1306,8 +1266,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 * @@ -1359,16 +1319,13 @@ 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 query - * @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) * @param primaryReleaseYear * @param searchType * @return @@ -1387,11 +1344,9 @@ public class TheMovieDbApi { /** * Search the movie, tv show and person collections with a single query. * - * Each item returned in the result array has a media_type field that maps - * to either movie, tv or person. + * Each item returned in the result array has a media_type field that maps to either movie, tv or person. * - * Each mapped result is the same response you would get from each - * independent search + * Each mapped result is the same response you would get from each independent search * * @param query * @param page @@ -1407,8 +1362,7 @@ 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 query * @param includeAdult @@ -1452,8 +1406,8 @@ public class TheMovieDbApi { } /** - * This method lets users get the status of whether or not the TV show has - * been rated or added to their favourite or watch lists. + * This method lets users get the status of whether or not the TV show has been rated or added to their favourite or watch + * lists. * * A valid session id is required. * @@ -1582,8 +1536,7 @@ public class TheMovieDbApi { } /** - * Get the list of translations that exist for a TV series. These - * translations cascade down to the episode level. + * Get the list of translations that exist for a TV series. These translations cascade down to the episode level. * * @param tvID * @return @@ -1594,8 +1547,7 @@ public class TheMovieDbApi { } /** - * Get the videos that have been added to a TV series (trailers, opening - * credits, etc...) + * Get the videos that have been added to a TV series (trailers, opening credits, etc...) * * @param tvID * @param language @@ -1619,8 +1571,7 @@ public class TheMovieDbApi { /** * Get the list of TV shows that are currently on the air. * - * This query looks for any TV show that has an episode with an air date in - * the next 7 days. + * This query looks for any TV show that has an episode with an air date in the next 7 days. * * @param page * @param language @@ -1649,8 +1600,7 @@ public class TheMovieDbApi { /** * Get the list of top rated TV shows. * - * By default, this list will only include TV shows that have 2 or more - * votes. + * By default, this list will only include TV shows that have 2 or more votes. * * This list refreshes every day. * @@ -1677,8 +1627,213 @@ public class TheMovieDbApi { // // + /** + * Get the primary information about a TV season by its season number. + * + * @param tvID + * @param seasonNumber + * @param language + * @param appendToResponse + * @return + * @throws MovieDbException + */ + public TVSeasonInfo getSeasonInfo(int tvID, int seasonNumber, String language, String... appendToResponse) throws MovieDbException { + return tmdbSeasons.getSeasonInfo(tvID, seasonNumber, language, appendToResponse); + } + + /** + * Look up a TV season's changes by season ID. + * + * @param tvID + * @param startDate + * @param endDate + * @return + * @throws MovieDbException + */ + public ResultList getSeasonChanges(int tvID, String startDate, String endDate) throws MovieDbException { + return tmdbSeasons.getSeasonChanges(tvID, startDate, endDate); + } + + /** + * This method lets users get the status of whether or not the TV episodes of a season have been rated. + * + * A valid session id is required. + * + * @param tvID + * @param sessionID + * @return + * @throws MovieDbException + */ + public MediaState getSeasonAccountState(int tvID, String sessionID) throws MovieDbException { + return tmdbSeasons.getSeasonAccountState(tvID, sessionID); + } + + /** + * Get the cast & crew credits for a TV season by season number. + * + * @param tvID + * @param seasonNumber + * @return + * @throws MovieDbException + */ + public MediaCreditList getSeasonCredits(int tvID, int seasonNumber) throws MovieDbException { + return tmdbSeasons.getSeasonCredits(tvID, seasonNumber); + } + + /** + * Get the external ids that we have stored for a TV season by season number. + * + * @param tvID + * @param seasonNumber + * @param language + * @return + * @throws MovieDbException + */ + public ExternalID getSeasonExternalID(int tvID, int seasonNumber, String language) throws MovieDbException { + return tmdbSeasons.getSeasonExternalID(tvID, seasonNumber, language); + } + + /** + * Get the images that we have stored for a TV season by season number. + * + * @param tvID + * @param seasonNumber + * @param language + * @param includeImageLanguage + * @return + * @throws MovieDbException + */ + public ResultList getSeasonImages(int tvID, int seasonNumber, String language, String... includeImageLanguage) throws MovieDbException { + return tmdbSeasons.getSeasonImages(tvID, seasonNumber, language, includeImageLanguage); + } + + /** + * Get the videos that have been added to a TV season (trailers, teasers, etc...) + * + * @param tvID + * @param seasonNumber + * @param language + * @return + * @throws MovieDbException + */ + public ResultList // - // + /** + * Get the primary information about a TV episode by combination of a season and episode number. + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @param language + * @param appendToResponse + * @return + * @throws MovieDbException + */ + public TVEpisodeInfo getEpisodeInfo(int tvID, int seasonNumber, int episodeNumber, String language, String... appendToResponse) throws MovieDbException { + return tmdbEpisodes.getEpisodeInfo(tvID, seasonNumber, episodeNumber, language, appendToResponse); + } + + /** + * Look up a TV episode's changes by episode ID + * + * @param episodeID + * @param startDate + * @param endDate + * @return + * @throws MovieDbException + */ + public ResultList getEpisodeChanges(int episodeID, String startDate, String endDate) throws MovieDbException { + return tmdbEpisodes.getEpisodeChanges(episodeID, startDate, endDate); + } + + /** + * This method lets users get the status of whether or not the TV episode has been rated. + * + * A valid session id is required. + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @param sessionID + * @return + * @throws MovieDbException + */ + public MediaState getEpisodeAccountState(int tvID, int seasonNumber, int episodeNumber, String sessionID) throws MovieDbException { + return tmdbEpisodes.getEpisodeAccountState(tvID, seasonNumber, episodeNumber, sessionID); + } + + /** + * Get the TV episode credits by combination of season and episode number. + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @return + * @throws MovieDbException + */ + public MediaCreditList getEpisodeCredits(int tvID, int seasonNumber, int episodeNumber) throws MovieDbException { + return tmdbEpisodes.getEpisodeCredits(tvID, seasonNumber, episodeNumber); + } + + /** + * Get the external ids for a TV episode by comabination of a season and episode number. + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @param language + * @return + * @throws MovieDbException + */ + public ExternalID getEpisodeExternalID(int tvID, int seasonNumber, int episodeNumber, String language) throws MovieDbException { + return tmdbEpisodes.getEpisodeExternalID(tvID, seasonNumber, episodeNumber, language); + } + + /** + * Get the images (episode stills) for a TV episode by combination of a season and episode number. + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @return + * @throws MovieDbException + */ + public ResultList getEpisodeImages(int tvID, int seasonNumber, int episodeNumber) throws MovieDbException { + return tmdbEpisodes.getEpisodeImages(tvID, seasonNumber, episodeNumber); + } + + /** + * This method lets users rate a TV episode. A valid session id or guest session id is required. + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @param rating + * @param sessionID + * @param guestSessionID + * @return + * @throws MovieDbException + */ + public StatusCode postEpisodeRating(int tvID, int seasonNumber, int episodeNumber, int rating, String sessionID, String guestSessionID) throws MovieDbException { + return tmdbEpisodes.postEpisodeRating(tvID, seasonNumber, episodeNumber, rating, sessionID, guestSessionID); + } + + /** + * Get the videos that have been added to a TV episode (teasers, clips, etc...) + * + * @param tvID + * @param seasonNumber + * @param episodeNumber + * @param language + * @return + * @throws MovieDbException + */ + public ResultList