TSK-1852: refactor JavaDoc in TaskService

This commit is contained in:
ryzheboka 2022-04-20 14:27:30 +02:00 committed by Elena Mokeeva
parent 43ed441daf
commit a2e0681190
1 changed files with 349 additions and 271 deletions

View File

@ -12,7 +12,7 @@ import pro.taskana.common.api.exceptions.ConcurrencyException;
import pro.taskana.common.api.exceptions.InvalidArgumentException;
import pro.taskana.common.api.exceptions.NotAuthorizedException;
import pro.taskana.common.api.exceptions.TaskanaException;
import pro.taskana.common.internal.util.IdGenerator;
import pro.taskana.spi.routing.api.TaskRoutingProvider;
import pro.taskana.task.api.exceptions.AttachmentPersistenceException;
import pro.taskana.task.api.exceptions.InvalidOwnerException;
import pro.taskana.task.api.exceptions.InvalidStateException;
@ -28,20 +28,20 @@ import pro.taskana.workbasket.api.WorkbasketPermission;
import pro.taskana.workbasket.api.exceptions.WorkbasketNotFoundException;
import pro.taskana.workbasket.api.models.Workbasket;
/** The Task Service manages all operations on tasks. */
/** The TaskService manages all operations on {@linkplain Task Tasks}. */
public interface TaskService {
/**
* Claim an existing {@linkplain Task} for the current user.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to be claimed
* @return claimed {@linkplain Task}
* @return the claimed {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
* @throws InvalidStateException if the {@linkplain Task#getState() state} of the {@linkplain
* Task} with taskId is not {@linkplain TaskState#READY READY}
* Task} with taskId isn't {@linkplain TaskState#READY}
* @throws InvalidOwnerException if the {@linkplain Task} with taskId is claimed by some else
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task claim(String taskId)
throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
@ -52,13 +52,13 @@ public interface TaskService {
* someone else.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to be claimed
* @return claimed {@linkplain Task}
* @return the claimed {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
* @throws InvalidStateException if the {@linkplain Task#getState() state} of the {@linkplain
* Task} with taskId is not READY
* Task} with taskId isn't {@linkplain TaskState#READY}
* @throws InvalidOwnerException if the {@linkplain Task} with taskId is claimed by someone else
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task forceClaim(String taskId)
throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
@ -67,14 +67,15 @@ public interface TaskService {
/**
* Cancel the claim of an existing {@linkplain Task} if it was claimed by the current user before.
*
* @param taskId {@linkplain Task#getId() id} of the task which should be unclaimed.
* @return updated unclaimed task
* @throws TaskNotFoundException if the {@linkplain Task} can't be found or does not exist
* @throws InvalidStateException if the {@linkplain Task} is already in an end {@linkplain
* Task#getState() state}.
* @throws InvalidOwnerException if the {@linkplain Task} is claimed by another user.
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the task is in
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* unclaimed
* @return the unclaimed {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
* @throws InvalidStateException if the {@linkplain Task} is already in one of the {@linkplain
* TaskState#END_STATES}
* @throws InvalidOwnerException if the {@linkplain Task} is claimed by another user
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task cancelClaim(String taskId)
throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
@ -83,87 +84,110 @@ public interface TaskService {
/**
* Cancel the claim of an existing {@linkplain Task} even if it was claimed by another user.
*
* @param taskId id of the {@linkplain Task} which should be unclaimed.
* @return updated unclaimed {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} can't be found or does not exist
* @throws InvalidStateException if the {@linkplain Task} is already in an end {@linkplain
* Task#getState() state}
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* unclaimed
* @return the unclaimed {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
* @throws InvalidStateException if the {@linkplain Task} is already in one of the {@linkplain
* TaskState#END_STATES}
* @throws InvalidOwnerException if forceCancel is false and the {@linkplain Task} is claimed by
* another user.
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
* another user
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task forceCancelClaim(String taskId)
throws TaskNotFoundException, InvalidStateException, InvalidOwnerException,
NotAuthorizedException;
/**
* Complete a claimed {@linkplain Task} as owner/admin and update {@linkplain Task#getState()
* state} and Timestamps. If {@linkplain Task} is already completed, the {@linkplain Task} is
* returned as itself.
* Complete a claimed {@linkplain Task} as {@linkplain Task#getOwner() owner} or {@linkplain
* TaskanaRole#ADMIN} and update {@linkplain Task#getState() state} and timestamps.
*
* @param taskId - {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* completed.
* @return Task - updated {@linkplain Task} after completion.
* @throws InvalidStateException if {@linkplain Task} wasn't claimed before.
* @throws TaskNotFoundException if the given {@linkplain Task} can't be found in DB.
* @throws InvalidOwnerException if current user is not the task-owner or administrator.
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
* <p>If the {@linkplain Task} is already completed, the {@linkplain Task} is returned unchanged.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* completed
* @return the completed {@linkplain Task}
* @throws InvalidStateException if the {@linkplain Task#getState() state} of the {@linkplain
* Task} with taskId is neither {@linkplain TaskState#CLAIMED} nor {@linkplain
* TaskState#COMPLETED}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws InvalidOwnerException if current user isn't the {@linkplain Task#getOwner() owner} of
* the {@linkplain Task} or {@linkplain TaskanaRole#ADMIN}
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task completeTask(String taskId)
throws TaskNotFoundException, InvalidOwnerException, InvalidStateException,
NotAuthorizedException;
/**
* Completes a {@linkplain Task} and updates {@linkplain Task#getState() state} and Timestamps in
* every case if the {@linkplain Task} exists. If {@linkplain Task} is already completed, the
* {@linkplain Task} is returned as itself.
* Completes a {@linkplain Task} and updates {@linkplain Task#getState() state} and timestamps in
* every case if the {@linkplain Task} exists.
*
* @param taskId - {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* completed.
* @return Task - updated {@linkplain Task} after completion.
* @throws InvalidStateException if {@linkplain Task} wasn't claimed before.
* @throws TaskNotFoundException if the given {@linkplain Task} can't be found in DB.
* @throws InvalidOwnerException if current user is not the task-owner or administrator.
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
* <p>If the {@linkplain Task} is already completed, the {@linkplain Task} is returned unchanged.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* completed
* @return the updated {@linkplain Task} after completion
* @throws InvalidStateException if the {@linkplain Task} with taskId wasn't claimed before
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws InvalidOwnerException if current user isn't the {@linkplain Task#getOwner() owner} of
* the {@linkplain Task} or {@linkplain TaskanaRole#ADMIN}
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task forceCompleteTask(String taskId)
throws TaskNotFoundException, InvalidOwnerException, InvalidStateException,
NotAuthorizedException;
/**
* Inserts a not existing {@linkplain Task}. <br>
* The default values of the created {@linkplain Task} are:
* Inserts a {@linkplain Task} that doesn't exist in the database yet.
*
* <p>If the {@linkplain Task#getWorkbasketSummary() workbasketSummary} of the given {@linkplain
* Task} is NULL, TaskService will call the {@linkplain TaskRoutingProvider} to determine a
* {@linkplain Workbasket} for the {@linkplain Task}. If the {@linkplain TaskRoutingProvider} is
* not active, e.g. because no {@linkplain TaskRoutingProvider} is registered, or the {@linkplain
* TaskRoutingProvider} doesn't find a {@linkplain Workbasket}, the {@linkplain Task} will not be
* inserted.
*
* <p>The default values of the created {@linkplain Task} are:
*
* <ul>
* <li><b>{@linkplain Task#getId() id}</b> - generated by {@linkplain IdGenerator}
* <li><b>{@linkplain Task#getExternalId() externalId}</b> - generated by IdGenerator
* <li><b>{@linkplain Task#getBusinessProcessId() businessProcessId}</b> - generated by
* IdGenerator
* <li><b>{@linkplain Task#getName() name}</b> - name of its Classification
* <li><b>{@linkplain Task#getDescription() description}</b> - description of its Classification
* <li><b>{@linkplain Task#getId() id}</b> - generated automatically
* <li><b>{@linkplain Task#getExternalId() externalId}</b> - if NULL, then generated
* automatically, else unchanged
* <li><b>{@linkplain Task#getBusinessProcessId() businessProcessId}</b> - generated
* automatically
* <li><b>{@linkplain Task#getName() name}</b> - if NULL then the name of its {@linkplain
* Classification}, else unchanged
* <li><b>{@linkplain Task#getDescription() description}</b> - if NULL then description of its
* {@linkplain Classification}, else unchanged
* <li><b>{@linkplain Task#getCreator() creator}</b> - id of current user
* <li><b>{@linkplain Task#getState() state}</b> - 'READY'
* <li><b>{@linkplain Task#isRead() isRead}</b> - {@code false}
* <li><b>{@linkplain Task#isTransferred() isTransferred}</b> - {@code false}
* <li><b>{@linkplain Task#getState() state}</b> - {@linkplain TaskState#READY}
* <li><b>{@linkplain Task#isRead() isRead}</b> - false
* <li><b>{@linkplain Task#isTransferred() isTransferred}</b> - false
* </ul>
*
* @param taskToCreate the transient {@linkplain Task} object to be inserted
* @param taskToCreate the transient {@linkplain Task} to be inserted
* @return the created and inserted {@linkplain Task}
* @throws TaskAlreadyExistException if the {@linkplain Task} does already exist.
* @throws NotAuthorizedException thrown if the current user is not authorized to create that
* {@linkplain Task}
* @throws WorkbasketNotFoundException thrown if the workbasket referenced by the {@linkplain
* Task} is not found
* @throws ClassificationNotFoundException thrown if the Classification referenced by the
* {@linkplain Task} is not found
* @throws InvalidArgumentException thrown if the primary ObjectReference is invalid
* @throws AttachmentPersistenceException if an Attachment with ID will be added multiple times
* without using the task-methods
* @throws ObjectReferencePersistenceException if an ObjectReference with ID will be added
* multiple times without using the task-methods
* @throws TaskAlreadyExistException if the {@linkplain Task} already exists
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#APPEND} for the {@linkplain Workbasket} the {@linkplain Task} is in
* @throws WorkbasketNotFoundException if the {@linkplain Workbasket} referenced by the
* {@linkplain Task#getWorkbasketSummary() workbasketSummary} of the {@linkplain Task} isn't
* found
* @throws ClassificationNotFoundException if the {@linkplain Classification} referenced by
* {@linkplain Task#getClassificationSummary() classificationSummary} of the {@linkplain Task}
* isn't found
* @throws InvalidArgumentException if the {@linkplain Task#getPrimaryObjRef() primaryObjRef} is
* invalid
* @throws AttachmentPersistenceException if an {@linkplain Attachment} with the same {@linkplain
* Attachment#getId() id} was added to the {@linkplain Task} multiple times without using
* {@linkplain Task#addAttachment(Attachment)}
* @throws ObjectReferencePersistenceException if an {@linkplain ObjectReference} with the same
* {@linkplain ObjectReference#getId() id} was added to the {@linkplain Task} multiple times
* without using {@linkplain Task#addSecondaryObjectReference(ObjectReference)}
*/
Task createTask(Task taskToCreate)
throws NotAuthorizedException, WorkbasketNotFoundException, ClassificationNotFoundException,
@ -171,20 +195,19 @@ public interface TaskService {
ObjectReferencePersistenceException;
/**
* Gets the details of a {@linkplain Task} by {@linkplain Task#getId() id} without checking
* permissions.
* Fetches a {@linkplain Task} from the database by the specified {@linkplain Task#getId() id}.
*
* @param taskId the {@linkplain Task#getId()} of the {@linkplain Task}
* @return the {@linkplain Task}
* @throws TaskNotFoundException thrown of the {@linkplain Task} with taskId is not found
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission#READ
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in.
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task}
* @return the {@linkplain Task} with the specified taskId
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task getTask(String taskId) throws TaskNotFoundException, NotAuthorizedException;
/**
* Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always setting the
* {@linkplain Task#isTransferred transfer} flag.
* Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always setting
* {@linkplain Task#isTransferred() isTransferred} to true.
*
* @see #transfer(String, String, boolean)
*/
@ -198,30 +221,31 @@ public interface TaskService {
/**
* Transfers a {@linkplain Task} to another {@linkplain Workbasket}.
*
* <p>The transfer resets the {@linkplain Task#isRead() read} flag and sets the {@linkplain
* Task#isTransferred() transfer} flag if {@code setTransferFlag} is {@code true}.
* <p>The transfer resets {@linkplain Task#isRead() isRead} and sets {@linkplain
* Task#isTransferred() isTransferred} if setTransferFlag is true.
*
* @param taskId the {@linkplain Task#getId()} of the {@linkplain Task} which should be
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* transferred
* @param destinationWorkbasketId the {@linkplain Workbasket#getId() id} of the target {@linkplain
* Workbasket}
* @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
* flag or not
* @param setTransferFlag controls whether to set {@linkplain Task#isTransferred() isTransferred}
* to true or not
* @return the transferred {@linkplain Task}
* @throws TaskNotFoundException Thrown if the {@linkplain Task} with taskId was not found.
* @throws WorkbasketNotFoundException Thrown if the target {@linkplain Workbasket} was not found.
* @throws NotAuthorizedException Thrown if the current user is not authorized to transfer this
* {@linkplain Task} to the target {@linkplain Workbasket}
* @throws InvalidStateException Thrown if the {@linkplain Task} is in a {@linkplain
* Task#getState() state} which does not allow transferring
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} was not found
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the source {@linkplain Workbasket} or no {@linkplain
* WorkbasketPermission#TRANSFER} for the target {@linkplain Workbasket}
* @throws InvalidStateException if the {@linkplain Task} is in one of the {@linkplain
* TaskState#END_STATES}
*/
Task transfer(String taskId, String destinationWorkbasketId, boolean setTransferFlag)
throws TaskNotFoundException, WorkbasketNotFoundException, NotAuthorizedException,
InvalidStateException;
/**
* Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always setting the
* {@linkplain Task#isTransferred transfer} flag.
* Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always setting
* {@linkplain Task#isTransferred isTransferred} .
*
* @see #transfer(String, String, String, boolean)
*/
@ -235,131 +259,165 @@ public interface TaskService {
/**
* Transfers a {@linkplain Task} to another {@linkplain Workbasket}.
*
* <p>The transfer resets the {@linkplain Task#isRead() read} flag and sets the transfer flag if
* {@code setTransferFlag} is {@code true}.
* <p>The transfer resets {@linkplain Task#isRead() isRead} and sets {@linkplain
* Task#isTransferred() isTransferred} if setTransferFlag is true.
*
* @param taskId the id of the {@linkplain Task} which should be transferred
* @param workbasketKey the key of the target {@linkplain Workbasket}
* @param domain the domain of the target {@linkplain Workbasket}
* @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
* flag or not
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be
* transferred
* @param workbasketKey the {@linkplain Workbasket#getKey() key} of the target {@linkplain
* Workbasket}
* @param domain the {@linkplain Workbasket#getDomain() domain} of the target {@linkplain
* Workbasket}
* @param setTransferFlag controls whether to set {@linkplain Task#isTransferred() isTransferred}
* or not
* @return the transferred {@linkplain Task}
* @throws TaskNotFoundException Thrown if the {@linkplain Task} with taskId was not found.
* @throws WorkbasketNotFoundException Thrown if the target {@linkplain Workbasket} was not found.
* @throws NotAuthorizedException Thrown if the current user is not authorized to transfer this
* {@linkplain Task} to the target {@linkplain Workbasket}
* @throws InvalidStateException Thrown if the {@linkplain Task} is in a {@linkplain
* Task#getState()} which does not allow transferring
* @throws TaskNotFoundException if the {@linkplain Task} with taskId was not found
* @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} was not found
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the source {@linkplain Workbasket} or no {@linkplain
* WorkbasketPermission#TRANSFER} for the target {@linkplain Workbasket}
* @throws InvalidStateException if the {@linkplain Task} is in one of the {@linkplain
* TaskState#END_STATES}
*/
Task transfer(String taskId, String workbasketKey, String domain, boolean setTransferFlag)
throws TaskNotFoundException, WorkbasketNotFoundException, NotAuthorizedException,
InvalidStateException;
/**
* Marks a {@linkplain Task} as read.
* Sets the value of {@linkplain Task#isRead() isRead} of the specified {@linkplain Task}.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to be updated
* @param isRead the new status of the {@linkplain Task#isRead() read} flag
* @param isRead the new status of {@linkplain Task#isRead() isRead}
* @return the updated {@linkplain Task}
* @throws TaskNotFoundException Thrown if the {@linkplain Task} with taskId was not found
* @throws NotAuthorizedException if the current user has no {@linkplain WorkbasketPermission
* READ} permission for the {@linkplain Workbasket} the {@linkplain Task} is in
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task setTaskRead(String taskId, boolean isRead)
throws TaskNotFoundException, NotAuthorizedException;
/**
* Provides a query builder for querying the database.
* Creates an empty {@linkplain TaskQuery}.
*
* @return a {@linkplain TaskQuery}
*/
TaskQuery createTaskQuery();
/**
* This method provides a query builder for querying the database.
* Creates an empty {@linkplain TaskCommentQuery}.
*
* @return a {@linkplain TaskCommentQuery}
*/
TaskCommentQuery createTaskCommentQuery();
/**
* Returns a not inserted instance of {@linkplain Task}. The returned {@linkplain Task} has no
* {@linkplain Task#getWorkbasketSummary() w} set. When createTask() is invoked for this task,
* TaskService will call the TaskRouting SPI to determine a workbasket for the task. If the
* TaskRouting API is not active, e.g. because no TaskRouter is registered, or the TaskRouter(s)
* don't find a workbasket, the task will not be inserted.
* Instantiates a non-persistent/non-inserted {@linkplain Task}.
*
* @return an empty new Task
* <p>Since a {@linkplain Task} doesn't allow setting a {@linkplain Task#getWorkbasketSummary()
* workbasketSummary}, please either provide an implementation of the {@linkplain
* TaskRoutingProvider} or use the referenced methods to create a {@linkplain Task} within a
* specific {@linkplain Workbasket}.
*
* @return the instantiated {@linkplain Task}
* @see #newTask(String)
* @see #newTask(String, String)
*/
Task newTask();
/**
* Returns a not inserted instance of {@linkplain Task}.
* Instantiates a non-persistent/non-inserted {@linkplain Task}.
*
* @param workbasketId the {@linkplain Workbasket#getId() id} of the {@linkplain Workbasket} to
* which the task belongs
* @return an empty new {@linkplain Task}
* which the {@linkplain Task} belongs
* @return the instantiated {@linkplain Task}
* @see #newTask()
* @see #newTask(String, String)
*/
Task newTask(String workbasketId);
/**
* Returns a not inserted instance of {@linkplain Task}.
* Instantiates a non-persistent/non-inserted {@linkplain Task}.
*
* @param workbasketKey the {@linkplain Workbasket#getKey() key} of the {@linkplain Workbasket} to
* which the {@linkplain Task} belongs
* @param domain the {@linkplain Workbasket#getDomain() domain} of the {@linkplain Workbasket} to
* which the {@linkplain Task} belongs
* @return an empty new {@linkplain Task}
* @return the instantiated {@linkplain Task}
* @see #newTask()
* @see #newTask(String)
*/
Task newTask(String workbasketKey, String domain);
/**
* Returns a not inserted instance of {@linkplain TaskComment}.
* Instantiates a non-persistent/non-inserted {@linkplain TaskComment}.
*
* @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to which the task
* comment belongs
* @return an empty new {@linkplain TaskComment}
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to which the
* {@linkplain TaskComment} belongs
* @return the instantiated {@linkplain TaskComment}
*/
TaskComment newTaskComment(String taskId);
/**
* Returns a not inserted instance of {@linkplain Attachment}.
* Instantiates a non-persistent/non-inserted {@linkplain Attachment}.
*
* @return an empty new {@linkplain Attachment}
* @return the instantiated {@linkplain Attachment}
*/
Attachment newAttachment();
/**
* Returns a not inserted instance of {@linkplain ObjectReference}.
* Instantiates a non-persistent/non-inserted {@linkplain ObjectReference}.
*
* @return an empty new {@linkplain ObjectReference}
* @return the instantiated {@linkplain ObjectReference}
* @see #newObjectReference(String, String, String, String, String)
*/
ObjectReference newObjectReference();
/**
* Instantiates a non-persistent/non-inserted {@linkplain ObjectReference}.
*
* @param company the {@linkplain ObjectReference#getCompany() company} of the new {@linkplain
* ObjectReference}
* @param system the {@linkplain ObjectReference#getSystem() system} of the new {@linkplain
* ObjectReference}
* @param systemInstance the {@linkplain ObjectReference#getSystemInstance() systemInstance} of
* the new {@linkplain ObjectReference}
* @param type the {@linkplain ObjectReference#getType() type} of the new {@linkplain
* ObjectReference}
* @param value the {@linkplain ObjectReference#getValue() value} of the new {@linkplain
* ObjectReference}
* @return the instantiated {@linkplain ObjectReference}
* @see #newObjectReference()
*/
ObjectReference newObjectReference(
String company, String system, String systemInstance, String type, String value);
/**
* Update a {@linkplain Task}.
*
* @param task the {@linkplain Task} to be updated in the database
* @param task the {@linkplain Task} to be updated
* @return the updated {@linkplain Task}
* @throws InvalidArgumentException if the {@linkplain Task} to be updated contains invalid
* properties like e.g. invalid {@linkplain ObjectReference}s
* @throws TaskNotFoundException if the id of the {@linkplain Task} is not found in the database
* properties like e.g. invalid {@linkplain Task#getSecondaryObjectReferences()
* secondaryObjectReferences}
* @throws TaskNotFoundException if the {@linkplain Task} isn't found in the database by its
* {@linkplain Task#getId() id}
* @throws ConcurrencyException if the {@linkplain Task} has been updated by another user in the
* meantime; that's the case if the given modified timestamp differs from the one in the
* database
* @throws ClassificationNotFoundException if the updated {@linkplain Task} refers to a {@link
* Classification} that cannot be found
* @throws NotAuthorizedException if the current user is not authorized to update the {@linkplain
* Task}
* @throws AttachmentPersistenceException if an {@linkplain Attachment} with ID will be added
* multiple times without using the Task-methods
* @throws ObjectReferencePersistenceException if an {@linkplain ObjectReference} with ID will be
* added multiple times without using the Task-methods
* @throws InvalidStateException if an attempt is made to change the owner of the {@linkplain
* Task} that state isn't READY.
* meantime; that's the case if the given {@linkplain Task#getModified() modified} timestamp
* differs from the one in the database
* @throws ClassificationNotFoundException if the {@linkplain Task#getClassificationSummary()
* classificationSummary} of the updated {@linkplain Task} refers to a {@link Classification}
* that can't be found
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
* @throws AttachmentPersistenceException if an {@linkplain Attachment} with the same {@linkplain
* Attachment#getId() id} was added to the {@linkplain Task} multiple times without using
* {@linkplain Task#addAttachment(Attachment)}
* @throws ObjectReferencePersistenceException if an {@linkplain ObjectReference} with the same
* {@linkplain ObjectReference#getId() id} was added to the {@linkplain Task} multiple times
* without using {@linkplain Task#addSecondaryObjectReference(ObjectReference)}
* @throws InvalidStateException if an attempt is made to change the {@linkplain Task#getOwner()
* owner} of the {@linkplain Task} that {@linkplain Task#getState() state} isn't {@linkplain
* TaskState#READY}
*/
Task updateTask(Task task)
throws InvalidArgumentException, TaskNotFoundException, ConcurrencyException,
@ -367,8 +425,8 @@ public interface TaskService {
ObjectReferencePersistenceException, InvalidStateException;
/**
* Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket} while always
* setting the {@linkplain Task#isTransferred transfer} flag.
* Transfers a List of {@linkplain Task Tasks} to another {@linkplain Workbasket} while always
* setting {@linkplain Task#isTransferred isTransferred} to true.
*
* @see #transferTasks(String, List, boolean)
*/
@ -380,32 +438,32 @@ public interface TaskService {
}
/**
* Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket}.
* Transfers a List of {@linkplain Task Tasks} to another {@linkplain Workbasket}.
*
* <p>The transfer resets the {@linkplain Task#isRead() read flag} and sets the {@linkplain
* Task#isTransferred() transfer flag} if {@code setTransferFlag} is {@code true}. Exceptions will
* be thrown if the caller got no {@linkplain WorkbasketPermission} on the target or if the target
* {@linkplain Workbasket} does not exist. Other Exceptions will be stored and returned in the
* end.
* <p>The transfer resets {@linkplain Task#isRead() isRead} and sets {@linkplain
* Task#isTransferred() isTransferred} if setTransferFlag is true. Exceptions will be thrown if
* the caller got no {@linkplain WorkbasketPermission} on the target or if the target {@linkplain
* Workbasket} doesn't exist. Other Exceptions will be stored and returned in the end.
*
* @param destinationWorkbasketId {@linkplain Workbasket#getId() id} of the target {@linkplain
* Workbasket}
* @param taskIds list of source {@linkplain Task Tasks} which will be moved
* @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
* flag or not
* @return Bulkresult with {@linkplain Task#getId() ids} and Error in it for failed transactions
* @throws NotAuthorizedException if the caller has no permissions on target {@linkplain
* Workbasket}
* @throws InvalidArgumentException if the method parameters are EMPTY or NULL
* @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} can not be found
* @param taskIds List of source {@linkplain Task Tasks} which will be moved
* @param setTransferFlag controls whether to set {@linkplain Task#isTransferred() isTransferred}
* or not
* @return Bulkresult with {@linkplain Task#getId() ids} and Error for each failed transactions
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the source {@linkplain Workbasket} or no {@linkplain
* WorkbasketPermission#TRANSFER} for the target {@linkplain Workbasket}
* @throws InvalidArgumentException if the method parameters are empty or NULL
* @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} can't be found
*/
BulkOperationResults<String, TaskanaException> transferTasks(
String destinationWorkbasketId, List<String> taskIds, boolean setTransferFlag)
throws NotAuthorizedException, InvalidArgumentException, WorkbasketNotFoundException;
/**
* Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket} while always
* setting the {@linkplain Task#isTransferred} flag.
* Transfers a List of {@linkplain Task Tasks} to another {@linkplain Workbasket} while always
* setting {@linkplain Task#isTransferred() isTransferred} to true.
*
* @see #transferTasks(String, String, List, boolean)
*/
@ -417,24 +475,25 @@ public interface TaskService {
}
/**
* Transfers a list of {@linkplain Task Tasks} to another {@linkplain Workbasket}.
* Transfers a List of {@linkplain Task Tasks} to another {@linkplain Workbasket}.
*
* <p>The transfer resets the {@linkplain Task#isRead() read flag} and sets the {@linkplain
* Task#isTransferred() transfer flag} if {@code setTransferFlag} is {@code true}. Exceptions will
* be thrown if the caller got no {@linkplain WorkbasketPermission Permission} on the target
* {@linkplain Workbasket} or if it does not exist. Other Exceptions will be stored and returned
* in the end.
* <p>The transfer resets {@linkplain Task#isRead() isRead} and sets {@linkplain
* Task#isTransferred() isTransferred} if setTransferFlag is true. Exceptions will be thrown if
* the caller got no {@linkplain WorkbasketPermission} on the target {@linkplain Workbasket} or if
* it doesn't exist. Other Exceptions will be stored and returned in the end.
*
* @param destinationWorkbasketKey target {@linkplain Workbasket#getKey()} Workbasket}
* @param destinationWorkbasketKey target {@linkplain Workbasket#getKey() key}
* @param destinationWorkbasketDomain target {@linkplain Workbasket#getDomain() domain}
* @param taskIds List of source {@linkplain Task Tasks} which will be moved
* @param setTransferFlag the control about whether to set the {@linkplain Task#isTransferred()}
* flag or not
* @return BulkResult with {@linkplain Task#getId() id} and Error in it for failed transactions.
* @throws NotAuthorizedException if the caller has no {@linkplain WorkbasketPermission} on target
* {@linkplain Workbasket}.
* @throws InvalidArgumentException if the method parameters are EMPTY or NULL.
* @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} can not be found.
* @param taskIds List of {@linkplain Task#getId() ids} of source {@linkplain Task Tasks} which
* will be moved
* @param setTransferFlag controls whether to set {@linkplain Task#isTransferred() isTransferred}
* or not
* @return BulkResult with {@linkplain Task#getId() ids} and Error for each failed transactions
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the source {@linkplain Workbasket} or no {@linkplain
* WorkbasketPermission#TRANSFER} for the target {@linkplain Workbasket}
* @throws InvalidArgumentException if the method parameters are empty or NULL
* @throws WorkbasketNotFoundException if the target {@linkplain Workbasket} can't be found
*/
BulkOperationResults<String, TaskanaException> transferTasks(
String destinationWorkbasketKey,
@ -446,27 +505,28 @@ public interface TaskService {
/**
* Deletes the {@linkplain Task} with the given {@linkplain Task#getId() id}.
*
* @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to delete.
* @throws TaskNotFoundException If the given {@linkplain Task#getId() id} does not refer to an
* existing {@linkplain Task}.
* @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to delete
* @throws TaskNotFoundException If the given {@linkplain Task#getId() id} doesn't refer to an
* existing {@linkplain Task}
* @throws InvalidStateException If the {@linkplain Task#getState() state} of the referenced
* {@linkplain Task} is not an end state.
* @throws NotAuthorizedException if the current user is not member of role {@linkplain
* {@linkplain Task} isn't one of the {@linkplain TaskState#END_STATES}
* @throws NotAuthorizedException if the current user isn't member of {@linkplain
* TaskanaRole#ADMIN}
*/
void deleteTask(String taskId)
throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;
/**
* Deletes the {@linkplain Task} with the given {@linkplain Task#getId() id} even if it is not
* Deletes the {@linkplain Task} with the given {@linkplain Task#getId() id} even if it isn't
* completed.
*
* @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to delete.
* @throws TaskNotFoundException If the given {@linkplain Task#getId() id} does not refer to an
* existing {@linkplain Task}.
* @throws InvalidStateException If the state of the referenced {@linkplain Task} is not an end
* state and forceDelete is false.
* @throws NotAuthorizedException if the current user is not member of role {@linkplain
* @param taskId The {@linkplain Task#getId() id} of the {@linkplain Task} to delete
* @throws TaskNotFoundException if the given {@linkplain Task#getId() id} doesn't refer to an
* existing {@linkplain Task}
* @throws InvalidStateException if the {@linkplain Task#getState() state} of the referenced
* {@linkplain Task} isn't one of the {@linkplain TaskState#END_STATES} and forceDelete is
* false
* @throws NotAuthorizedException if the current user isn't member of {@linkplain
* TaskanaRole#ADMIN}
*/
void forceDeleteTask(String taskId)
@ -475,28 +535,29 @@ public interface TaskService {
/**
* Selects and claims the first {@linkplain Task} which is returned by the {@linkplain TaskQuery}.
*
* @param taskQuery the {@linkplain TaskQuery}.
* @param taskQuery the {@linkplain TaskQuery}
* @return the {@linkplain Task} that got selected and claimed
* @throws InvalidOwnerException if the {@linkplain Task} is claimed by someone else
* @throws NotAuthorizedException if the current user has no read permission for the Workbasket
* the {@linkplain Task} is in
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task selectAndClaim(TaskQuery taskQuery) throws NotAuthorizedException, InvalidOwnerException;
/**
* Deletes a list of {@linkplain Task Tasks}.
* Deletes a List of {@linkplain Task Tasks}.
*
* @param tasks the {@linkplain Task#getId() ids} of the tasks to delete.
* @param tasks the {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} to delete
* @return the result of the operations with each {@linkplain Task#getId() id} and Exception for
* each failed task deletion.
* @throws InvalidArgumentException if the TaskIds parameter is NULL
* @throws NotAuthorizedException if the current user is not member of role ADMIN
* each failed deletion
* @throws InvalidArgumentException if the tasks parameter contains NULL values
* @throws NotAuthorizedException if the current user isn't member of {@linkplain
* TaskanaRole#ADMIN}
*/
BulkOperationResults<String, TaskanaException> deleteTasks(List<String> tasks)
throws InvalidArgumentException, NotAuthorizedException;
/**
* Completes a list of {@linkplain Task Tasks}.
* Completes a List of {@linkplain Task Tasks}.
*
* @param taskIds {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} which should be
* completed
@ -510,13 +571,14 @@ public interface TaskService {
/**
* Completes each existing {@linkplain Task} in the given List in every case, independent of the
* {@linkplain Task#getOwner() owner} or {@linkplain Task#getState() state} of the {@linkplain
* Task}. If the {@linkplain Task} is already {@linkplain TaskState#COMPLETED completed}, the
* Task}.
*
* <p>If the {@linkplain Task} is already {@linkplain TaskState#COMPLETED completed}, the
* {@linkplain Task} stays unchanged.
*
* @see TaskService#forceCompleteTask
* @param taskIds {@linkplain Task#getId() id} of the {@linkplain Task Tasks} which should be
* completed
* @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
* @return the result of the operations with {@linkplain Task#getId() ids} and Exception for each
* failed completion
* @throws InvalidArgumentException If the taskIds parameter is NULL
*/
@ -525,14 +587,17 @@ public interface TaskService {
/**
* Updates specified {@linkplain TaskCustomField TaskCustomFields} of {@linkplain Task Tasks}
* associated with the given {@linkplain ObjectReference}.
* associated with the given {@linkplain Task#getPrimaryObjRef() primaryObjRef}.
*
* @param selectionCriteria the {@linkplain ObjectReference} that is used to select the tasks
* @param selectionCriteria the {@linkplain Task#getPrimaryObjRef() primaryObjRef} of the
* searched-for {@linkplain Task Tasks}.
* @param customFieldsToUpdate a Map that contains as key the identification of the {@linkplain
* TaskCustomField} and as value the corresponding new value of that field
* @return a list of the {@linkplain Task#getId() ids} of all modified {@linkplain Task Tasks}
* TaskCustomField} and as value the corresponding new value of that {@linkplain
* TaskCustomField}
* @return a List of the {@linkplain Task#getId() ids} of all modified {@linkplain Task Tasks}
* @throws InvalidArgumentException if the given selectionCriteria is invalid or the given
* customFieldsToUpdate are NULL or empty
* @see #updateTasks(List, Map)
*/
List<String> updateTasks(
ObjectReference selectionCriteria, Map<TaskCustomField, String> customFieldsToUpdate)
@ -543,12 +608,13 @@ public interface TaskService {
* Tasks}.
*
* @param taskIds the {@linkplain Task#getId() taskIds} that are used to select the {@linkplain
* Task Tasks}.
* Task Tasks}
* @param customFieldsToUpdate a Map that contains as key the identification of the {@linkplain
* TaskCustomField} and as value the corresponding new value of that {@linkplain
* TaskCustomField}.
* TaskCustomField}
* @return a list of the {@linkplain Task#getId() ids} of all modified {@linkplain Task Tasks}
* @throws InvalidArgumentException if the given customFieldsToUpdate are NULL or empty.
* @throws InvalidArgumentException if the given customFieldsToUpdate are NULL or empty
* @see #updateTasks(ObjectReference, Map)
*/
List<String> updateTasks(List<String> taskIds, Map<TaskCustomField, String> customFieldsToUpdate)
throws InvalidArgumentException;
@ -558,12 +624,13 @@ public interface TaskService {
*
* @param taskComment the {@linkplain TaskComment} to be created
* @return the created {@linkplain TaskComment}
* @throws NotAuthorizedException if the current user has no authorization to create a {@link
* TaskComment} for the given taskId or is not authorized to access the {@linkplain Task}
* @throws TaskNotFoundException if the given {@linkplain TaskComment#getTaskId() taskId} does not
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} of the commented {@linkplain
* Task}.
* @throws TaskNotFoundException if the given {@linkplain TaskComment#getTaskId() taskId} doesn't
* refer to an existing {@linkplain Task}
* @throws InvalidArgumentException if the {@linkplain TaskComment#getId() id} of the provided
* {@link TaskComment} is not NULL or empty
* {@link TaskComment} is neither NULL nor empty
*/
TaskComment createTaskComment(TaskComment taskComment)
throws NotAuthorizedException, TaskNotFoundException, InvalidArgumentException;
@ -573,17 +640,18 @@ public interface TaskService {
*
* @param taskComment the {@linkplain TaskComment} to be updated in the database
* @return the updated {@linkplain TaskComment}
* @throws NotAuthorizedException if the current user has no authorization to update the
* {@linkplain TaskComment} or is not authorized to access the {@linkplain Task}
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} of the commented {@linkplain
* Task}.
* @throws ConcurrencyException if an attempt is made to update the {@linkplain TaskComment} and
* another user updated it already; that's the case if the given {} timestamp differs from the
* one in the database
* @throws TaskCommentNotFoundException if the {@linkplain TaskComment#getId() is} of the
* specified {@linkplain TaskComment}does not refer to an existing {@linkplain TaskComment}
* @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} does not refer
* another user updated it already; that's the case if the given {@linkplain
* Task#getModified() modified} timestamp differs from the one in the database
* @throws TaskCommentNotFoundException if the {@linkplain TaskComment#getId() id} of the
* specified {@linkplain TaskComment} doesn't refer to an existing {@linkplain TaskComment}
* @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} doesn't refer
* to an existing {@linkplain Task}
* @throws InvalidArgumentException if the given {@linkplain TaskComment#getId() id} is NULL or
* empty
* @throws InvalidArgumentException if the {@linkplain TaskComment#getId() id} of the specified
* {@linkplain TaskComment} is NULL or empty
*/
TaskComment updateTaskComment(TaskComment taskComment)
throws NotAuthorizedException, ConcurrencyException, TaskCommentNotFoundException,
@ -594,13 +662,15 @@ public interface TaskService {
*
* @param taskCommentId the {@linkplain TaskComment#getId() id} of the {@linkplain TaskComment} to
* delete
* @throws NotAuthorizedException if the current user has no authorization to delete a task
* comment or is not authorized to access the task.
* @throws NotAuthorizedException if the current user isn't {@linkplain TaskanaRole#ADMIN},
* {@linkplain TaskanaRole#TASK_ADMIN} or the {@linkplain TaskComment#getCreator() creator} of
* the {@linkplain TaskComment}; the user also needs {@linkplain WorkbasketPermission#READ}
* for the {@linkplain Workbasket} of the commented {@linkplain Task}
* @throws InvalidArgumentException if the taskCommentId is NULL or empty
* @throws TaskCommentNotFoundException if the given taskCommentId in the TaskComment does not
* refer to an existing taskComment.
* @throws TaskCommentNotFoundException if the given taskCommentId doesn't refer to an existing
* {@linkplain TaskComment}
* @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} of the
* TaskComment does not refer to an existing {@linkplain Task}.
* TaskComment doesn't refer to an existing {@linkplain Task}
* @throws InvalidArgumentException if the given taskCommentId is NULL or empty
*/
void deleteTaskComment(String taskCommentId)
@ -613,13 +683,13 @@ public interface TaskService {
* @param taskCommentId the {@linkplain TaskComment#getId() id} of the {@linkplain TaskComment}
* which should be retrieved
* @return the {@linkplain TaskComment} identified by taskCommentId
* @throws TaskCommentNotFoundException if the given taskCommentId does not refer to an existing
* @throws TaskCommentNotFoundException if the given taskCommentId doesn't refer to an existing
* {@linkplain TaskComment}
* @throws NotAuthorizedException if the current user has no authorization to retrieve a
* {@linkplain TaskComment} from a certain {@linkplain Task} or is not authorized to access
* the {@linkplain Task}
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} of the commented {@linkplain
* Task}
* @throws TaskNotFoundException if the {@linkplain TaskComment#getTaskId() taskId} of the
* TaskComment does not refer to an existing {@linkplain Task}
* TaskComment doesn't refer to an existing {@linkplain Task}
* @throws InvalidArgumentException if the given taskCommentId is NULL or empty
*/
TaskComment getTaskComment(String taskCommentId)
@ -627,42 +697,46 @@ public interface TaskService {
InvalidArgumentException;
/**
* Retrieves the List of {@linkplain TaskComment TaskComments} for the Task with given {@linkplain
* Task#getId() id}.
* Retrieves the List of {@linkplain TaskComment TaskComments} for the {@linkplain Task} with
* given {@linkplain Task#getId() id}.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} for which all task
* comments should be retrieved
* @return the List of task comments attached to the specified {@linkplain Task}
* @throws NotAuthorizedException if the current user has no authorization to retrieve a
* taskComment from the {@linkplain Task} or is not authorized to access the {@linkplain Task}
* @throws TaskNotFoundException if the given taskId does not refer to an existing {@linkplain
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} for which all
* {@linkplain TaskComment TaskComments} should be retrieved
* @return the List of {@linkplain TaskComment TaskComments} attached to the specified {@linkplain
* Task}
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} of the commented {@linkplain
* Task}
* @throws TaskNotFoundException if the given taskId doesn't refer to an existing {@linkplain
* Task}
*/
List<TaskComment> getTaskComments(String taskId)
throws NotAuthorizedException, TaskNotFoundException;
/**
* Sets the specified {@linkplain CallbackState} on a list of {@linkplain Task Tasks}. Note: this
* method is primarily intended to be used by the TaskanaAdapter
* Sets the specified {@linkplain CallbackState} on a List of {@linkplain Task Tasks}.
*
* <p>Note: this method is primarily intended to be used by the TaskanaAdapter
*
* @param externalIds the {@linkplain Task#getExternalId() externalIds} of the {@linkplain Task
* Tasks} on which the {@linkplain CallbackState} is set
* @param state the {@linkplain CallbackState} that is to be set on the {@linkplain Task Tasks}
* @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
* @return the result of the operations with {@linkplain Task#getId() ids} and Exception for each
* failed operation
*/
BulkOperationResults<String, TaskanaException> setCallbackStateForTasks(
List<String> externalIds, CallbackState state);
/**
* Sets the {@linkplain Task#getOwner() owner} on a List of {@linkplain Task Tasks}. The
* {@linkplain Task#getOwner() owner} will only be set on {@linkplain Task Tasks} that are in
* state {@linkplain TaskState#READY}.
* Sets the {@linkplain Task#getOwner() owner} on a List of {@linkplain Task Tasks}.
*
* <p>The {@linkplain Task#getOwner() owner} will only be set on {@linkplain Task Tasks} that are
* in {@linkplain TaskState#READY}.
*
* @param owner the new {@linkplain Task#getOwner() owner} of the {@linkplain Task Tasks}
* @param taskIds the {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} on which the
* {@linkplain Task#getOwner() owner} is to be set
* @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
* @return the result of the operations with {@linkplain Task#getId() ids} and Exception for each
* failed {@linkplain Task}-update
*/
BulkOperationResults<String, TaskanaException> setOwnerOfTasks(
@ -670,49 +744,53 @@ public interface TaskService {
/**
* Sets the {@linkplain Task#getPlanned() planned} Instant on a List of {@linkplain Task Tasks}.
* Only {@linkplain Task Tasks} in state {@linkplain TaskState#READY} and {@linkplain
*
* <p>Only {@linkplain Task Tasks} in state {@linkplain TaskState#READY} and {@linkplain
* TaskState#CLAIMED} will be affected by this method. On each {@linkplain Task}, the
* corresponding {@linkplain Task#getDue() due date} is set according to the shortest serviceLevel
* in the {@linkplain Task#getClassificationSummary() Classification} of the {@linkplain Task} and
* its {@linkplain Task#getAttachments() Attachments}.
* corresponding {@linkplain Task#getDue() due} Instant is set according to the shortest
* serviceLevel in the {@linkplain Task#getClassificationSummary() Classification} of the
* {@linkplain Task} and its {@linkplain Task#getAttachments() Attachments}.
*
* @param planned the new {@linkplain Task#getPlanned() planned} Instant of the {@linkplain Task
* Tasks}
* @param taskIds the {@linkplain Task#getId() ids} of the {@linkplain Task Tasks} on which the
* new {@linkplain Task#getPlanned() planned} Instant is to be set
* @return the result of the operations with {@linkplain Task#getId() id} and Exception for each
* failed {@linkplain Task Task} update.
* @return the result of the operations with {@linkplain Task#getId() ids} and Exception for each
* failed {@linkplain Task} update
*/
BulkOperationResults<String, TaskanaException> setPlannedPropertyOfTasks(
Instant planned, List<String> taskIds);
/**
* Cancels the {@linkplain Task} with the given {@linkplain Task#getId() id}. Cancellation means a
* {@linkplain Task} is obsolete from a business perspective and does not need to be completed
* anymore.
* Cancels the {@linkplain Task} with the given {@linkplain Task#getId() id}.
*
* <p>Cancellation means a {@linkplain Task} is obsolete from a business perspective and doesn't
* need to be completed anymore.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to cancel
* @return the updated {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId is not found
* @throws InvalidStateException if the {@linkplain Task} is not in state {@linkplain
* TaskState#READY} or {@linkplain TaskState#CLAIMED}
* @throws NotAuthorizedException if the current user is not authorized to see the {@linkplain
* Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws InvalidStateException if the {@linkplain Task} isn't in {@linkplain TaskState#READY} or
* {@linkplain TaskState#CLAIMED}
* @throws NotAuthorizedException if the current user has no {@linkplain
* WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in
*/
Task cancelTask(String taskId)
throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;
/**
* Terminates a {@linkplain Task}. Termination is an administrative action to complete a
* {@linkplain Task}. This is typically done by administration to correct any technical issue.
* {@linkplain Task}.
*
* @param taskId the id of the {@linkplain Task} to cancel
* <p>This is typically done by administration to correct any technical issue.
*
* @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} to cancel
* @return the updated {@linkplain Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId is not found
* @throws InvalidStateException if the {@linkplain Task} is not in state {@linkplain
* TaskState#READY} or {@linkplain TaskState#CLAIMED}
* @throws NotAuthorizedException if the current user is not authorized to see the {@linkplain
* Task}
* @throws TaskNotFoundException if the {@linkplain Task} with taskId wasn't found
* @throws InvalidStateException if the {@linkplain Task} isn't in {@linkplain TaskState#READY} or
* {@linkplain TaskState#CLAIMED}
* @throws NotAuthorizedException if the current user isn't member of {@linkplain
* TaskanaRole#ADMIN} or {@linkplain TaskanaRole#BUSINESS_ADMIN}
*/
Task terminateTask(String taskId)
throws TaskNotFoundException, InvalidStateException, NotAuthorizedException;