Package com.github.m0nk3y2k4.thetvdb.internal.api.impl

Class TheTVDBApiImpl

java.lang.Object

com.github.m0nk3y2k4.thetvdb.internal.api.impl.TheTVDBApiImpl

All Implemented Interfaces:

TheTVDBApi

public class TheTVDBApiImpl
extends Object
implements TheTVDBApi

Implementation of the TheTVDBApi API layout. It provides methods for all sorts of API calls throughout the different API routes. Responses will be returned as mapped Java DTO objects.

Nested Class Summary

Nested classes/interfaces inherited from interface com.github.m0nk3y2k4.thetvdb.api.TheTVDBApi

TheTVDBApi.Extended, TheTVDBApi.JSON, TheTVDBApi.Version

Constructor Summary

Constructors

Constructor	Description
TheTVDBApiImpl(String apiKey)	Creates a new TheTVDBApi instance.
TheTVDBApiImpl(String apiKey, Proxy proxy)	Creates a new TheTVDBApi instance.
TheTVDBApiImpl(String apiKey, String userKey, String userName)	Creates a new TheTVDBApi instance.
TheTVDBApiImpl(String apiKey, String userKey, String userName, Proxy proxy)	Creates a new TheTVDBApi instance.

Method Summary

Modifier and Type	Method	Description
List<String>	addToFavorites(long seriesId)	Adds the supplied series ID to the user’s favorite’s list and returns the updated list as plain Strings.
List<Rating>	addToRatings(String itemType, long itemId, long itemRating)	Updates a given rating of a given type and returns the modified rating, mapped as Java DTO.
List<String>	deleteFromFavorites(long seriesId)	Deletes the given series ID from the user’s favorite’s list and returns the updated list as plain Strings.
void	deleteFromRatings(String itemType, long itemId)	Deletes a given rating of a given type.
TheTVDBApi.Extended	extended()	Provides access to the API's Extended layout.
Series	filterSeries(long seriesId, QueryParameters queryParameters)	Returns a filtered series record based on the given parameters, mapped as Java DTO.
Series	filterSeries(long seriesId, String filterKeys)	Returns a series records, filtered by the supplied comma-separated list of keys, mapped as Java DTO.
List<Actor>	getActors(long seriesId)	Returns a list of actors for a specific series mapped as Java DTO.
List<String>	getAvailableEpisodeQueryParameters(long seriesId)	Returns a list of keys which are valid parameters for querying episodes, as plain Strings.
List<ImageQueryParameter>	getAvailableImageQueryParameters(long seriesId)	Returns a list of valid parameters for querying a series images, mapped as Java DTO.
List<Language>	getAvailableLanguages()	Returns a list of all supported languages mapped as Java DTO.
List<String>	getAvailableLastUpdatedQueryParameters()	Returns a list of valid parameters for querying series which have been updated lately, as plain Strings.
List<String>	getAvailableRatingsQueryParameters()	Returns a list of valid parameters for querying user ratings, as plain Strings.
List<String>	getAvailableSeriesFilterParameters(long seriesId)	Returns a list of keys which are valid parameters for filtering series, as plain Strings.
List<String>	getAvailableSeriesSearchParameters()	Returns possible query parameters, which can be used to search for series, mapped as Java DTO.
Episode	getEpisode(long episodeId)	Returns the full information for a given episode id as mapped Java DTO.
List<Episode>	getEpisodes(long seriesId)	Returns the first 100 episodes of a specific series mapped as Java DTO.
List<Episode>	getEpisodes(long seriesId, long page)	Returns a list of episodes of a specific series mapped as Java DTO.
List<Episode>	getEpisodes(long seriesId, QueryParameters queryParameters)	Returns all episodes of a specific series mapped as Java DTO.
List<String>	getFavorites()	Returns a list of favorite series for a given user, as plain Strings.
Language	getLanguage(long languageId)	Returns further language information for a given language ID mapped as Java DTO.
Movie	getMovie(long movieId)	Returns detailed information for a specific movie mapped as Java DTO.
List<Long>	getMovieUpdates(long since)	Returns a list of ID's of all movies that have been updated since the given epoch timestamp.
List<Rating>	getRatings()	Returns a list of ratings for the given user, mapped as Java DTO.
Series	getSeries(long seriesId)	Returns detailed information for a specific series mapped as Java DTO.
SeriesSummary	getSeriesEpisodesSummary(long seriesId)	Returns a summary of the episodes and seasons available for a series, mapped as Java DTO.
Map<String,String>	getSeriesHeaderInformation(long seriesId)	Returns header information for a specific series as key/value pairs.
ImageSummary	getSeriesImagesSummary(long seriesId)	Returns a summary of the images types and counts available for a particular series, mapped as Java DTO.
Optional<String>	getToken()	Returns the JSON Web Token used for authentication of all requests that are sent to the remote service by this API instance.
User	getUser()	Returns basic information about the currently authenticated user, mapped as Java DTO.
void	init()	Initializes the current API session by requesting a new token from the remote API.
void	init(String token)	Initializes the current API with the given token.
TheTVDBApi.JSON	json()	Provides access to the API's JSON layout.
void	login()	Initializes the current API session by requesting a new token from the remote API.
List<Episode>	queryEpisodes(long seriesId, QueryParameters queryParameters)	Returns all matching episodes of a specific series mapped as Java DTO.
List<Episode>	queryEpisodesByAbsoluteNumber(long seriesId, long absoluteNumber)	Returns a specific episode of a series, mapped as Java DTO.
List<Episode>	queryEpisodesByAiredEpisode(long seriesId, long airedEpisode)	Returns all episodes of a specific series, matching the airedEpisode parameter, mapped as Java DTO.
List<Episode>	queryEpisodesByAiredSeason(long seriesId, long airedSeason)	Returns all episodes of a specific series and season mapped as Java DTO.
List<Episode>	queryEpisodesByAiredSeason(long seriesId, long airedSeason, long page)	Returns all episodes of a specific series and season mapped as Java DTO.
List<Image>	queryImages(long seriesId, QueryParameters queryParameters)	Returns the matching result of querying images for a specific series, mapped as Java DTO.
List<Image>	queryImages(long seriesId, String keyType, String resolution)	Returns all images for a specific series, matching the given parameters, mapped as Java DTO.
List<Image>	queryImages(long seriesId, String keyType, String resolution, String subKey)	Returns all images for a specific series, matching the given parameters, mapped as Java DTO.
List<Image>	queryImagesByKeyType(long seriesId, String keyType)	Returns all images of a specific type for a series, mapped as Java DTO.
List<Image>	queryImagesByResolution(long seriesId, String resolution)	Returns all images of a specific resolution for a series, mapped as Java DTO.
List<Image>	queryImagesBySubKey(long seriesId, String subKey)	Returns all images of a specific sub key for a series, mapped as Java DTO.
Map<Long,Long>	queryLastUpdated(long fromTime)	Returns a map of series that have changed in the (one) week since the provided fromTime query parameter.
Map<Long,Long>	queryLastUpdated(long fromTime, long toTime)	Returns a map of series that have changed in between the given timeframe, but with a maximum of one week, starting at the provided fromTime query parameter.
Map<Long,Long>	queryLastUpdated(QueryParameters queryParameters)	Returns a map of series that have changed in a maximum of one week blocks since the provided fromTime query parameter.
List<Rating>	queryRatings(QueryParameters queryParameters)	Returns a list of ratings for a given user that match the query, mapped as Java DTO.
List<Rating>	queryRatingsByItemType(String itemType)	Returns a list of ratings for a given user that match the itemType parameter, mapped as Java DTO.
void	refreshToken()	Refreshes the current, valid JWT session token.
List<SeriesSearchResult>	searchSeries(QueryParameters queryParameters)	Returns a list of series search results based on the given query parameters mapped as Java DTO.
List<SeriesSearchResult>	searchSeriesByImdbId(String imdbId)	Search for series by IMDB-Id.
List<SeriesSearchResult>	searchSeriesByName(String name)	Search for series by name.
List<SeriesSearchResult>	searchSeriesByZap2itId(String zap2itId)	Search for series by Zap2it-Id.
void	setLanguage(String languageCode)	Sets the preferred language to be used for communication with the remote service.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TheTVDBApiImpl

