001/*
002 * (C) Copyright 2010-2012 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     ldoguin, Antoine Taillefer
018 */
019package org.nuxeo.ecm.platform.task;
020
021import java.io.Serializable;
022import java.util.List;
023
024import org.nuxeo.ecm.core.api.CoreSession;
025import org.nuxeo.ecm.core.api.DocumentModel;
026import org.nuxeo.ecm.core.api.NuxeoException;
027import org.nuxeo.ecm.core.api.NuxeoPrincipal;
028import org.nuxeo.ecm.core.api.SortInfo;
029
030/**
031 * @author Laurent Doguin
032 * @since 5.5
033 */
034public interface TaskProvider extends Serializable {
035
036    /**
037     * @return A list of task instances where the current user is an actor. Doesn't take into account tasks that were
038     *         delegated to this user.
039     * @throws IllegalStateException If the currentUser is null.
040     */
041    List<Task> getCurrentTaskInstances(CoreSession coreSession);
042
043    /**
044     * Provide @param sortInfo to handle sort page-provider contributions (see {@link #getCurrentTaskInstances})
045     *
046     * @since 5.9.3
047     */
048    List<Task> getCurrentTaskInstances(CoreSession coreSession, List<SortInfo> sortInfos);
049
050    /**
051     * Returns a list of task instances assigned to one of the actors in the list or to its pool. Doesn't take into
052     * account tasks that were delegated to these users. The query is done in unrestricted mode and so the documents
053     * linked to the tasks are detached.
054     *
055     * @since 5.5
056     * @param actors a list used as actorId to retrieve the tasks.
057     */
058    List<Task> getCurrentTaskInstances(List<String> actors, CoreSession coreSession);
059
060    /**
061     * Provide @param sortInfo to handle sort page-provider contributions (see {@link #getCurrentTaskInstances})
062     *
063     * @since 5.9.3
064     */
065    List<Task> getCurrentTaskInstances(List<String> actors, CoreSession coreSession, List<SortInfo> sortInfos);
066
067    /**
068     * Returns the list of task instances associated with this document for which the user is the actor or belongs to
069     * the pooled actor list. Doesn't take into account tasks that were delegated to this user.
070     * <p>
071     * If the user is null, then it returns all task instances for the document. The query is done in unrestricted mode
072     * and so the documents linked to the tasks are detached.
073     *
074     * @param dm the document.
075     */
076    List<Task> getTaskInstances(DocumentModel dm, NuxeoPrincipal user, CoreSession coreSession);
077
078    /**
079     * Returns the list of task instances associated with this document assigned to one of the actor in the list or its
080     * pool. Doesn't take into account tasks that were delegated to these users. The query is done in unrestricted mode
081     * and so the documents linked to the tasks are detached.
082     */
083    List<Task> getTaskInstances(DocumentModel dm, List<String> actors, CoreSession coreSession);
084
085    /**
086     * Returns the list of task instances associated with this document assigned to one of the actor in the list or its
087     * pool. If the parameter {@code includeDelegatedTasks} is true, takes into account tasks that were delegated to
088     * these users. The query is done in unrestricted mode and so the documents linked to the tasks are detached.
089     *
090     * @since 5.8
091     */
092    List<Task> getTaskInstances(DocumentModel dm, List<String> actors, boolean includeDelegatedTasks,
093            CoreSession session);
094
095    /**
096     * Returns the list of task instances associated assigned to the current user.
097     * Takes into account tasks that were delegated to this user.
098     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
099     *
100     * @since 7.4
101     */
102    List<Task> getAllCurrentTaskInstances(CoreSession session, List<SortInfo> sortInfos);
103
104
105    /**
106     * Returns all the tasks instances for the given {@code processId}.
107     * <p>
108     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
109     *
110     * @since 5.6
111     */
112    List<Task> getAllTaskInstances(String processId, CoreSession session);
113
114    /**
115     * Returns all the tasks instances for the given {@code processId} and where the user is the actor or belongs to the
116     * pooled actor list. Doesn't take into account tasks that were delegated to this user.
117     * <p>
118     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
119     *
120     * @since 5.6
121     */
122    List<Task> getAllTaskInstances(String processId, NuxeoPrincipal user, CoreSession session);
123
124    /**
125     * Returns all the tasks instances for the given {@code processId} which assigned to one of the actor in the list or
126     * its pool. Doesn't take into account tasks that were delegated to these users.
127     * <p>
128     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
129     *
130     * @since 5.6
131     */
132    List<Task> getAllTaskInstances(String processId, List<String> actors, CoreSession session);
133
134    /**
135     * Ends the task
136     *
137     * @since 5.6
138     * @param coreSession the session to use when notifying and resolving of referenced document for notification.
139     * @param principal principal used when notifying
140     * @param task the instance to end
141     * @param comment string added to the task comments and used as a notification comment
142     * @param eventName the core event name to use when notifying
143     * @param isValidated boolean marker to state if the task was validated or rejected
144     * @throws NuxeoException when trying to end a task without being granted the right to do so, or when any other
145     *             error occurs
146     * @return the name of the Seam event to raise
147     */
148    String endTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment, String eventName,
149            boolean isValidated);
150
151    /**
152     * Returns all the tasks instances for the given {@code processId} originating from the given {@code nodeId}.
153     * <p>
154     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
155     *
156     * @since 5.7
157     */
158    List<Task> getAllTaskInstances(String processId, String nodeId, CoreSession session);
159
160}