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