public TheTVDBApiImpl(@Nonnull
                      String apiKey)

Creates a new TheTVDBApi instance. The given apiKey must be a valid TheTVDB.com API Key as it will be used for remote service authentication. To authenticate and generate a new session token use the init() or login() method right after creating a new instance of this API.

NOTE: Objects created with this constructor can not be used for calls to the remote API's /users routes. These calls require extended authentication using an additional userKey and userName.

Parameters:

apiKey - Valid TheTVDB.com API-Key

See Also:

TheTVDBApiImpl(apiKey, userKey, userName)

TheTVDBApiImpl

public TheTVDBApiImpl(@Nonnull
                      String apiKey,
                      @Nonnull
                      Proxy proxy)

Creates a new TheTVDBApi instance. The given apiKey must be a valid TheTVDB.com API Key as it will be used for remote service authentication. To authenticate and generate a new session token use the init() or login() method right after creating a new instance of this API. All communication to the remote API will be forwarded to the given proxy.

NOTE: Objects created with this constructor can not be used for calls to the remote API's /users routes. These calls require extended authentication using an additional userKey and userName.

Parameters:

apiKey - Valid TheTVDB.com API-Key

proxy - The proxy service to be used for remote API communication

See Also:

TheTVDBApiImpl(apiKey, userKey, userName, proxy)

TheTVDBApiImpl

public TheTVDBApiImpl(@Nonnull
                      String apiKey,
                      @Nonnull
                      String userKey,
                      @Nonnull
                      String userName)

Creates a new TheTVDBApi instance. The given apiKey must be a valid TheTVDB.com API Key. The userKey and userName must refer to a registered TheTVDB.com user account. The given parameters will be used for the initial remote service authentication. To authenticate and generate a new session token use the init() or login() method right after creating a new instance of this API.

Parameters:

apiKey - Valid TheTVDB.com API-Key

userKey - Valid TheTVDB.com user key (also referred to as "Unique ID")

userName - Registered TheTVDB.com user name

TheTVDBApiImpl

public TheTVDBApiImpl(@Nonnull
                      String apiKey,
                      @Nonnull
                      String userKey,
                      @Nonnull
                      String userName,
                      @Nonnull
                      Proxy proxy)

Creates a new TheTVDBApi instance. The given apiKey must be a valid TheTVDB.com API Key. The userKey and userName must refer to a registered TheTVDB.com user account. The given parameters will be used for the initial remote service authentication. To authenticate and generate a new session token use the init() or login() method right after creating a new instance of this API. All communication to the remote API will be forwarded to the given proxy.

Parameters:

apiKey - Valid TheTVDB.com API-Key

userKey - Valid TheTVDB.com user key (also referred to as "Unique ID")

userName - Registered TheTVDB.com user name

