Allow clients to provide an existing JWT to the API. With this option it is possible to create multiple API instances which share the same JWT token. Reduced access level for some methods and constructors based on their current usage.

Author: m0nk3y2k4

src/main/java/com/github/m0nk3y2k4/thetvdb/api/TheTVDBApi.java

@@ -8,6 +8,7 @@
 import javax.annotation.Nonnull;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 
 public interface TheTVDBApi {
 
@@ -20,6 +21,27 @@ public interface TheTVDBApi {
      */
     void init() throws APIException;
 
+    /**
+     * 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 <i>"{header}.{payload}.{signature}"</i>.
+     * <p/>
+     * 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.
+     *
+     * @param 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
+     */
+    void init(@Nonnull String token) throws APIException;
+
+    /**
+     * 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 <i>Optional</i> instance will be returned.
+     *
+     * @return The JWT used by this API or an empty <i>Optional</i> if the API has not been initialized
+     */
+    Optional<String> getToken();
+
     /**
      * 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 <b>"en"</b>. For a list

src/main/java/com/github/m0nk3y2k4/thetvdb/internal/api/impl/TheTVDBApiImpl.java

@@ -2,6 +2,7 @@
 
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 
 import javax.annotation.Nonnull;
 
@@ -81,6 +82,16 @@ public void init() throws APIException {
         this.login();
     }
 
+    @Override
+    public void init(@Nonnull String token) throws APIException {
+        con.setToken(token);
+    }
+
+    @Override
+    public Optional<String> getToken() {
+        return con.getToken();
+    }
+
     @Override
     public void setLanguage(String languageCode) {
         con.setLanguage(languageCode);

src/main/java/com/github/m0nk3y2k4/thetvdb/internal/connection/APIConnection.java

@@ -64,6 +64,18 @@ public JsonNode sendPUT(@Nonnull String resource) throws APIException {
         return sendRequest(new PutRequest(resource));
     }
 
+    public void setToken(@Nonnull String token) throws APIException {
+        session.setToken(token);
+    }
+
+    public void setStatus(Status status) {
+        session.setStatus(status);
+    }
+
+    public void setLanguage(String language) {
+        session.setLanguage(language);
+    }
+
     public String getApiKey() {
         return session.getApiKey();
     }
@@ -76,20 +88,12 @@ public Optional<String> getUserName() {
         return session.getUserName();
     }
 
-    public boolean userAuthentication() {
-        return session.userAuthentication();
+    public Optional<String> getToken() {
+        return session.getToken();
     }
 
-    public void setStatus(Status status) {
-        session.setStatus(status);
-    }
-
-    public void setToken(String token) {
-        session.setToken(token);
-    }
-
-    public void setLanguage(String language) {
-        this.session.setLanguage(language);
+    public boolean userAuthentication() {
+        return session.userAuthentication();
     }
 
     private synchronized JsonNode sendRequest(APIRequest request) throws APIException {
@@ -110,10 +114,8 @@ private synchronized JsonNode sendRequest(APIRequest request) throws APIExceptio
     private void authorizeSession() throws APIException {
         switch (session.getStatus()) {
             case NOT_AUTHORIZED:
-                AuthenticationAPI.login(this);              // Request a new token
-                break;
             case AUTHORIZED:
-                AuthenticationAPI.refreshSession(this);     // Refresh the existing token
+                AuthenticationAPI.login(this);              // Not yet authorized or authorization expired: Request a new token
                 break;
             default:
                 // Authorization is already in progress but could not be completed. Do not retry to authorize this session
@@ -151,7 +153,7 @@ abstract class APIRequest {
         this.resource = resource;
     }
 
-    public void setSession(@Nonnull APISession session) {
+    void setSession(@Nonnull APISession session) {
         this.session = session;
     }
 
@@ -167,7 +169,7 @@ void openConnection(@Nonnull String resource, @Nonnull String requestMethod) thr
         con.setRequestProperty("User-Agent", USER_AGENT);
         if (session != null && session.isInitialized()) {
             // If session has already been initialized, add token information and language key to each request
-            con.setRequestProperty("Authorization", "Bearer " + session.getToken());
+            con.setRequestProperty("Authorization", "Bearer " + session.getToken().get());
             con.setRequestProperty("Accept-Language", session.getLanguage());
         }
     }
@@ -212,20 +214,20 @@ private String getError() throws IOException {
         return parseResponse(con.getErrorStream()).get(API_ERROR).asText("");
     }
 
-    public abstract JsonNode send() throws APIException;
+    abstract JsonNode send() throws APIException;
 }
 
 final class GetRequest extends APIRequest {
 
     /** Messages for error/exception handling */
     private static final String ERR_GET = "An exception occurred while sending GET request to API";
 
-    public GetRequest(@Nonnull String resource) {
+    GetRequest(@Nonnull String resource) {
         super(resource);
     }
 
     @Override
-    public JsonNode send() throws APIException {
+    JsonNode send() throws APIException {
         try {
             openConnection(resource, "GET");
 
@@ -244,13 +246,13 @@ final class PostRequest extends APIRequest {
 
     private final String data;
 
-    public PostRequest(@Nonnull String resource, @Nonnull String data) {
+    PostRequest(@Nonnull String resource, @Nonnull String data) {
         super(resource);
         this.data = data;
     }
 
     @Override
-    public JsonNode send() throws APIException {
+    JsonNode send() throws APIException {
         try {
             openConnection(resource, "POST");
 
@@ -279,12 +281,12 @@ final class HeadRequest extends APIRequest {
     /** Messages for error/exception handling */
     private static final String ERR_HEAD = "An exception occurred while sending HEAD request to API";
 
-    public HeadRequest(@Nonnull String resource) {
+    HeadRequest(@Nonnull String resource) {
         super(resource);
     }
 
     @Override
-    public JsonNode send() throws APIException {
+    JsonNode send() throws APIException {
         try {
             openConnection(resource, "HEAD");
 
@@ -327,12 +329,12 @@ final class DeleteRequest extends APIRequest {
         /** Messages for error/exception handling */
         private static final String ERR_DELETE = "An exception occurred while sending DELETE request to API";
 
-        public DeleteRequest(@Nonnull String resource) {
+        DeleteRequest(@Nonnull String resource) {
             super(resource);
         }
 
         @Override
-        public JsonNode send() throws APIException {
+        JsonNode send() throws APIException {
             try {
                 openConnection(resource, "DELETE");
 
@@ -349,12 +351,12 @@ final class PutRequest extends APIRequest {
     /** Messages for error/exception handling */
     private static final String ERR_PUT = "An exception occurred while sending PUT request to API";
 
-    public PutRequest(@Nonnull String resource) {
+    PutRequest(@Nonnull String resource) {
         super(resource);
     }
 
     @Override
-    public JsonNode send() throws APIException {
+    JsonNode send() throws APIException {
         try {
             openConnection(resource, "PUT");
 

src/main/java/com/github/m0nk3y2k4/thetvdb/internal/connection/APISession.java

@@ -1,10 +1,12 @@
 package com.github.m0nk3y2k4.thetvdb.internal.connection;
 
+import com.github.m0nk3y2k4.thetvdb.api.exception.APIException;
 import com.github.m0nk3y2k4.thetvdb.internal.util.APIUtil;
 
 import javax.annotation.Nonnull;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.regex.Pattern;
 
 /**
  * Session used for remote API communication. All connections to the TheTVDB API are backed by an instance of this class. These sessions
@@ -13,6 +15,13 @@
  */
 public final class APISession {
 
+    /** Pattern for JSON Web Token validation */
+    private static final Pattern JWT_PATTERN = Pattern.compile("^[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*$");
+
+    /** Error messages */
+    private static final String ERR_JWT_EMPTY = "Remote API authorization failed: Token must not be NULL or empty";
+    private static final String ERR_JWT_INVALID = "Remote API authorization failed: Invalid token format [%s]";
+
     /**
      * Represents the different states of a session. By default, sessions are not authorized for general API communication. Only
      * login/refresh requests may be allowed. During the execution of these kind of requests, the session authorization is in progress.
@@ -52,7 +61,7 @@ public enum Status {NOT_AUTHORIZED, AUTHORIZATION_IN_PROGRESS, AUTHORIZED}
      *
      * @param apiKey The API key used to request a session token
      */
-    public APISession(@Nonnull String apiKey) {
+    APISession(@Nonnull String apiKey) {
         Objects.requireNonNull(apiKey, "API key must not be NULL or empty!");
 
         this.apiKey = apiKey;
@@ -71,7 +80,7 @@ public APISession(@Nonnull String apiKey) {
      * @param userKey User key for authentication (also referred to as "Unique ID")
      * @param userName User name for authentication
      */
-    public APISession(@Nonnull String apiKey, @Nonnull String userKey, @Nonnull String userName) {
+    APISession(@Nonnull String apiKey, @Nonnull String userKey, @Nonnull String userName) {
         Objects.requireNonNull(apiKey, "API key must not be NULL or empty!");
         Objects.requireNonNull(userKey, "User key must not be NULL or empty!");
         Objects.requireNonNull(userName, "User name must not be NULL or empty!");
@@ -86,7 +95,7 @@ public APISession(@Nonnull String apiKey, @Nonnull String userKey, @Nonnull Stri
      *
      * @return API key of the session
      */
-    public String getApiKey() {
+    String getApiKey() {
         return this.apiKey;
     }
 
@@ -95,7 +104,7 @@ public String getApiKey() {
      *
      * @return The user key
      */
-    public Optional<String> getUserKey() {
+    Optional<String> getUserKey() {
         return Optional.ofNullable(userKey);
     }
 
@@ -104,36 +113,38 @@ public Optional<String> getUserKey() {
      *
      * @return The user name
      */
-    public Optional<String> getUserName() {
+    Optional<String> getUserName() {
         return Optional.ofNullable(userName);
     }
 
     /**
-     * Sets the token of this session
+     * Returns the current session token. Might be empty if the session has not yet been initialized.
      *
-     * @param token The new session token
+     * @return Current API session token
      */
-    public void setToken(@Nonnull String token) {
-        Objects.requireNonNull(token, "Token must not be NULL or empty!");
-
-        this.token = token;
+    Optional<String> getToken() {
+        return Optional.ofNullable(token);
     }
 
     /**
-     * Returns the current session token
+     * Sets the token of this session
      *
-     * @return Current API session token
+     * @param token The new session token
      */
-    public String getToken() {
-        return token;
+    void setToken(@Nonnull String token) throws APIException {
+        // Validate token - throws an exception if not a valid JWT
+        validateJWT(token);
+
+        this.token = token;
+        this.status = Status.AUTHORIZED;
     }
 
     /**
      * Set the preferred language used for API communication. Search results will be based on this language.
      *
      * @param language The language for API communication
      */
-    public void setLanguage(String language) {
+    void setLanguage(String language) {
         this.language = language;
     }
 
@@ -142,7 +153,7 @@ public void setLanguage(String language) {
      *
      * @return The language used for API communication
      */
-    public String getLanguage() {
+    String getLanguage() {
         return language;
     }
 
@@ -151,7 +162,7 @@ public String getLanguage() {
      *
      * @param status The new session status
      */
-    public void setStatus(Status status) { this.status = status; }
+    void setStatus(Status status) { this.status = status; }
     /**
      * Returns the current {@link Status} of this session. This status indicates that...
      * <p/>
@@ -161,14 +172,14 @@ public String getLanguage() {
      *
      * @return The current status of this session
      */
-    public Status getStatus() { return status; }
+    Status getStatus() { return status; }
 
     /**
      * Check if this session has already been initialized
      *
      * @return {@link Boolean#TRUE} if the session is initialized or {@link Boolean#FALSE} if the session is not yet initialized.
      */
-    public Boolean isInitialized() {
+    Boolean isInitialized() {
         return getStatus() == Status.AUTHORIZED;
     }
 
@@ -177,7 +188,24 @@ public Boolean isInitialized() {
      *
      * @return {@link Boolean#TRUE} if both, userKey and userName are not empty or {@link Boolean#FALSE} if not.
      */
-    public Boolean userAuthentication() {
+    Boolean userAuthentication() {
         return APIUtil.hasValue(userKey) && APIUtil.hasValue(userName);
     }
+
+    /**
+     * Checks if the given token is a valid JSON Web Token
+     *
+     * @param token The token to check
+     *
+     * @throws APIException If the given token is <code>null</code>, an empty character sequence or does not match the regular JWT format
+     */
+    private static void validateJWT(String token) throws APIException {
+        if (APIUtil.hasNoValue(token)) {
+            throw new APIException(ERR_JWT_EMPTY);
+        }
+
+        if (!JWT_PATTERN.matcher(token).matches()) {
+            throw new APIException(String.format(ERR_JWT_INVALID, token));
+        }
+    }
 }