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.NuxeoPrincipal;
027import org.nuxeo.ecm.core.api.SortInfo;
028
029/**
030 * @author Laurent Doguin
031 * @since 5.5
032 */
033public interface TaskProvider extends Serializable {
034
035    /**
036     * @param coreSession
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     * @param coreSession
058     * @return
059     */
060    List<Task> getCurrentTaskInstances(List<String> actors, CoreSession coreSession);
061
062    /**
063     * Provide @param sortInfo to handle sort page-provider contributions (see {@link #getCurrentTaskInstances})
064     *
065     * @since 5.9.3
066     */
067    List<Task> getCurrentTaskInstances(List<String> actors, CoreSession coreSession, List<SortInfo> sortInfos);
068
069    /**
070     * Returns the list of task instances associated with this document for which the user is the actor or belongs to
071     * the pooled actor list. Doesn't take into account tasks that were delegated to this user.
072     * <p>
073     * If the user is null, then it returns all task instances for the document. The query is done in unrestricted mode
074     * and so the documents linked to the tasks are detached.
075     *
076     * @param dm the document.
077     * @param user
078     * @param coreSession
079     * @return
080     */
081    List<Task> getTaskInstances(DocumentModel dm, NuxeoPrincipal user, CoreSession coreSssion);
082
083    /**
084     * Returns the list of task instances associated with this document assigned to one of the actor in the list or its
085     * pool. Doesn't take into account tasks that were delegated to these users. The query is done in unrestricted mode
086     * and so the documents linked to the tasks are detached.
087     *
088     * @param dm
089     * @param actors
090     * @param coreSession
091     * @return
092     */
093    List<Task> getTaskInstances(DocumentModel dm, List<String> actors, CoreSession coreSession);
094
095    /**
096     * Returns the list of task instances associated with this document assigned to one of the actor in the list or its
097     * pool. If the parameter {@code includeDelegatedTasks} is true, takes into account tasks that were delegated to
098     * these users. The query is done in unrestricted mode and so the documents linked to the tasks are detached.
099     *
100     * @since 5.8
101     */
102    List<Task> getTaskInstances(DocumentModel dm, List<String> actors, boolean includeDelegatedTasks,
103            CoreSession session);
104
105    /**
106     * Returns the list of task instances associated assigned to the current user.
107     * Takes into account tasks that were delegated to this user.
108     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
109     *
110     * @since 7.4
111     */
112    List<Task> getAllCurrentTaskInstances(CoreSession session, List<SortInfo> sortInfos);
113
114
115    /**
116     * Returns all the tasks instances for the given {@code processId}.
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, CoreSession session);
123
124    /**
125     * Returns all the tasks instances for the given {@code processId} and where the user is the actor or belongs to the
126     * pooled actor list. Doesn't take into account tasks that were delegated to this user.
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, NuxeoPrincipal user, CoreSession session);
133
134    /**
135     * Returns all the tasks instances for the given {@code processId} which assigned to one of the actor in the list or
136     * its pool. Doesn't take into account tasks that were delegated to these users.
137     * <p>
138     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
139     *
140     * @since 5.6
141     */
142    List<Task> getAllTaskInstances(String processId, List<String> actors, CoreSession session);
143
144    /**
145     * Ends the task
146     *
147     * @since 5.6
148     * @param coreSession the session to use when notifying and resolving of referenced document for notification.
149     * @param principal principal used when notifying
150     * @param task the instance to end
151     * @param comment string added to the task comments and used as a notification comment
152     * @param eventName the core event name to use when notifying
153     * @param isValidated boolean marker to state if the task was validated or rejected
154     * @throws NuxeoException when trying to end a task without being granted the right to do so (see
155     *             {@link #canEndTask(NuxeoPrincipal, Task)}), or when any other error occurs
156     * @return the name of the Seam event to raise
157     */
158    String endTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment, String eventName,
159            boolean isValidated);
160
161    /**
162     * Returns all the tasks instances for the given {@code processId} originating from the given {@code nodeId}.
163     * <p>
164     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
165     *
166     * @since 5.7
167     */
168    List<Task> getAllTaskInstances(String processId, String nodeId, CoreSession session);
169
170}