001/*
002 * (C) Copyright 2010-2012 Nuxeo SA (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     ldoguin, Antoine Taillefer
016 */
017package org.nuxeo.ecm.platform.task;
018
019import java.io.Serializable;
020import java.util.List;
021
022import org.nuxeo.ecm.core.api.CoreSession;
023import org.nuxeo.ecm.core.api.DocumentModel;
024import org.nuxeo.ecm.core.api.NuxeoPrincipal;
025import org.nuxeo.ecm.core.api.SortInfo;
026
027/**
028 * @author Laurent Doguin
029 * @since 5.5
030 */
031public interface TaskProvider extends Serializable {
032
033    /**
034     * @param coreSession
035     * @return A list of task instances where the current user is an actor. Doesn't take into account tasks that were
036     *         delegated to this user.
037     * @throws IllegalStateException If the currentUser is null.
038     */
039    List<Task> getCurrentTaskInstances(CoreSession coreSession);
040
041    /**
042     * Provide @param sortInfo to handle sort page-provider contributions (see {@link #getCurrentTaskInstances})
043     *
044     * @since 5.9.3
045     */
046    List<Task> getCurrentTaskInstances(CoreSession coreSession, List<SortInfo> sortInfos);
047
048    /**
049     * Returns a list of task instances assigned to one of the actors in the list or to its pool. Doesn't take into
050     * account tasks that were delegated to these users. The query is done in unrestricted mode and so the documents
051     * linked to the tasks are detached.
052     *
053     * @since 5.5
054     * @param actors a list used as actorId to retrieve the tasks.
055     * @param coreSession
056     * @return
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     * @param user
076     * @param coreSession
077     * @return
078     */
079    List<Task> getTaskInstances(DocumentModel dm, NuxeoPrincipal user, CoreSession coreSssion);
080
081    /**
082     * Returns the list of task instances associated with this document assigned to one of the actor in the list or its
083     * pool. Doesn't take into account tasks that were delegated to these users. The query is done in unrestricted mode
084     * and so the documents linked to the tasks are detached.
085     *
086     * @param dm
087     * @param actors
088     * @param coreSession
089     * @return
090     */
091    List<Task> getTaskInstances(DocumentModel dm, List<String> actors, CoreSession coreSession);
092
093    /**
094     * Returns the list of task instances associated with this document assigned to one of the actor in the list or its
095     * pool. If the parameter {@code includeDelegatedTasks} is true, takes into account tasks that were delegated to
096     * these users. The query is done in unrestricted mode and so the documents linked to the tasks are detached.
097     *
098     * @since 5.8
099     */
100    List<Task> getTaskInstances(DocumentModel dm, List<String> actors, boolean includeDelegatedTasks,
101            CoreSession session);
102
103    /**
104     * Returns the list of task instances associated assigned to the current user.
105     * Takes into account tasks that were delegated to this user.
106     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
107     *
108     * @since 7.4
109     */
110    List<Task> getAllCurrentTaskInstances(CoreSession session, List<SortInfo> sortInfos);
111
112
113    /**
114     * Returns all the tasks instances for the given {@code processId}.
115     * <p>
116     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
117     *
118     * @since 5.6
119     */
120    List<Task> getAllTaskInstances(String processId, CoreSession session);
121
122    /**
123     * Returns all the tasks instances for the given {@code processId} and where the user is the actor or belongs to the
124     * pooled actor list. Doesn't take into account tasks that were delegated to this user.
125     * <p>
126     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
127     *
128     * @since 5.6
129     */
130    List<Task> getAllTaskInstances(String processId, NuxeoPrincipal user, CoreSession session);
131
132    /**
133     * Returns all the tasks instances for the given {@code processId} which assigned to one of the actor in the list or
134     * its pool. Doesn't take into account tasks that were delegated to these users.
135     * <p>
136     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
137     *
138     * @since 5.6
139     */
140    List<Task> getAllTaskInstances(String processId, List<String> actors, CoreSession session);
141
142    /**
143     * Ends the task
144     *
145     * @since 5.6
146     * @param coreSession the session to use when notifying and resolving of referenced document for notification.
147     * @param principal principal used when notifying
148     * @param task the instance to end
149     * @param comment string added to the task comments and used as a notification comment
150     * @param eventName the core event name to use when notifying
151     * @param isValidated boolean marker to state if the task was validated or rejected
152     * @throws NuxeoException when trying to end a task without being granted the right to do so (see
153     *             {@link #canEndTask(NuxeoPrincipal, Task)}), or when any other error occurs
154     * @return the name of the Seam event to raise
155     */
156    String endTask(CoreSession coreSession, NuxeoPrincipal principal, Task task, String comment, String eventName,
157            boolean isValidated);
158
159    /**
160     * Returns all the tasks instances for the given {@code processId} originating from the given {@code nodeId}.
161     * <p>
162     * The query is done in unrestricted mode and so the documents linked to the tasks are detached.
163     *
164     * @since 5.7
165     */
166    List<Task> getAllTaskInstances(String processId, String nodeId, CoreSession session);
167
168}