proxy - The proxy service to be used for remote API communication

Method Detail

init

public void init()
          throws APIException

Description copied from interface: TheTVDBApi

Initializes the current API session by requesting a new token from the remote API. This token will be used for authentication of all requests that are sent to the remote service by this API instance. The initialization will be performed based on the constructor parameters used to create this API instance. Actually this method will do the same as TheTVDBApi.login().

Specified by:

init in interface TheTVDBApi

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

init

public void init(@Nonnull
                 String token)
          throws APIException

Description copied from interface: TheTVDBApi

Initializes the current API with the given token. This token will be used for authentication of all requests that are sent to the remote service by this API instance. The given string must be a valid Base64 encoded token in the regular JWT format "{header}.{payload}.{signature}".

If the given token is (or becomes) expired it will be replaced by a new JWT automatically. The new token will be requested from the remove service based on the constructor parameters used to create this API instance.

Specified by:

init in interface TheTVDBApi

Parameters:

token - JSON Web Token to be used for remote API communication/authorization

Throws:

APIException - If the given string does not match the JSON Web Token format

getToken

public Optional<String> getToken()

Description copied from interface: TheTVDBApi

Returns the JSON Web Token used for authentication of all requests that are sent to the remote service by this API instance. If the current API has not yet been initialized an empty Optional instance will be returned.

Specified by:

getToken in interface TheTVDBApi

Returns:

The JWT used by this API or an empty Optional if the API has not been initialized

setLanguage

public void setLanguage(String languageCode)

Description copied from interface: TheTVDBApi

Sets the preferred language to be used for communication with the remote service. Some of the API calls might use this setting in order to only return results that match the given language. If available, the data returned by the remote API will be translated to the given language. The default language code is "en". For a list of supported languages see TheTVDBApi.getAvailableLanguages().

Specified by:

setLanguage in interface TheTVDBApi

Parameters:

languageCode - The language in which the results are to be returned

See Also:

TheTVDBApi.getAvailableLanguages()

login

public void login()
           throws APIException

Description copied from interface: TheTVDBApi

Initializes the current API session by requesting a new token from the remote API. This token will be used for authentication of all requests that are sent to the remote service by this API instance. The initialization will be performed based on the constructor parameters used to create this API instance. It is recommended to login/initialize the session before making the first API call. However, if an API call is made without proper initialization, an implicit login will be performed.

Corresponds to remote API route: [POST] /login

Specified by:

login in interface TheTVDBApi

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

refreshToken

public void refreshToken()
                  throws APIException

Description copied from interface: TheTVDBApi

Refreshes the current, valid JWT session token. This method can be used to extend the expiration date (24 hours) of the current session token without the need of a complete new login.

Corresponds to remote API route: [GET] /refresh_token

Specified by:

refreshToken in interface TheTVDBApi

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

getEpisode

public Episode getEpisode(long episodeId)
                   throws APIException

Description copied from interface: TheTVDBApi

Returns the full information for a given episode id as mapped Java DTO.

Corresponds to remote API route: [GET] /episodes/{id}

Specified by:

getEpisode in interface TheTVDBApi

Parameters:

episodeId - The ID of the episode

Returns:

Mapped Java DTO containing the full episode information based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given episode ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getEpisode(episodeId), TheTVDBApi.Extended.getEpisode(episodeId)

getAvailableLanguages

public List<Language> getAvailableLanguages()
                                     throws APIException

Description copied from interface: TheTVDBApi

