Add Missing Interface Doc and Null Checks

Signed-off-by: Sven Strittmatter <sven.strittmatter@iteratec.com>

Author: Weltraumschaf

src/main/java/io/securecodebox/persistence/defectdojo/service/DefectDojoService.java

@@ -5,6 +5,7 @@
 
 import com.fasterxml.jackson.core.JsonProcessingException;
 import io.securecodebox.persistence.defectdojo.model.Model;
+import lombok.NonNull;
 
 import java.net.URISyntaxException;
 import java.util.List;
@@ -13,21 +14,93 @@
 
 /**
  * Basic CRUD interface for DefectDojo REST API
+ *
+ * @param <T> Type of model the implementation deals with
  */
 public interface DefectDojoService<T extends Model> {
+  /**
+   * Get a single model object by its id from DefectDojo
+   * <p>
+   * TODO: Use Optional here instead of null as return value
+   *
+   * @param id must not be less than 1
+   * @return maybe {@code null}
+   */
   T get(long id);
 
-  List<T> search(Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException;
+  /**
+   * Search for model objects by query parameters (name value pairs) in DefectDojo
+   *
+   * @param queryParams not {@code null}
+   * @return not {@code null}, maybe empty
+   * @throws URISyntaxException
+   * @throws JsonProcessingException
+   */
+  List<T> search(@NonNull Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException;
 
+  /**
+   * Get list of all model objects in DefectDojo
+   *
+   * @return never {@code null}, maybe empty
+   * @throws URISyntaxException
+   * @throws JsonProcessingException
+   */
   List<T> search() throws URISyntaxException, JsonProcessingException;
 
-  Optional<T> searchUnique(T searchObject) throws URISyntaxException, JsonProcessingException;
+  /**
+   * Search for a single model object in DefectDojo
+   * <p>
+   * If multiple objects were found the first one will be returned.
+   * </p>
+   *
+   * @param searchObject not {@code null}
+   * @return never {@code null}
+   * @throws URISyntaxException
+   * @throws JsonProcessingException
+   */
+  Optional<T> searchUnique(@NonNull T searchObject) throws URISyntaxException, JsonProcessingException;
 
-  Optional<T> searchUnique(Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException;
+  /**
+   * Search for a single model object in DefectDojo
+   * <p>
+   * If multiple objects were found the first one will be returned.
+   * </p>
+   *
+   * @param queryParams not {@code null}
+   * @return never {@code null}
+   * @throws URISyntaxException
+   * @throws JsonProcessingException
+   */
+  Optional<T> searchUnique(@NonNull Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException;
 
-  T create(T object);
+  /**
+   * Create the given model object in DefectDojo
+   * <p>
+   * Use the returned object for further processing because DefectDojo may alter it (e.g. the id).
+   * </p>
+   *
+   * @param object not {@code null}
+   * @return never {@code null}
+   */
+  T create(@NonNull T object);
 
+  /**
+   * Delete the given model object in DefectDojo identified by its id
+   *
+   * @param id must not be less than 1
+   */
   void delete(long id);
 
-  T update(T object, long objectId);
+  /**
+   * Update the given model object in DefectDojo identified by its id
+   *
+   * <p>
+   * Use the returned object for further processing because DefectDojo may alter it (e.g. the id).
+   * </p>
+   *
+   * @param object not {@code null}
+   * @param id     must not be less than 1
+   * @return never {@code null}
+   */
+  T update(@NonNull T object, long id);
 }

src/main/java/io/securecodebox/persistence/defectdojo/service/GenericDefectDojoService.java

@@ -84,7 +84,7 @@ public final T get(long id) {
   }
 
   @Override
-  public final List<T> search(Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException {
+  public final List<T> search(@NonNull Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException {
     List<T> objects = new LinkedList<>();
 
     boolean hasNext;
@@ -120,7 +120,7 @@ public final Optional<T> searchUnique(T searchObject) throws URISyntaxException,
   }
 
   @Override
-  public final Optional<T> searchUnique(Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException {
+  public final Optional<T> searchUnique(@NonNull Map<String, Object> queryParams) throws URISyntaxException, JsonProcessingException {
     var objects = search(queryParams);
 
     return objects.stream()
@@ -129,7 +129,7 @@ public final Optional<T> searchUnique(Map<String, Object> queryParams) throws UR
   }
 
   @Override
-  public final T create(T object) {
+  public final T create(@NonNull T object) {
     var restTemplate = this.getRestTemplate();
     HttpEntity<T> payload = new HttpEntity<>(object, getDefectDojoAuthorizationHeaders());
 
@@ -146,11 +146,11 @@ public final void delete(long id) {
   }
 
   @Override
-  public final T update(T object, long objectId) {
+  public final T update(@NonNull T object, long id) {
     var restTemplate = this.getRestTemplate();
     HttpEntity<T> payload = new HttpEntity<>(object, getDefectDojoAuthorizationHeaders());
 
-    ResponseEntity<T> response = restTemplate.exchange(this.config.getUrl() + API_PREFIX + getUrlPath() + "/" + objectId + "/", HttpMethod.PUT, payload, getModelClass());
+    ResponseEntity<T> response = restTemplate.exchange(this.config.getUrl() + API_PREFIX + getUrlPath() + "/" + id + "/", HttpMethod.PUT, payload, getModelClass());
     return response.getBody();
   }