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     */
055    DocumentModelList getAttachedDocuments(CoreSession session);
056
057    /**
058     * Return the DocumentRoute this element is part of.
059     *
060     * @param session The session use to fetch the route.
061     */
062    DocumentRoute getDocumentRoute(CoreSession session);
063
064    /**
065     * if the route this element is part of has been validated.
066     */
067    boolean isValidated();
068
069    /**
070     * if this element is ready.
071     */
072    boolean isReady();
073
074    /**
075     * if this route is done.
076     */
077    boolean isDone();
078
079    /**
080     * if this route is running.
081     */
082    boolean isRunning();
083
084    /**
085     * if this route is draft.
086     */
087    boolean isDraft();
088
089    /**
090     * The name of this element.
091     */
092    String getName();
093
094    /**
095     * the description of this element.
096     */
097    String getDescription();
098
099    /**
100     * Execute this element. If this is a step, it will run the operation, if this is a containter it will run its
101     * children.
102     */
103    void run(CoreSession session);
104
105    /**
106     * Execute this element. If this is a step, it will run the operation, if this is a container it will run its
107     * children.
108     *
109     * @param map the values to pass as initial workflow variables
110     */
111    void run(CoreSession session, Map<String, Serializable> map);
112
113    /**
114     * Resumes execution on a route node.
115     *
116     * @param session the session
117     * @param nodeId the node id to resume on
118     * @param taskId the task id
119     * @param data the data coming from UI form
120     * @param status the id of the button clicked to submit the related task form
121     * @since 5.6
122     */
123    void resume(CoreSession session, String nodeId, String taskId, Map<String, Object> data, String status);
124
125    /**
126     * Set this element to the validate state and put it in read only mode.
127     */
128    void validate(CoreSession session);
129
130    /**
131     * Get the underlying document representing this element.
132     */
133    DocumentModel getDocument();
134
135    /**
136     * save the document representing this DocumentRoute.
137     */
138    void save(CoreSession session);
139
140    /**
141     * set this element as validated.
142     */
143    void setValidated(CoreSession session);
144
145    /**
146     * set this element as ready.
147     */
148    void setReady(CoreSession session);
149
150    /**
151     * set this element as running.
152     */
153    void setRunning(CoreSession session);
154
155    /**
156     * set this element as done.
157     */
158    void setDone(CoreSession session);
159
160    /**
161     * remove write rights to everyone but the administrators.
162     */
163    void setReadOnly(CoreSession session);
164
165    /**
166     * make this element follow a transition.
167     *
168     * @param transition the followed transition.
169     * @param session the session used to follow the transition.
170     * @param recursive If this element has children, do we recurse the follow transition.
171     * @see BulkLifeCycleChangeListener
172     */
173    void followTransition(ElementLifeCycleTransistion transition, CoreSession session, boolean recursive);
174
175    /**
176     * If this session can validate the step.
177     */
178    boolean canValidateStep(CoreSession session);
179
180    /**
181     * make this user or group a validator for this step.
182     */
183    void setCanValidateStep(CoreSession session, String userOrGroup);
184
185    /**
186     * If this session can update this step.
187     */
188    boolean canUpdateStep(CoreSession session);
189
190    /**
191     * make this user or group a step updater.
192     */
193    void setCanUpdateStep(CoreSession session, String userOrGroup);
194
195    /**
196     * make this user or group a step reader.
197     */
198    void setCanReadStep(CoreSession session, String userOrGroup);
199
200    /**
201     * If this session can delete this step.
202     */
203    boolean canDeleteStep(CoreSession session);
204
205    /**
206     * If this step can be undone. Default is to allow undoing only if the parent folder is running.
207     */
208    boolean canUndoStep(CoreSession session);
209
210    /**
211     * make this user or group step deleter.
212     */
213    void setCanDeleteStep(CoreSession session, String userOrGroup);
214
215    /**
216     * Set the step back to the ready state from running or done. This method only modify the step state, it does not
217     * run any other action (such as undoing the step action)
218     */
219    void backToReady(CoreSession session);
220
221    /**
222     * Set the step to a cancel step. This method only modify the state of this element and does not run any other
223     * action.
224     */
225    void setCanceled(CoreSession session);
226
227    /**
228     * Cancel this element.
229     */
230    void cancel(CoreSession session);
231
232    boolean isCanceled();
233
234    /**
235     * @return true
236     */
237    boolean isModifiable();
238
239    /**
240     * @since 7.2
241     */
242    String getTitle();
243}