Returns a list of all supported languages mapped as Java DTO. These language abbreviations can be used to set the preferred language for the communication with the remote service (see TheTVDBApi.setLanguage(String).

Corresponds to remote API route: [GET] /languages

Specified by:

getAvailableLanguages in interface TheTVDBApi

Returns:

List of available languages mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

TheTVDBApi.JSON.getAvailableLanguages(), TheTVDBApi.Extended.getAvailableLanguages()

getLanguage

public Language getLanguage(long languageId)
                     throws APIException

Description copied from interface: TheTVDBApi

Returns further language information for a given language ID mapped as Java DTO. The language abbreviation can be used to set the preferred language for the communication with the remote service (see TheTVDBApi.setLanguage(String).

Corresponds to remote API route: [GET] /languages/{id}

Specified by:

getLanguage in interface TheTVDBApi

Parameters:

languageId - The ID of the language

Returns:

Mapped Java DTO containing detailed language information based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if the given language ID does not exist.

See Also:

TheTVDBApi.JSON.getLanguage(languageId), TheTVDBApi.Extended.getLanguage(languageId)

getMovie

public Movie getMovie(long movieId)
               throws APIException

Description copied from interface: TheTVDBApi

Returns detailed information for a specific movie mapped as Java DTO.

Corresponds to remote API route: [GET] /movies/{id}

Specified by:

getMovie in interface TheTVDBApi

Parameters:

movieId - The TheTVDB.com movie ID

Returns:

Detailed information for a specific movie mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given movie ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getMovie(movieId), TheTVDBApi.Extended.getMovie(movieId)

getMovieUpdates

public List<Long> getMovieUpdates(long since)
                           throws APIException

Description copied from interface: TheTVDBApi

Returns a list of ID's of all movies that have been updated since the given epoch timestamp.

Corresponds to remote API route: [GET] /movieupdates

Specified by:

getMovieUpdates in interface TheTVDBApi

Parameters:

since - Epoch time to start your date range

Returns:

A list of updated movies ID's beginning at the given since time, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

TheTVDBApi.JSON.getMovieUpdates(since), TheTVDBApi.Extended.getMovieUpdates(since)

searchSeries

public List<SeriesSearchResult> searchSeries(QueryParameters queryParameters)
                                      throws APIException

Description copied from interface: TheTVDBApi

Returns a list of series search results based on the given query parameters mapped as Java DTO. The list contains basic information of all series matching the query parameters.

Corresponds to remote API route: [GET] /search/series

Specified by:

searchSeries in interface TheTVDBApi

Parameters:

queryParameters - Object containing key/value pairs of query search parameters. For a complete list of possible search parameters see the API documentation or use TheTVDBApi.getAvailableSeriesSearchParameters().

Returns:

List of series search results mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

See Also:

TheTVDBApi.JSON.searchSeries(queryParameters), TheTVDBApi.Extended.searchSeries(queryParameters)

searchSeriesByName

public List<SeriesSearchResult> searchSeriesByName(@Nonnull
                                                   String name)
                                            throws APIException

Description copied from interface: TheTVDBApi

Search for series by name. Returns a list of series search results mapped as Java DTO. The search results contain basic information of all series matching the given name. This is a shortcut-method for searchSeries(queryParameters) with a single "name" query parameter.

Specified by:

searchSeriesByName in interface TheTVDBApi

Parameters:

name - The name of the series to search for

Returns:

List of series search results mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

searchSeriesByImdbId

public List<SeriesSearchResult> searchSeriesByImdbId(@Nonnull
                                                     String imdbId)
                                              throws APIException

Description copied from interface: TheTVDBApi

Search for series by IMDB-Id. Returns a list of series search results mapped as Java DTO. The search results contain basic information of all series matching the given IMDB-Id. This is a shortcut-method for searchSeries(queryParameters) with a single "imdbId" query parameter.

Specified by:

searchSeriesByImdbId in interface TheTVDBApi

Parameters:

imdbId - The IMDB-Id of the series to search for

Returns:

List of series search results mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

searchSeriesByZap2itId

public List<SeriesSearchResult> searchSeriesByZap2itId(@Nonnull
                                                       String zap2itId)
                                                throws APIException

Description copied from interface: TheTVDBApi

Search for series by Zap2it-Id. Returns a list of series search results mapped as Java DTO. The search results contain basic information of all series matching the given Zap2it-Id. This is a shortcut-method for searchSeries(queryParameters) with a single "zap2itId" query parameter.

Specified by:

searchSeriesByZap2itId in interface TheTVDBApi

Parameters:

zap2itId - The Zap2it-Id of the series to search for

Returns:

List of series search results mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no records are found that match your query.

getAvailableSeriesSearchParameters

public List<String> getAvailableSeriesSearchParameters()
                                                throws APIException

Description copied from interface: TheTVDBApi

Returns possible query parameters, which can be used to search for series, mapped as Java DTO.

Corresponds to remote API route: [GET] /search/series/params

Specified by:

getAvailableSeriesSearchParameters in interface TheTVDBApi

Returns:

List of possible parameters to query by in the series search route

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

TheTVDBApi.JSON.getAvailableSeriesSearchParameters(), TheTVDBApi.Extended.getAvailableSeriesSearchParameters(), TheTVDBApi.JSON.searchSeries(queryParams), TheTVDBApi.Extended.searchSeries(queryParams), searchSeries(queryParams)

getSeries

public Series getSeries(long seriesId)
                 throws APIException

Description copied from interface: TheTVDBApi

Returns detailed information for a specific series mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}

Specified by:

getSeries in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Detailed information for a specific series mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeries(seriesId), TheTVDBApi.Extended.getSeries(seriesId)

getSeriesHeaderInformation

public Map<String,String> getSeriesHeaderInformation(long seriesId)
                                              throws APIException

Description copied from interface: TheTVDBApi

Returns header information for a specific series as key/value pairs. Good for getting the Last-Updated header to find out when the series was last modified.

Corresponds to remote API route: [HEAD] /series/{id}

Specified by:

getSeriesHeaderInformation in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

HTML header information returned by the remote service mapped as key/value pairs

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeriesHeaderInformation(seriesId), TheTVDBApi.Extended.getSeriesHeaderInformation(seriesId)

getActors

public List<Actor> getActors(long seriesId)
                      throws APIException

Description copied from interface: TheTVDBApi

Returns a list of actors for a specific series mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/actors

Specified by:

getActors in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

List of actors mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getActors(seriesId), TheTVDBApi.Extended.getActors(seriesId)

getEpisodes

public List<Episode> getEpisodes(long seriesId,
                                 QueryParameters queryParameters)
                          throws APIException

Description copied from interface: TheTVDBApi

Returns all episodes of a specific series mapped as Java DTO. Results will be paginated with 100 results per page. Use queryParameters to select a specific result page.

Corresponds to remote API route: [GET] /series/{id}/episodes

Specified by:

getEpisodes in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible parameters see the API documentation.

Returns:

List of episodes mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getEpisodes(seriesId, queryParameters), TheTVDBApi.Extended.getEpisodes(seriesId, queryParameters)

getEpisodes

public List<Episode> getEpisodes(long seriesId)
                          throws APIException

Description copied from interface: TheTVDBApi

Returns the first 100 episodes of a specific series mapped as Java DTO. Note that this method is deterministic and will always return the first result page of the available episodes. This is a shortcut-method for getEpisodes(seriesId, queryParameters) with an empty query parameter.

Specified by:

getEpisodes in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

List of episodes mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

getEpisodes(seriesId, page)

getEpisodes

public List<Episode> getEpisodes(long seriesId,
                                 long page)
                          throws APIException

Description copied from interface: TheTVDBApi

Returns a list of episodes of a specific series mapped as Java DTO. The result list will contain 100 episodes at most. For series with more episodes use the page parameter to browse to a specific result page. This is a shortcut-method for getEpisodes(seriesId, queryParameters) with a single "page" query parameter.

Specified by:

getEpisodes in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

page - The result page to be returned

Returns:

List of episodes mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

getEpisodes(seriesId)

queryEpisodes

public List<Episode> queryEpisodes(long seriesId,
                                   QueryParameters queryParameters)
                            throws APIException

Description copied from interface: TheTVDBApi

Returns all matching episodes of a specific series mapped as Java DTO. Results will be paginated. Note that this method is deterministic and will always return the first result page of the available episodes.

Corresponds to remote API route: [GET] /series/{id}/episodes/query

Specified by:

queryEpisodes in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableEpisodeQueryParameters(seriesId).

Returns:

List of episodes matching the query parameters, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

TheTVDBApi.JSON.queryEpisodes(seriesId, queryParameters), TheTVDBApi.Extended.queryEpisodes(seriesId, queryParameters)

queryEpisodesByAiredSeason

public List<Episode> queryEpisodesByAiredSeason(long seriesId,
                                                long airedSeason)
                                         throws APIException

Description copied from interface: TheTVDBApi

Returns all episodes of a specific series and season mapped as Java DTO. Results will be paginated. Note that this method is deterministic and will always return the first result page of the available episodes. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a single "airedSeason" query parameter.

Specified by:

queryEpisodesByAiredSeason in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

airedSeason - The number of the aired season to query for

Returns:

List of episodes for a specific season, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

queryEpisodesByAiredSeason(seriesId, airedSeason, page)

queryEpisodesByAiredSeason

public List<Episode> queryEpisodesByAiredSeason(long seriesId,
                                                long airedSeason,
                                                long page)
                                         throws APIException

Description copied from interface: TheTVDBApi

Returns all episodes of a specific series and season mapped as Java DTO. Results will be paginated. For seasons with a high number of episodes use the page parameter to browse to a specific result page. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a "airedSeason" and "page" query parameter.

Specified by:

queryEpisodesByAiredSeason in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

airedSeason - The number of the aired season to query for

page - The result page to be returned

Returns:

List of episodes for a specific season, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

queryEpisodesByAiredSeason(seriesId, airedSeason)

queryEpisodesByAiredEpisode

public List<Episode> queryEpisodesByAiredEpisode(long seriesId,
                                                 long airedEpisode)
                                          throws APIException

Description copied from interface: TheTVDBApi

Returns all episodes of a specific series, matching the airedEpisode parameter, mapped as Java DTO. Results will be paginated. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a single "airedEpisode" query parameter.

Note that an aired episode number might be associated with a specific season. If the series consists of more than one season this method will return the matching aired episodes from all the seasons. Use TheTVDBApi.queryEpisodesByAbsoluteNumber(long, long) in order to query for a single episode.

Specified by:

queryEpisodesByAiredEpisode in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

airedEpisode - The number of the aired episode to query for

Returns:

List of episodes for a specific season and aired episode number, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

queryEpisodesByAbsoluteNumber(seriesId, absoluteNumber)

queryEpisodesByAbsoluteNumber

public List<Episode> queryEpisodesByAbsoluteNumber(long seriesId,
                                                   long absoluteNumber)
                                            throws APIException

Description copied from interface: TheTVDBApi

Returns a specific episode of a series, mapped as Java DTO. Results will be paginated. This is a shortcut-method for queryEpisodes(seriesId, queryParameters) with a single "absoluteNumber" query parameter.

Note that (unlike an aired episode number) an absolute episode number should most likely be unique throughout all episodes of a specific series. So in most cases the returned list will consist of only one element. However, as the remote API doesn't give any guarantees that querying with an "absoluteNumber" parameter always returns one episode record at most this method will return all episode data as received from the remote service.

Specified by:

queryEpisodesByAbsoluteNumber in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

absoluteNumber - The absolute number of the episode to query for (this is not the episode ID!)

Returns:

List of episodes for an absolute episode number, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

getEpisode(episodeId)

getAvailableEpisodeQueryParameters

public List<String> getAvailableEpisodeQueryParameters(long seriesId)
                                                throws APIException

Description copied from interface: TheTVDBApi

Returns a list of keys which are valid parameters for querying episodes, as plain Strings. These keys are permitted to be used in QueryParameters objects when querying for specific episodes of a series.

Corresponds to remote API route: [GET] /series/{id}/episodes/query/params

Specified by:

getAvailableEpisodeQueryParameters in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

List of allowed keys to be used for querying episodes, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

queryEpisodes(seriesId, queryParameters), TheTVDBApi.JSON.getAvailableEpisodeQueryParameters(seriesId), TheTVDBApi.Extended.getAvailableEpisodeQueryParameters(seriesId)

getSeriesEpisodesSummary

public SeriesSummary getSeriesEpisodesSummary(long seriesId)
                                       throws APIException

Description copied from interface: TheTVDBApi

Returns a summary of the episodes and seasons available for a series, mapped as Java DTO.
Note: Season "0" is for all episodes that are considered to be specials.

Corresponds to remote API route: [GET] /series/{id}/episodes/summary

Specified by:

getSeriesEpisodesSummary in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

A summary of the episodes and seasons available for the given series, mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeriesEpisodesSummary(seriesId), TheTVDBApi.Extended.getSeriesEpisodesSummary(seriesId)

filterSeries

public Series filterSeries(long seriesId,
                           QueryParameters queryParameters)
                    throws APIException

Description copied from interface: TheTVDBApi

Returns a filtered series record based on the given parameters, mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/filter

Specified by:

filterSeries in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableSeriesFilterParameters(seriesId).

Returns:

A filtered series record, mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.filterSeries(seriesId, queryParameters), TheTVDBApi.Extended.filterSeries(seriesId, queryParameters)

filterSeries

public Series filterSeries(long seriesId,
                           @Nonnull
                           String filterKeys)
                    throws APIException

Description copied from interface: TheTVDBApi

Returns a series records, filtered by the supplied comma-separated list of keys, mapped as Java DTO. This is a shortcut-method for filterSeries(seriesId, queryParameters) with a single "keys" query parameter.

Specified by:

filterSeries in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

filterKeys - Comma-separated list of keys to filter by

Returns:

A filtered series record, mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

getAvailableSeriesFilterParameters

public List<String> getAvailableSeriesFilterParameters(long seriesId)
                                                throws APIException

Description copied from interface: TheTVDBApi

Returns a list of keys which are valid parameters for filtering series, as plain Strings. These keys are permitted to be used in QueryParameters objects when filtering for a specific series.

Corresponds to remote API route: [GET] /series/{id}/filter/params

Specified by:

getAvailableSeriesFilterParameters in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

A list of keys to filter by, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

filterSeries(seriesId, queryParameters), TheTVDBApi.JSON.getAvailableSeriesFilterParameters(seriesId), TheTVDBApi.Extended.getAvailableSeriesFilterParameters(seriesId)

getSeriesImagesSummary

public ImageSummary getSeriesImagesSummary(long seriesId)
                                    throws APIException

Description copied from interface: TheTVDBApi

Returns a summary of the images types and counts available for a particular series, mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/images

Specified by:

getSeriesImagesSummary in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

A summary of the image types and counts available for the given series, mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

TheTVDBApi.JSON.getSeriesImagesSummary(seriesId), TheTVDBApi.Extended.getSeriesImagesSummary(seriesId)

queryImages

public List<Image> queryImages(long seriesId,
                               QueryParameters queryParameters)
                        throws APIException

Description copied from interface: TheTVDBApi

Returns the matching result of querying images for a specific series, mapped as Java DTO.

Corresponds to remote API route: [GET] /series/{id}/images/query

Specified by:

queryImages in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId).

