TSK-1955: Add javadoc for two SPIs

This commit is contained in:
ryzheboka 2022-09-12 21:19:27 +02:00 committed by Elena Mokeeva
parent 084dc2b99b
commit 316c173663
3 changed files with 65 additions and 11 deletions

View File

@ -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}

View File

@ -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);
}

View File

@ -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);
}