Package com.github.m0nk3y2k4.thetvdb.internal.connection

Class APIConnection

java.lang.Object

com.github.m0nk3y2k4.thetvdb.internal.connection.APIConnection

public class APIConnection
extends Object

Main class for handling communication with the TheTVDB.com REST remote service on a technical level

It provides options to invoke different types of HTTP requests to any given API route. It will also maintain additional session information like API key, the JWT token and authentication status and will handle the Bearer authentication for each request.

Although it is highly recommended to first off authenticate a newly created API connection manually via the TheTVDBApi.login() method, this API connection also provides some automatic on-demand authorization. In case an attempt is made to call any of the API routes without previous authorization, the connection will automatically try to resolve the HTTP-401 state by invoking the login() function followed by a retry of requesting the original resource.

Constructor Summary

Constructors

Constructor	Description
APIConnection(String apiKey)	Creates a new TheTVDB.com API connection using the given apiKey for remote service authentication.
APIConnection(String apiKey, String userKey, String userName)	Creates a new TheTVDB.com API connection using the given credentials for remote service authentication.
APIConnection(String apiKey, String userKey, String userName, Supplier<RemoteAPI> remote)	Creates a new API connection using the given credentials for remote service authentication.
APIConnection(String apiKey, Supplier<RemoteAPI> remote)	Creates a new API connection using the given apiKey for remote service authentication.

Method Summary

Modifier and Type	Method	Description
String	getApiKey()	Returns the API key related to this connection
protected APISession.Status	getStatus()	Returns the current APISession.Status of the underlying session.
Optional<String>	getToken()	Returns the JWT token that is currently used for Bearer authentication.
Optional<String>	getUserKey()	Returns the user key related to this connection.
Optional<String>	getUserName()	Returns the user name related to this connection.
com.fasterxml.jackson.databind.JsonNode	sendDELETE(String resource)	Invokes a new DELETE request onto the given resource and returns the response as raw, unmodified JSON.
com.fasterxml.jackson.databind.JsonNode	sendGET(String resource)	Invokes a new GET request onto the given resource and returns the response as raw, unmodified JSON.
com.fasterxml.jackson.databind.JsonNode	sendHEAD(String resource)	Invokes a new HEAD request onto the given resource and returns the response as raw, unmodified JSON.
com.fasterxml.jackson.databind.JsonNode	sendPOST(String resource, String data)	Invokes a new POST request onto the given resource and returns the response as raw, unmodified JSON.
com.fasterxml.jackson.databind.JsonNode	sendPUT(String resource)	Invokes a new PUT request onto the given resource and returns the response as raw, unmodified JSON.
void	setLanguage(String language)	Set the preferred language used for API communication.
void	setStatus(APISession.Status status)	Sets the current status of the underlying session.
void	setToken(String token)	Sets the JWT token of the underlying session which will then be used further communication authentication
boolean	userAuthentication()	Checks whether user authentication is available or not.

Methods inherited from class java.lang.Object

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

Constructor Detail

APIConnection

public APIConnection(@Nonnull
                     String apiKey)

Creates a new TheTVDB.com API connection using the given apiKey for remote service authentication. The given key must be a valid TheTVDB.com API Key.

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:

APIConnection(apiKey, userName, userKey)

APIConnection

public APIConnection(@Nonnull
                     String apiKey,
                     @Nonnull
                     Supplier<RemoteAPI> remote)

Creates a new API connection using the given apiKey for remote service authentication. The given key must be a valid TheTVDB.com API Key. All outgoing communication will be directed towards the given remote endpoint.

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

remote - Supplier providing the remote API endpoint to be used by this connection

See Also:

APIConnection(apiKey, userName, userKey, remote)

APIConnection

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

Creates a new TheTVDB.com API connection using the given credentials for remote service authentication. The given apiKey must be a valid TheTVDB.com API Key. The userKey and userName must refer to a registered TheTVDB.com user account.

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

See Also:

APIConnection(apiKey)

APIConnection

public APIConnection(@Nonnull
                     String apiKey,
                     @Nonnull
                     String userKey,
                     @Nonnull
                     String userName,
                     @Nonnull
                     Supplier<RemoteAPI> remote)

Creates a new API connection using the given credentials for remote service authentication. The given apiKey must be a valid TheTVDB.com API Key. The userKey and userName must refer to a registered TheTVDB.com user account. All outgoing communication will be directed towards the given remote endpoint.

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