Returns:

List of images that matched the query, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

TheTVDBApi.JSON.queryImages(seriesId, queryParameters), TheTVDBApi.Extended.queryImages(seriesId, queryParameters)

queryImages

public List<Image> queryImages(long seriesId,
                               @Nonnull
                               String keyType,
                               @Nonnull
                               String resolution)
                        throws APIException

Description copied from interface: TheTVDBApi

Returns all images for a specific series, matching the given parameters, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a "keyType" and "resolution" query parameter.

Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

Specified by:

queryImages in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

keyType - Type of image you're querying for (fanart, poster, etc.)

resolution - Resolution to filter by (1280x1024, for example)

Returns:

List of images that matched the given parameters, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

queryImages(seriesId, keyType, resolution, subKey)

queryImages

public List<Image> queryImages(long seriesId,
                               @Nonnull
                               String keyType,
                               @Nonnull
                               String resolution,
                               @Nonnull
                               String subKey)
                        throws APIException

Description copied from interface: TheTVDBApi

Returns all images for a specific series, matching the given parameters, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a "keyType", a "resolution" and a "subKey" query parameter.

Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

Specified by:

queryImages in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

keyType - Type of image you're querying for (fanart, poster, etc.)

resolution - Resolution to filter by (1280x1024, for example)

subKey - Subkey for the other method query parameters

