Extended parameter validation and FindBugs annotations. Validation issues will now be handled as RuntimeException.

Author: m0nk3y2k4

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

@@ -39,7 +39,7 @@ public interface QueryParameters extends Iterable<QueryParameters.Parameter> {
      *
      * @return Optional containing the current value for the given key or {@link Optional#empty()} if no parameter with this key exists
      */
-    Optional<String> getParameterValue(String key);
+    Optional<String> getParameterValue(@Nonnull String key);
 
     /**
      * Returns <code>true</code> if an individual parameter with the given key exists in this very object or <code>false</code> if no such parameter has been added yet.
@@ -48,7 +48,7 @@ public interface QueryParameters extends Iterable<QueryParameters.Parameter> {
      *
      * @return <code>True</code> if a parameter with the given key has already been added to this object or <code>false</code> if not
      */
-    boolean containsParameter(String key);
+    boolean containsParameter(@Nonnull String key);
 
     /**
      * Returns a Stream of individual query parameters hold by this class.

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

@@ -399,15 +399,15 @@ public interface TheTVDBApi {
 
     List<Image> queryImages(long seriesId, QueryParameters queryParameters) throws APIException;
 
-    List<Image> queryImages(long seriesId, String keyType, String resolution) throws APIException;
+    List<Image> queryImages(long seriesId, @Nonnull String keyType, @Nonnull String resolution) throws APIException;
 
-    List<Image> queryImages(long seriesId, String keyType, String resolution, String subKey) throws APIException;
+    List<Image> queryImages(long seriesId, @Nonnull String keyType, @Nonnull String resolution, @Nonnull String subKey) throws APIException;
 
-    List<Image> queryImagesByKeyType(long seriesId, String keyType) throws APIException;
+    List<Image> queryImagesByKeyType(long seriesId, @Nonnull String keyType) throws APIException;
 
-    List<Image> queryImagesByResolution(long seriesId, String resolution) throws APIException;
+    List<Image> queryImagesByResolution(long seriesId, @Nonnull String resolution) throws APIException;
 
-    List<Image> queryImagesBySubKey(long seriesId, String subKey) throws APIException;
+    List<Image> queryImagesBySubKey(long seriesId, @Nonnull String subKey) throws APIException;
 
     List<ImageQueryParameter> getAvailableImageQueryParameters(long seriesId) throws APIException;
 
@@ -851,6 +851,8 @@ interface Extended {
 
         APIResponse<List<String>> getAvailableRatingsQueryParameters() throws APIException;
 
+        void deleteFromRatings(@Nonnull String itemType, long itemId) throws APIException;
+
         APIResponse<List<Rating>> addToRatings(@Nonnull String itemType, long itemId, long itemRating) throws APIException;
     }
 }

src/main/java/com/github/m0nk3y2k4/thetvdb/api/exception/APIException.java

@@ -4,10 +4,10 @@
 
 public class APIException extends Exception {
 
-    public static final String API_NOT_AUTHORIZED_ERROR = "Missing authorization or expired JWT token (HTTP-401). Original API error message: %s";
+    protected static final String API_NOT_AUTHORIZED_ERROR = "Missing authorization or expired JWT token (HTTP-401). Original API error message: %s";
+
     public static final String API_NOT_FOUND_ERROR = "Requested resource could not be found (HTTP-404). Original API error message: %s";
     public static final String API_CONFLICT_ERROR = "Update request caused a conflict (HTTP-409). Original API error message: %s";
-    public static final String API_VALIDATION_ERROR = "Request could not be processed due to invalid/missing parameters: %s";
     public static final String API_SERVICE_UNAVAILABLE = "API Service is currently unavailable. Please try again later.";
     public static final String API_JSON_PARSE_ERROR = "Error while parsing JSON from response";
 

src/main/java/com/github/m0nk3y2k4/thetvdb/api/exception/APIRuntimeException.java

@@ -1,7 +1,19 @@
 package com.github.m0nk3y2k4.thetvdb.api.exception;
 
+import javax.annotation.Nonnull;
+
 public class APIRuntimeException extends RuntimeException {
 
+    protected static final String API_VALIDATION_ERROR = "Request could not be processed due to invalid/missing parameters: %s";
+
+    public APIRuntimeException(String message) {
+        super(message);
+    }
+
+    public APIRuntimeException(@Nonnull String message, @Nonnull String details) {
+        super(String.format(message, details));
+    }
+
     public APIRuntimeException(String message, Exception ex) {
         super(message, ex);
     }

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

@@ -1,8 +1,10 @@
 package com.github.m0nk3y2k4.thetvdb.internal.api.impl;
 
 import com.github.m0nk3y2k4.thetvdb.api.QueryParameters;
+import com.github.m0nk3y2k4.thetvdb.internal.resource.validation.ObjectValidator;
 
 import javax.annotation.Nonnull;
+
 import java.util.*;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
@@ -31,25 +33,27 @@ public class QueryParametersImpl implements QueryParameters {
     public QueryParametersImpl(@Nonnull Map<String, String> parameters) {
         super();
 
-        Objects.requireNonNull(parameters, "Parameters map must not be NULL");
+        ObjectValidator.requireNonNull(parameters, "Parameters map must not be NULL");
 
         parameters.forEach(this::addParameter);
     }
 
     @Override
     public QueryParameters addParameter(@Nonnull String key, @Nonnull String value) {
-        Objects.requireNonNull(key, "Parameter key must not be NULL");
-        Objects.requireNonNull(value, "Parameter value must not be NULL");
+        ObjectValidator.requireNonNull(key, "Parameter key must not be NULL");
+        ObjectValidator.requireNonNull(value, "Parameter value must not be NULL");
 
         params.put(key, value);
         return this;
     }
 
     @Override
-    public Optional<String> getParameterValue(String key) { return Optional.ofNullable(params.get(key)); }
+    public Optional<String> getParameterValue(@Nonnull String key) {
+        return Optional.ofNullable(params.get(key));
+    }
 
     @Override
-    public boolean containsParameter(String key) {
+    public boolean containsParameter(@Nonnull String key) {
         return params.containsKey(key);
     }
 

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

@@ -242,31 +242,31 @@ public List<Image> queryImages(long seriesId, QueryParameters queryParameters) t
     }
 
     @Override
-    public List<Image> queryImages(long seriesId, String keyType, String resolution) throws APIException {
+    public List<Image> queryImages(long seriesId, @Nonnull String keyType, @Nonnull String resolution) throws APIException {
         validateNotEmpty(keyType, resolution);
         return queryImages(seriesId, query(Map.of(Query.Series.KEYTYPE, keyType, Query.Series.RESOLUTION, resolution)));
     }
 
     @Override
-    public List<Image> queryImages(long seriesId, String keyType, String resolution, String subKey) throws APIException {
+    public List<Image> queryImages(long seriesId, @Nonnull String keyType, @Nonnull String resolution, @Nonnull String subKey) throws APIException {
         validateNotEmpty(keyType, resolution, subKey);
         return queryImages(seriesId, query(Map.of(Query.Series.KEYTYPE, keyType, Query.Series.RESOLUTION, resolution, Query.Series.SUBKEY, subKey)));
     }
 
     @Override
-    public List<Image> queryImagesByKeyType(long seriesId, String keyType) throws APIException {
+    public List<Image> queryImagesByKeyType(long seriesId, @Nonnull String keyType) throws APIException {
         validateNotEmpty(keyType);
         return queryImages(seriesId, query(Map.of(Query.Series.KEYTYPE, keyType)));
     }
 
     @Override
-    public List<Image> queryImagesByResolution(long seriesId, String resolution) throws APIException {
+    public List<Image> queryImagesByResolution(long seriesId, @Nonnull String resolution) throws APIException {
         validateNotEmpty(resolution);
         return queryImages(seriesId, query(Map.of(Query.Series.RESOLUTION, resolution)));
     }
 
     @Override
-    public List<Image> queryImagesBySubKey(long seriesId, String subKey) throws APIException {
+    public List<Image> queryImagesBySubKey(long seriesId, @Nonnull String subKey) throws APIException {
         validateNotEmpty(subKey);
         return queryImages(seriesId, query(Map.of(Query.Series.SUBKEY, subKey)));
     }
@@ -341,7 +341,7 @@ public List<String> getAvailableRatingsQueryParameters() throws APIException {
 
     @Override
     public void deleteFromRatings(@Nonnull String itemType, long itemId) throws APIException {
-        json().deleteFromRatings(itemType, itemId);
+        extended().deleteFromRatings(itemType, itemId);
     }
 
     @Override
@@ -644,6 +644,11 @@ public APIResponse<List<String>> getAvailableRatingsQueryParameters() throws API
             return JsonDeserializer.mapQueryParameters(json().getAvailableRatingsQueryParameters());
         }
 
+        @Override
+        public void deleteFromRatings(@Nonnull String itemType, long itemId) throws APIException {
+            json().deleteFromRatings(itemType, itemId);
+        }
+
         @Override
         public APIResponse<List<Rating>> addToRatings(@Nonnull String itemType, long itemId, long itemRating) throws APIException {
             return JsonDeserializer.mapRatings(json().addToRatings(itemType, itemId, itemRating));

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

@@ -27,6 +27,7 @@
 import com.github.m0nk3y2k4.thetvdb.api.exception.APIException;
 import com.github.m0nk3y2k4.thetvdb.internal.exception.APINotAuthorizedException;
 import com.github.m0nk3y2k4.thetvdb.internal.resource.impl.AuthenticationAPI;
+import com.github.m0nk3y2k4.thetvdb.internal.resource.validation.ConnectionValidator;
 
 public class APIConnection {
 
@@ -158,10 +159,13 @@ void setSession(@Nonnull APISession session) {
     }
 
     void openConnection(@Nonnull String resource, @Nonnull String requestMethod) throws IOException {
+        ConnectionValidator.validateResource(resource);
+        ConnectionValidator.validateRequestMethod(requestMethod);
+
         con = (HttpsURLConnection) new URL(API_URL + resource).openConnection();
 
-        // POST or GET
-        con.setRequestMethod(requestMethod);
+        // POST, GET, DELETE, PUT,...
+        con.setRequestMethod(requestMethod.toUpperCase());
 
         // Request properties for API
         con.setRequestProperty("Content-Type", "application/json; charset=utf-8");
@@ -241,6 +245,7 @@ JsonNode send() throws APIException {
 }
 
 final class PostRequest extends APIRequest {
+
     /** Messages for error/exception handling */
     private static final String ERR_POST = "An exception occurred while sending POST request to API";
 
@@ -268,6 +273,8 @@ JsonNode send() throws APIException {
     }
 
     private void writeRequestBody(@Nonnull String data) throws IOException {
+        ConnectionValidator.validatePayload(data);
+
         con.setDoOutput(true);
 
         try (OutputStream os = con.getOutputStream()) {
@@ -278,6 +285,7 @@ private void writeRequestBody(@Nonnull String data) throws IOException {
 }
 
 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";
 
@@ -326,6 +334,7 @@ private JsonNode createJsonFromHeaderFields() {
 }
 
 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";
 
@@ -348,6 +357,7 @@ JsonNode send() throws APIException {
 }
 
 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";
 

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

@@ -1,10 +1,10 @@
 package com.github.m0nk3y2k4.thetvdb.internal.connection;
 
 import com.github.m0nk3y2k4.thetvdb.api.exception.APIException;
+import com.github.m0nk3y2k4.thetvdb.internal.resource.validation.ObjectValidator;
 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;
 
@@ -27,7 +27,16 @@ public final class APISession {
      * login/refresh requests may be allowed. During the execution of these kind of requests, the session authorization is in progress.
      * In case the login/refresh were successful the session is authorized and ready for general API communication.
      */
-    public enum Status {NOT_AUTHORIZED, AUTHORIZATION_IN_PROGRESS, AUTHORIZED}
+    public enum Status {
+        /** Session authorization is pending */
+        NOT_AUTHORIZED,
+
+        /** Session authorization is currently in progress */
+        AUTHORIZATION_IN_PROGRESS,
+
+        /** Session authorization completed successfully */
+        AUTHORIZED
+    }
 
     /** Accept english by default if no language was specified */
     private static final String DEFAULT_LANGUAGE = "en";
@@ -62,7 +71,7 @@ public enum Status {NOT_AUTHORIZED, AUTHORIZATION_IN_PROGRESS, AUTHORIZED}
      * @param apiKey The API key used to request a session token
      */
     APISession(@Nonnull String apiKey) {
-        Objects.requireNonNull(apiKey, "API key must not be NULL or empty!");
+        ObjectValidator.requireNonEmpty(apiKey, "API key must not be NULL or empty!");
 
         this.apiKey = apiKey;
         this.userKey = null;
@@ -81,9 +90,9 @@ public enum Status {NOT_AUTHORIZED, AUTHORIZATION_IN_PROGRESS, AUTHORIZED}
      * @param userName User name for authentication
      */
     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!");
+        ObjectValidator.requireNonEmpty(apiKey, "API key must not be NULL or empty!");
+        ObjectValidator.requireNonEmpty(userKey, "User key must not be NULL or empty!");
+        ObjectValidator.requireNonEmpty(userName, "User name must not be NULL or empty!");
 
         this.apiKey = apiKey;
         this.userKey = userKey;
@@ -140,12 +149,13 @@ void setToken(@Nonnull String token) throws APIException {
     }
 
     /**
-     * Set the preferred language used for API communication. Search results will be based on this language.
+     * Set the preferred language used for API communication. Search results will be based on this language. If the given
+     * language parameter is <code>Null</code> the sessions language will be reset to {@link #DEFAULT_LANGUAGE}.
      *
      * @param language The language for API communication
      */
     void setLanguage(String language) {
-        this.language = language;
+        this.language = language != null ? language : DEFAULT_LANGUAGE;
     }
 
     /**
@@ -158,11 +168,14 @@ String getLanguage() {
     }
 
     /**
-     * Sets the current status of this session
+     * Sets the current status of this session. If the given status parameter is <code>Null</code> the sessions
+     * status will be reset to {@link Status#NOT_AUTHORIZED}.
      *
      * @param status The new session status
      */
-    void setStatus(Status status) { this.status = status; }
+    void setStatus(Status status) {
+        this.status = status != null ? status : Status.NOT_AUTHORIZED;
+    }
     /**
      * Returns the current {@link Status} of this session. This status indicates that...
      * <p/>

src/main/java/com/github/m0nk3y2k4/thetvdb/internal/exception/APIValidationException.java

@@ -1,10 +1,10 @@
 package com.github.m0nk3y2k4.thetvdb.internal.exception;
 
-import com.github.m0nk3y2k4.thetvdb.api.exception.APIException;
+import com.github.m0nk3y2k4.thetvdb.api.exception.APIRuntimeException;
 
 import javax.annotation.Nonnull;
 
-public final class APIValidationException extends APIException {
+public final class APIValidationException extends APIRuntimeException {
 
     public APIValidationException(@Nonnull String error) {
         super(API_VALIDATION_ERROR, error);

src/main/java/com/github/m0nk3y2k4/thetvdb/internal/resource/QueryResource.java

@@ -17,6 +17,14 @@
 
 public abstract class QueryResource extends Resource {
 
+    protected static String createQueryResource(@Nonnull String base, @CheckForNull QueryParameters queryParams) {
+        return base + createQuery(queryParams);
+    }
+
+    protected static String createQueryResource(@Nonnull String base, @Nonnull String specific, @CheckForNull QueryParameters queryParams) {
+        return createResource(base, specific) + createQuery(queryParams);
+    }
+
     private static String createQuery(@CheckForNull QueryParameters queryParams) {
         List<QueryParameters.Parameter> validParams = Optional.ofNullable(queryParams).orElse(TheTVDBApiFactory.createQueryParameters())
                 .stream().filter(QueryResource::isValidQueryParameter).collect(Collectors.toList());
@@ -29,19 +37,11 @@ private static String createQuery(@CheckForNull QueryParameters queryParams) {
         return "";
     }
 
-    protected static String createQueryResource(@Nonnull String base, @CheckForNull QueryParameters queryParams) {
-        return base + createQuery(queryParams);
-    }
-
-    protected static String createQueryResource(@Nonnull String base, @Nonnull String specific, @CheckForNull QueryParameters queryParams) {
-        return createResource(base, specific) + createQuery(queryParams);
-    }
-
-    private static Boolean isValidQueryParameter(QueryParameters.Parameter param) {
+    private static Boolean isValidQueryParameter(@Nonnull QueryParameters.Parameter param) {
         return APIUtil.hasValue(param.getKey(), param.getValue());
     }
 
-    private static String encode(String value) throws APIRuntimeException {
+    private static String encode(@Nonnull String value) throws APIRuntimeException {
         try {
             return URLEncoder.encode(value, Charset.defaultCharset().name());
         } catch (UnsupportedEncodingException ex) {