001/*
002 * (C) Copyright 2009 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 *     arussel
016 */
017package org.nuxeo.ecm.platform.routing.api;
018
019import java.io.Serializable;
020import java.util.Map;
021
022import org.nuxeo.ecm.core.api.CoreSession;
023import org.nuxeo.ecm.core.api.DocumentModel;
024import org.nuxeo.ecm.core.api.DocumentModelList;
025import org.nuxeo.ecm.core.lifecycle.event.BulkLifeCycleChangeListener;
026
027/**
028 * An element of a {@link DocumentRoute}
029 *
030 * @author arussel
031 */
032public interface DocumentRouteElement extends Serializable {
033
034    /**
035     * The lifecycle state of an element
036     */
037    enum ElementLifeCycleState {
038        draft, validated, ready, running, done, canceled
039    }
040
041    /**
042     * The transition of the lifecycle state.
043     */
044    enum ElementLifeCycleTransistion {
045        toValidated, toReady, toRunning, toDone, backToReady, toCanceled, toDraft
046    }
047
048    /**
049     * Return the list of documents that this route processes.
050     *
051     * @param session the session used to fetch the documents
052     * @return
053     */
054    DocumentModelList getAttachedDocuments(CoreSession session);
055
056    /**
057     * Return the DocumentRoute this element is part of.
058     *
059     * @param session The session use to fetch the route.
060     * @return
061     */
062    DocumentRoute getDocumentRoute(CoreSession session);
063
064    /**
065     * if the route this element is part of has been validated.
066     *
067     * @return
068     */
069    boolean isValidated();
070
071    /**
072     * if this element is ready.
073     *
074     * @return
075     */
076    boolean isReady();
077
078    /**
079     * if this route is done.
080     *
081     * @return
082     */
083    boolean isDone();
084
085    /**
086     * if this route is running.
087     *
088     * @return
089     */
090    boolean isRunning();
091
092    /**
093     * if this route is draft.
094     *
095     * @return
096     */
097    boolean isDraft();
098
099    /**
100     * The name of this element.
101     *
102     * @return
103     */
104    String getName();
105
106    /**
107     * the description of this element.
108     *
109     * @return
110     */
111    String getDescription();
112
113    /**
114     * Execute this element. If this is a step, it will run the operation, if this is a containter it will run its
115     * children.
116     *
117     * @param session
118     */
119    void run(CoreSession session);
120
121    /**
122     * Execute this element. If this is a step, it will run the operation, if this is a container it will run its
123     * children.
124     *
125     * @param session
126     * @param map the values to pass as initial workflow variables
127     */
128    void run(CoreSession session, Map<String, Serializable> map);
129
130    /**
131     * Resumes execution on a route node.
132     *
133     * @param session the session
134     * @param nodeId the node id to resume on
135     * @param taskId the task id
136     * @param data the data coming from UI form
137     * @param status the id of the button clicked to submit the related task form
138     * @since 5.6
139     */
140    void resume(CoreSession session, String nodeId, String taskId, Map<String, Object> data, String status);
141
142    /**
143     * Set this element to the validate state and put it in read only mode.
144     *
145     * @param session
146     */
147    void validate(CoreSession session);
148
149    /**
150     * Get the underlying document representing this element.
151     *
152     * @return
153     */
154    DocumentModel getDocument();
155
156    /**
157     * save the document representing this DocumentRoute.
158     *
159     * @param session
160     */
161    void save(CoreSession session);
162
163    /**
164     * set this element as validated.
165     */
166    void setValidated(CoreSession session);
167
168    /**
169     * set this element as ready.
170     */
171    void setReady(CoreSession session);
172
173    /**
174     * set this element as running.
175     */
176    void setRunning(CoreSession session);
177
178    /**
179     * set this element as done.
180     */
181    void setDone(CoreSession session);
182
183    /**
184     * remove write rights to everyone but the administrators.
185     */
186    void setReadOnly(CoreSession session);
187
188    /**
189     * make this element follow a transition.
190     *
191     * @param transition the followed transition.
192     * @param session the session used to follow the transition.
193     * @param recursive If this element has children, do we recurse the follow transition.
194     * @see BulkLifeCycleChangeListener
195     */
196    void followTransition(ElementLifeCycleTransistion transition, CoreSession session, boolean recursive);
197
198    /**
199     * If this session can validate the step.
200     */
201    boolean canValidateStep(CoreSession session);
202
203    /**
204     * make this user or group a validator for this step.
205     */
206    void setCanValidateStep(CoreSession session, String userOrGroup);
207
208    /**
209     * If this session can update this step.
210     */
211    boolean canUpdateStep(CoreSession session);
212
213    /**
214     * make this user or group a step updater.
215     */
216    void setCanUpdateStep(CoreSession session, String userOrGroup);
217
218    /**
219     * make this user or group a step reader.
220     */
221    void setCanReadStep(CoreSession session, String userOrGroup);
222
223    /**
224     * If this session can delete this step.
225     */
226    boolean canDeleteStep(CoreSession session);
227
228    /**
229     * If this step can be undone. Default is to allow undoing only if the parent folder is running.
230     */
231    boolean canUndoStep(CoreSession session);
232
233    /**
234     * make this user or group step deleter.
235     */
236    void setCanDeleteStep(CoreSession session, String userOrGroup);
237
238    /**
239     * Set the step back to the ready state from running or done. This method only modify the step state, it does not
240     * run any other action (such as undoing the step action)
241     */
242    void backToReady(CoreSession session);
243
244    /**
245     * Set the step to a cancel step. This method only modify the state of this element and does not run any other
246     * action.
247     */
248    void setCanceled(CoreSession session);
249
250    /**
251     * Cancel this element.
252     *
253     * @param session
254     */
255    void cancel(CoreSession session);
256
257    /**
258     * @return
259     */
260    boolean isCanceled();
261
262    /**
263     * @return true
264     */
265    boolean isModifiable();
266
267    /**
268     * @since 7.2
269     */
270    String getTitle();
271}