Returns:

List of images that matched the given parameters, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

See Also:

queryImages(seriesId, keyType, resolution)

queryImagesByKeyType

public List<Image> queryImagesByKeyType(long seriesId,
                                        @Nonnull
                                        String keyType)
                                 throws APIException

Description copied from interface: TheTVDBApi

Returns all images of a specific type for a series, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a single "keyType" query parameter.

Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

Specified by:

queryImagesByKeyType in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

keyType - Type of image you're querying for (fanart, poster, etc.)

Returns:

List of images of the given key type, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

queryImagesByResolution

public List<Image> queryImagesByResolution(long seriesId,
                                           @Nonnull
                                           String resolution)
                                    throws APIException

Description copied from interface: TheTVDBApi

Returns all images of a specific resolution for a series, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a single "resolution" query parameter.

Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

Specified by:

queryImagesByResolution in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

resolution - Resolution to filter by (1280x1024, for example)

Returns:

List of images with the given resolution, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

queryImagesBySubKey

public List<Image> queryImagesBySubKey(long seriesId,
                                       @Nonnull
                                       String subKey)
                                throws APIException

Description copied from interface: TheTVDBApi

Returns all images of a specific sub key for a series, mapped as Java DTO. This is a shortcut-method for queryImages(seriesId, queryParameters) with a single "subKey" query parameter.

Note: For more details regarding valid values for the method specific query parameters see the API documentation or use getAvailableImageQueryParameters(seriesId)

Specified by:

queryImagesBySubKey in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

subKey - Subkey to query for

Returns:

List of images matching the given sub key, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc. or if no records are found that match your query.

getAvailableImageQueryParameters

public List<ImageQueryParameter> getAvailableImageQueryParameters(long seriesId)
                                                           throws APIException

