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

Class UsersAPI

java.lang.Object

com.github.m0nk3y2k4.thetvdb.internal.resource.Resource

com.github.m0nk3y2k4.thetvdb.internal.resource.QueryResource

com.github.m0nk3y2k4.thetvdb.internal.resource.impl.UsersAPI

public final class UsersAPI
extends QueryResource

Implementation of a connector for the remote API's Users endpoint.

Provides static access to all routes of this endpoint which may be used to handle user data.

Field Summary

Fields inherited from class com.github.m0nk3y2k4.thetvdb.internal.resource.Resource

ID_VALIDATOR, PATH_ID

Method Summary

Modifier and Type	Method	Description
static com.fasterxml.jackson.databind.JsonNode	addToFavorites(APIConnection con, long id)	Adds the supplied series ID to the user’s favorite’s list and returns the updated list as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	addToRatings(APIConnection con, String itemType, long itemId, long itemRating)	Updates a given rating of a given type and returns the modified rating, mapped as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	deleteFromFavorites(APIConnection con, long id)	Deletes the given series ID from the user’s favorite’s list and returns the updated list as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	deleteFromRatings(APIConnection con, String itemType, long itemId)	Deletes a given rating of a given type.
static com.fasterxml.jackson.databind.JsonNode	get(APIConnection con)	Returns basic information about the currently authenticated user, as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	getFavorites(APIConnection con)	Returns an array of favorite series for a given user, as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	getRatings(APIConnection con)	Returns a list of ratings for the given user, as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	getRatingsQueryParams(APIConnection con)	Returns a list of valid parameters for querying user ratings, as raw JSON.
static com.fasterxml.jackson.databind.JsonNode	queryRatings(APIConnection con, QueryParameters params)	Returns a list of ratings for a given user that match the query, as raw JSON.

Methods inherited from class java.lang.Object

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

Methods inherited from class com.github.m0nk3y2k4.thetvdb.internal.resource.QueryResource

createQueryResource

Methods inherited from class com.github.m0nk3y2k4.thetvdb.internal.resource.Resource

createResource, createResource

Method Detail

get

public static com.fasterxml.jackson.databind.JsonNode get(@Nonnull
                                                          APIConnection con)
                                                   throws APIException

Returns basic information about the currently authenticated user, as raw JSON.

Corresponds to remote API route: [GET] /user

Parameters:

con - Initialized connection to be used for API communication

Returns:

JSON object containing basic user information

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

getFavorites

public static com.fasterxml.jackson.databind.JsonNode getFavorites(@Nonnull
                                                                   APIConnection con)
                                                            throws APIException

Returns an array of favorite series for a given user, as raw JSON. Will be a blank array if no favorites exist.

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

Parameters:

con - Initialized connection to be used for API communication

Returns:

JSON object containing the user favorites

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

deleteFromFavorites

public static com.fasterxml.jackson.databind.JsonNode deleteFromFavorites(@Nonnull
                                                                          APIConnection con,
                                                                          long id)
                                                                   throws APIException

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

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

Parameters:

con - Initialized connection to be used for API communication

id - The TheTVDB.com series ID

Returns:

JSON object containing the updated list of user favorites

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

addToFavorites

public static com.fasterxml.jackson.databind.JsonNode addToFavorites(@Nonnull
                                                                     APIConnection con,
                                                                     long id)
                                                              throws APIException

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

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

Parameters:

con - Initialized connection to be used for API communication

id - The TheTVDB.com series ID

Returns:

JSON object containing the updated list of user favorites

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

getRatings

public static com.fasterxml.jackson.databind.JsonNode getRatings(@Nonnull
                                                                 APIConnection con)
                                                          throws APIException

Returns a list of ratings for the given user, as raw JSON.

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

Parameters:

con - Initialized connection to be used for API communication

Returns:

JSON object containing a list of user ratings

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

queryRatings

public static com.fasterxml.jackson.databind.JsonNode queryRatings(@Nonnull
                                                                   APIConnection con,
                                                                   @CheckForNull
                                                                   QueryParameters params)
                                                            throws APIException

Returns a list of ratings for a given user that match the query, as raw JSON.

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

Parameters:

con - Initialized connection to be used for API communication

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

Returns:

JSON object containing a list of user ratings that match the given query

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

getRatingsQueryParams

public static com.fasterxml.jackson.databind.JsonNode getRatingsQueryParams(@Nonnull
                                                                            APIConnection con)
                                                                     throws APIException

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

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

Parameters:

con - Initialized connection to be used for API communication

Returns:

JSON object containing a list of possible parameters which may be used to query for user ratings

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

deleteFromRatings

public static com.fasterxml.jackson.databind.JsonNode deleteFromRatings(@Nonnull
                                                                        APIConnection con,
                                                                        @Nonnull
                                                                        String itemType,
                                                                        long itemId)
                                                                 throws APIException

Deletes a given rating of a given type.

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

Parameters:

con - Initialized connection to be used for API communication

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

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

Returns:

JSON object as returned by the remote service (probably containing an empty data block)

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

addToRatings

public static com.fasterxml.jackson.databind.JsonNode addToRatings(@Nonnull
                                                                   APIConnection con,
                                                                   @Nonnull
                                                                   String itemType,
                                                                   long itemId,
                                                                   long itemRating)
                                                            throws APIException

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

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

Parameters:

con - Initialized connection to be used for API communication

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:

JSON object containing the modified rating (whether it was added or updated)
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