TSK-1852: refactor JavaDoc in TaskService
This commit is contained in:
parent
43ed441daf
commit
a2e0681190
|
@ -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;
|
||||
|
|
Loading…
Reference in New Issue