Description copied from interface: TheTVDBApi

Returns a list of valid parameters for querying a series images, mapped as Java DTO. Unlike other routes, querying for a series images may be restricted to certain combinations of query keys. The allowed combinations are clustered in the single ImageQueryParameter objects returned by this method.

Corresponds to remote API route: [GET] /series/{id}/images/query/params

Specified by:

getAvailableImageQueryParameters in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

A list of possible parameters which may be used to query a series images, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, the given series ID does not exist, etc.

See Also:

queryImages(seriesId, queryParameters), TheTVDBApi.JSON.getAvailableImageQueryParameters(seriesId), TheTVDBApi.Extended.getAvailableImageQueryParameters(seriesId)

queryLastUpdated

public Map<Long,Long> queryLastUpdated(QueryParameters queryParameters)
                                throws APIException

Description copied from interface: TheTVDBApi

Returns a map of series that have changed in a maximum of one week blocks since the provided fromTime query parameter. The key/value pairs of the returned map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. Note that the given query parameters must always contain a valid fromTime Epoch timestamp key.

The user may specify an additional toTime query key to grab results for less than a week. Any timespan larger than a week will be reduced down to one week automatically.

Corresponds to remote API route: [GET] /updated/query

Specified by:

queryLastUpdated in interface TheTVDBApi

Parameters:

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use TheTVDBApi.getAvailableLastUpdatedQueryParameters().

Returns:

A map of updated objects that match the given timeframe, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.

See Also:

TheTVDBApi.JSON.queryLastUpdated(queryParameters), TheTVDBApi.Extended.queryLastUpdated(queryParameters)

queryLastUpdated

public Map<Long,Long> queryLastUpdated(long fromTime)
                                throws APIException

Description copied from interface: TheTVDBApi

Returns a map of series that have changed in the (one) week since the provided fromTime query parameter. The key/value pairs of the returned map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. This is a shortcut-method for queryLastUpdated(queryParameters) with a single "fromTime" query parameter.

Specified by:

queryLastUpdated in interface TheTVDBApi

Parameters:

fromTime - Epoch time to start your date range

Returns:

A map of updated objects beginning at the given fromTime, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.

See Also:

queryLastUpdated(fromTime, toTime)

queryLastUpdated

public Map<Long,Long> queryLastUpdated(long fromTime,
                                       long toTime)
                                throws APIException

Description copied from interface: TheTVDBApi

Returns a map of series that have changed in between the given timeframe, but with a maximum of one week, starting at the provided fromTime query parameter. The toTime parameter may be specified to grab results for less than a week. Any timespan larger than a week will be reduced down to one week automatically. The key/value pairs of the returned map represent a TheTVDB.com series ID (key) and when it was updated the last time (value) as Epoch time. This is a shortcut-method for queryLastUpdated(queryParameters) with a "fromTime" and a "toTime" query parameter.

Specified by:

queryLastUpdated in interface TheTVDBApi

Parameters:

fromTime - Epoch time to start your date range

toTime - Epoch time to end your date range. Must not be greater than one week from fromTime.

Returns:

A map of updated objects matching the given timeframe, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or no records exist for the given timespan.

See Also:

queryLastUpdated(fromTime)

getAvailableLastUpdatedQueryParameters

public List<String> getAvailableLastUpdatedQueryParameters()
                                                    throws APIException

Description copied from interface: TheTVDBApi

Returns a list of valid parameters for querying series which have been updated lately, as plain Strings. These keys are permitted to be used in QueryParameters objects when querying for recently updated series.

Corresponds to remote API route: [GET] /updated/query/params

Specified by:

getAvailableLastUpdatedQueryParameters in interface TheTVDBApi

Returns:

A list of possible parameters which may be used to query for last updated series, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

See Also:

queryLastUpdated(queryParameters), TheTVDBApi.JSON.getAvailableLastUpdatedQueryParameters(), TheTVDBApi.Extended.getAvailableLastUpdatedQueryParameters()

getUser

public User getUser()
             throws APIException

Description copied from interface: TheTVDBApi

Returns basic information about the currently authenticated user, mapped as Java DTO.

Corresponds to remote API route: [GET] /user

Specified by:

getUser in interface TheTVDBApi

Returns:

Basic user information, mapped as Java DTO based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.getUser(), TheTVDBApi.Extended.getUser()

getFavorites

public List<String> getFavorites()
                          throws APIException

Description copied from interface: TheTVDBApi

Returns a list of favorite series for a given user, as plain Strings. Will be an empty list if no favorites exist.

Corresponds to remote API route: [GET] /user/favorites

Specified by:

getFavorites in interface TheTVDBApi

Returns:

The user favorites, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.getFavorites(), TheTVDBApi.Extended.getFavorites()

deleteFromFavorites

public List<String> deleteFromFavorites(long seriesId)
                                 throws APIException

Description copied from interface: TheTVDBApi

Deletes the given series ID from the user’s favorite’s list and returns the updated list as plain Strings.

Corresponds to remote API route: [DELETE] /user/favorites/{id}

Specified by:

deleteFromFavorites in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Updated list of user favorites, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user or the requested record could not be deleted

See Also:

addToFavorites(seriesId), TheTVDBApi.JSON.deleteFromFavorites(seriesId), TheTVDBApi.Extended.deleteFromFavorites(seriesId)

addToFavorites

public List<String> addToFavorites(long seriesId)
                            throws APIException

Description copied from interface: TheTVDBApi

Adds the supplied series ID to the user’s favorite’s list and returns the updated list as plain Strings.

