From 316c17366340f9e74ccbad9929db1d69a2166e43 Mon Sep 17 00:00:00 2001
From: ryzheboka <25465835+ryzheboka@users.noreply.github.com>
Date: Mon, 12 Sep 2022 21:19:27 +0200
Subject: [PATCH] TSK-1955: Add javadoc for two SPIs

---
 .../priority/api/PriorityServiceProvider.java | 17 ++++++--
 .../spi/routing/api/TaskRoutingProvider.java  | 42 ++++++++++++++++---
 .../spi/task/api/CreateTaskPreprocessor.java  | 17 +++++++-
 3 files changed, 65 insertions(+), 11 deletions(-)

diff --git a/lib/taskana-core/src/main/java/pro/taskana/spi/priority/api/PriorityServiceProvider.java b/lib/taskana-core/src/main/java/pro/taskana/spi/priority/api/PriorityServiceProvider.java
index c01c8493c..dddff1388 100644
--- a/lib/taskana-core/src/main/java/pro/taskana/spi/priority/api/PriorityServiceProvider.java
+++ b/lib/taskana-core/src/main/java/pro/taskana/spi/priority/api/PriorityServiceProvider.java
@@ -6,17 +6,28 @@ import pro.taskana.task.api.models.Task;
 import pro.taskana.task.api.models.TaskSummary;
 
 /**
- * This SPI enables the computation of {@linkplain Task} priorities depending on individual
- * preferences.
+ * The PriorityServiceProvider allows to determine the priority of a {@linkplain Task} according to
+ * custom logic.
  */
 public interface PriorityServiceProvider {
 
   /**
-   * Calculates the {@linkplain Task#getPriority() priority} of a certain {@linkplain Task}.
+   * Determine the {@linkplain Task#getPriority() priority} of a certain {@linkplain Task} during
+   * execution of {@linkplain pro.taskana.task.api.TaskService#createTask(Task)} and {@linkplain
+   * pro.taskana.task.api.TaskService#updateTask(Task)}. This priority overwrites the priority from
+   * Classification-driven logic.
    *
    * <p>The implemented method must calculate the {@linkplain Task#getPriority() priority}
    * efficiently. There can be a huge amount of {@linkplain Task Tasks} the SPI has to handle.
    *
+   * <p>The behaviour is undefined if this method tries to apply persistent changes to any entity.
+   *
+   * <p>This SPI is executed with the same {@linkplain
+   * pro.taskana.common.api.security.UserPrincipal} and {@linkplain
+   * pro.taskana.common.api.security.GroupPrincipal} as in {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task)} or {@linkplain
+   * pro.taskana.task.api.TaskService#updateTask(Task)}.
+   *
    * @param taskSummary the {@linkplain TaskSummary} to compute the {@linkplain Task#getPriority()
    *     priority} for
    * @return the computed {@linkplain Task#getPriority() priority}
diff --git a/lib/taskana-core/src/main/java/pro/taskana/spi/routing/api/TaskRoutingProvider.java b/lib/taskana-core/src/main/java/pro/taskana/spi/routing/api/TaskRoutingProvider.java
index ef4340c37..c328a3c3f 100644
--- a/lib/taskana-core/src/main/java/pro/taskana/spi/routing/api/TaskRoutingProvider.java
+++ b/lib/taskana-core/src/main/java/pro/taskana/spi/routing/api/TaskRoutingProvider.java
@@ -2,22 +2,52 @@ package pro.taskana.spi.routing.api;
 
 import pro.taskana.common.api.TaskanaEngine;
 import pro.taskana.task.api.models.Task;
+import pro.taskana.workbasket.api.models.Workbasket;
 
-/** Interface for TASKANA TaskRoutingProvider SPI. */
+/**
+ * The TaskRoutingProvider allows to determine the {@linkplain Workbasket} for a {@linkplain Task}
+ * that has no {@linkplain Workbasket} on {@linkplain
+ * pro.taskana.task.api.TaskService#createTask(Task) creation}.
+ */
 public interface TaskRoutingProvider {
 
   /**
-   * Initialize TaskRoutingProvider service.
+   * Provide the active {@linkplain TaskanaEngine} which is initialized for this TASKANA
+   * installation.
    *
-   * @param taskanaEngine {@linkplain TaskanaEngine} The Taskana engine needed for initialization.
+   * <p>This method is called during TASKANA startup and allows the service provider to store the
+   * active {@linkplain TaskanaEngine} for later usage.
+   *
+   * @param taskanaEngine the active {@linkplain TaskanaEngine} which is initialized for this
+   *     installation
    */
   void initialize(TaskanaEngine taskanaEngine);
 
   /**
-   * Determines a WorkbasketId for a given task.
+   * Determine the {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket} for a given
+   * {@linkplain Task}.This method will be invoked by TASKANA when it is asked to {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task) create} a {@linkplain Task} that has no
+   * {@linkplain Workbasket} assigned.
    *
-   * @param task {@linkplain Task} The task for which a workbasket must be determined.
-   * @return the id of the workbasket in which the task is to be created.
+   * <p>If more than one TaskRoutingProvider class is registered, TASKANA calls them all and uses
+   * their results only if they agree on the {@linkplain Workbasket}. This is, if more than one
+   * {@linkplain Workbasket#getId() ids} are returned, TASKANA uses them only if they are identical.
+   * If different ids are returned, the {@linkplain Task} will not be {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task) created}.
+   *
+   * <p>If the {@linkplain Workbasket} cannot be computed, the method should return NULL. If every
+   * registered TaskRoutingProvider return NULL, the {@linkplain Task} will not be {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task) created}
+   *
+   * <p>The behaviour is undefined if this method tries to apply persistent changes to any entity.
+   *
+   * <p>This SPI is executed with the same {@linkplain
+   * pro.taskana.common.api.security.UserPrincipal} and {@linkplain
+   * pro.taskana.common.api.security.GroupPrincipal} as in {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task)}.
+   *
+   * @param task the {@linkplain Task} for which a {@linkplain Workbasket} must be determined
+   * @return the {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket}
    */
   String determineWorkbasketId(Task task);
 }
diff --git a/lib/taskana-core/src/main/java/pro/taskana/spi/task/api/CreateTaskPreprocessor.java b/lib/taskana-core/src/main/java/pro/taskana/spi/task/api/CreateTaskPreprocessor.java
index e4c0ee23c..0a7c7cde0 100644
--- a/lib/taskana-core/src/main/java/pro/taskana/spi/task/api/CreateTaskPreprocessor.java
+++ b/lib/taskana-core/src/main/java/pro/taskana/spi/task/api/CreateTaskPreprocessor.java
@@ -2,12 +2,25 @@ package pro.taskana.spi.task.api;
 
 import pro.taskana.task.api.models.Task;
 
+/**
+ * The CreateTaskPreprocessor allows to implement customized behaviour before the given {@linkplain
+ * Task} has been created.
+ */
 public interface CreateTaskPreprocessor {
 
   /**
-   * Processes a {@linkplain Task} before its creation.
+   * Perform any action before a {@linkplain Task} has been created through {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task)}.
    *
-   * @param taskToProcess {@linkplain Task} The Task to preprocess.
+   * <p>This SPI is executed within the same transaction staple as {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task)}.
+   *
+   * <p>This SPI is executed with the same {@linkplain
+   * pro.taskana.common.api.security.UserPrincipal} and {@linkplain
+   * pro.taskana.common.api.security.GroupPrincipal} as in {@linkplain
+   * pro.taskana.task.api.TaskService#createTask(Task)}.
+   *
+   * @param taskToProcess the {@linkplain Task} to preprocess
    */
   void processTaskBeforeCreation(Task taskToProcess);
 }