remote - Supplier providing the remote API endpoint to be used by this connection

See Also:

APIConnection(apiKey, remote)

Method Detail

sendGET

public com.fasterxml.jackson.databind.JsonNode sendGET(@Nonnull
                                                       String resource)
                                                throws APIException

Invokes a new GET request onto the given resource and returns the response as raw, unmodified JSON. In case this connection has not yet been authorized an automated authorization attempt will be triggered.

Parameters:

resource - The remote API resource to be invoked

Returns:

The raw JSON response as received by the remote service

Throws:

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

sendPOST

public com.fasterxml.jackson.databind.JsonNode sendPOST(@Nonnull
                                                        String resource,
                                                        @Nonnull
                                                        String data)
                                                 throws APIException

Invokes a new POST request onto the given resource and returns the response as raw, unmodified JSON. In case this connection has not yet been authorized an automated authorization attempt will be triggered.

Parameters:

resource - The remote API resource to be invoked

data - The request payload to be pushed to the remote service

Returns:

The raw JSON response as received by the remote service

Throws:

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

sendHEAD

public com.fasterxml.jackson.databind.JsonNode sendHEAD(@Nonnull
                                                        String resource)
                                                 throws APIException

Invokes a new HEAD request onto the given resource and returns the response as raw, unmodified JSON. In case this connection has not yet been authorized an automated authorization attempt will be triggered.

Parameters:

resource - The remote API resource to be invoked

Returns:

The raw JSON response as received by the remote service

Throws:

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

sendDELETE

public com.fasterxml.jackson.databind.JsonNode sendDELETE(@Nonnull
                                                          String resource)
                                                   throws APIException

Invokes a new DELETE request onto the given resource and returns the response as raw, unmodified JSON. In case this connection has not yet been authorized an automated authorization attempt will be triggered.

Parameters:

resource - The remote API resource to be invoked

Returns:

The raw JSON response as received by the remote service

Throws:

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

sendPUT

public com.fasterxml.jackson.databind.JsonNode sendPUT(@Nonnull
                                                       String resource)
                                                throws APIException

Invokes a new PUT request onto the given resource and returns the response as raw, unmodified JSON. In case this connection has not yet been authorized an automated authorization attempt will be triggered.

Parameters:

resource - The remote API resource to be invoked

Returns:

The raw JSON response as received by the remote service

Throws:

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

setToken

public void setToken(@Nonnull
                     String token)
              throws APIException

Sets the JWT token of the underlying session which will then be used further communication authentication

Parameters:

token - The new JWT session token issued by the remote service

Throws:

APIException - If the given token is null, an empty character sequence or does not match the regular JWT format

setStatus

public void setStatus(APISession.Status status)

Sets the current status of the underlying session. If the given status parameter is null the sessions status will be reset to APISession.Status.NOT_AUTHORIZED.

Parameters:

status - The new session status

getStatus

protected APISession.Status getStatus()

Returns the current APISession.Status of the underlying session. This status indicates that...

• APISession.Status.NOT_AUTHORIZED: The session has not yet been initialized. API communication is restricted to login/refresh requests.
• APISession.Status.AUTHORIZATION_IN_PROGRESS: The initialization of this session is currently in progress
• APISession.Status.AUTHORIZED: The session is initialized and ready for further API communication

Returns:

The current status of the underlying session

setLanguage

public void setLanguage(String language)

Set the preferred language used for API communication. If available, search results will returned in this language.

Parameters:

language - The preferred language of the data returned by the remote service

getApiKey

public String getApiKey()

Returns the API key related to this connection

Returns:

API key of this connection

getUserKey

public Optional<String> getUserKey()

Returns the user key related to this connection. If no value is present then this connection only supports authorization via API Key.

Returns:

Optional user key for this connection

getUserName

public Optional<String> getUserName()

Returns the user name related to this connection. If no value is present then this connection only supports authorization via API Key.

Returns:

Optional user name for this connection

getToken

public Optional<String> getToken()

Returns the JWT token that is currently used for Bearer authentication. Might be empty if authorization has not yet been initialized.

Returns:

Current API session token or empty Optional if not yet authorized

userAuthentication

public boolean userAuthentication()

Checks whether user authentication is available or not. A distinct user authentication is optional and only required for specific API calls (USER*).

Returns:

Boolean.TRUE if the underlying session supports user authentication or Boolean.FALSE if not.