Corresponds to remote API route: [PUT] /user/favorites/{id}

Specified by:

addToFavorites in interface TheTVDBApi

Parameters:

seriesId - The TheTVDB.com series ID

Returns:

Updated list of user favorites, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user or the requested record could not be updated

See Also:

deleteFromFavorites(seriesId), TheTVDBApi.JSON.addToFavorites(seriesId), TheTVDBApi.Extended.addToFavorites(seriesId)

getRatings

public List<Rating> getRatings()
                        throws APIException

Description copied from interface: TheTVDBApi

Returns a list of ratings for the given user, mapped as Java DTO.

Corresponds to remote API route: [GET] /user/ratings

Specified by:

getRatings in interface TheTVDBApi

Returns:

List of user ratings, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.getRatings(), TheTVDBApi.Extended.getRatings()

queryRatings

public List<Rating> queryRatings(QueryParameters queryParameters)
                          throws APIException

Description copied from interface: TheTVDBApi

Returns a list of ratings for a given user that match the query, mapped as Java DTO.

Corresponds to remote API route: [GET] /user/ratings/query

Specified by:

queryRatings in interface TheTVDBApi

Parameters:

queryParameters - Object containing key/value pairs of query parameters. For a complete list of possible query parameters see the API documentation or use TheTVDBApi.getAvailableRatingsQueryParameters().

Returns:

List of user ratings that match the given query, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

TheTVDBApi.JSON.queryRatings(queryParameters), TheTVDBApi.Extended.queryRatings(queryParameters)

queryRatingsByItemType

public List<Rating> queryRatingsByItemType(@Nonnull
                                           String itemType)
                                    throws APIException

Description copied from interface: TheTVDBApi

Returns a list of ratings for a given user that match the itemType parameter, mapped as Java DTO. This is a shortcut-method for queryRatings(queryParameters) with a single "itemType" query parameter.

Specified by:

queryRatingsByItemType in interface TheTVDBApi

Parameters:

itemType - Item to query. Can be either 'series', 'episode', or 'banner'.

Returns:

List of user ratings with the given item type, mapped as Java DTO's based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc.

getAvailableRatingsQueryParameters

public List<String> getAvailableRatingsQueryParameters()
                                                throws APIException

Description copied from interface: TheTVDBApi

Returns a list of valid parameters for querying user ratings, as plain Strings. These keys are permitted to be used in QueryParameters objects when querying for ratings.

Corresponds to remote API route: [GET] /user/ratings/query/params

Specified by:

getAvailableRatingsQueryParameters in interface TheTVDBApi

Returns:

A list of possible parameters which may be used to query for user ratings, based on the JSON data returned by the remote service

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no information exists for the current user

See Also:

queryRatings(queryParameters), TheTVDBApi.JSON.getAvailableRatingsQueryParameters(), TheTVDBApi.Extended.getAvailableRatingsQueryParameters()

deleteFromRatings

public void deleteFromRatings(@Nonnull
                              String itemType,
                              long itemId)
                       throws APIException

Description copied from interface: TheTVDBApi

Deletes a given rating of a given type.

Corresponds to remote API route: [DELETE] /user/ratings/{itemType}/{itemId}

Specified by:

deleteFromRatings in interface TheTVDBApi

Parameters:

itemType - Item to update. Can be either 'series', 'episode', or 'image'.

itemId - ID of the ratings record that you wish to delete

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no rating is found that matches your given parameters

See Also:

addToRatings(itemType, itemId, itemRating), TheTVDBApi.JSON.deleteFromRatings(itemType, itemId), TheTVDBApi.Extended.deleteFromRatings(itemType, itemId)

addToRatings

public List<Rating> addToRatings(@Nonnull
                                 String itemType,
                                 long itemId,
                                 long itemRating)
                          throws APIException

Description copied from interface: TheTVDBApi

Updates a given rating of a given type and returns the modified rating, mapped as Java DTO. If no rating exists yet, a new rating will be created.

Corresponds to remote API route: [PUT] /user/ratings/{itemType}/{itemId}/{itemRating}

Specified by:

addToRatings in interface TheTVDBApi

Parameters:

itemType - Item to update. Can be either 'series', 'episode', or 'image'.

itemId - ID of the ratings record that you wish to modify

itemRating - The updated rating number

Returns:

The modified rating (whether it was added or updated), mapped as Java DTO based on the JSON data returned by the remote service
Note: It seems that the data returned by the remote service for this route is quite unreliable! It might not always return the modified rating but an empty data array instead.

Throws:

APIException - If an exception with the remote API occurs, e.g. authentication failure, IO error, resource not found, etc. or if no rating is found that matches your given parameters

See Also:

deleteFromRatings(itemType, itemId), TheTVDBApi.JSON.addToRatings(itemType, itemId, itemRating), TheTVDBApi.Extended.addToRatings(itemType, itemId, itemRating)

json

public TheTVDBApi.JSON json()

Description copied from interface: TheTVDBApi

Provides access to the API's JSON layout.

In this layout, all methods will return the raw, unmodified JSON as received from the remove service.

Specified by:

json in interface TheTVDBApi

Returns:

Instance representing the the API's JSON layout

extended

public TheTVDBApi.Extended extended()

Description copied from interface: TheTVDBApi

Provides access to the API's Extended layout.

In this layout, all methods will return a single APIResponse object, containing the actual request data, mapped as DTO, as well as all additional information that is available in the corresponding context.

Specified by:

extended in interface TheTVDBApi

Returns:

Instance representing the the API's Extended layout