001    /* 
002        Licensed to the Apache Software Foundation (ASF) under one
003        or more contributor license agreements.  See the NOTICE file
004        distributed with this work for additional information
005        regarding copyright ownership.  The ASF licenses this file
006        to you under the Apache License, Version 2.0 (the
007        "License"); you may not use this file except in compliance
008        with the License.  You may obtain a copy of the License at
009    
010           http://www.apache.org/licenses/LICENSE-2.0
011    
012        Unless required by applicable law or agreed to in writing,
013        software distributed under the License is distributed on an
014        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015        KIND, either express or implied.  See the License for the
016        specific language governing permissions and limitations
017        under the License.  
018     */
019    package org.apache.wiki.workflow;
020    
021    import java.io.Serializable;
022    import java.security.Principal;
023    import java.util.Collection;
024    import java.util.Date;
025    import java.util.List;
026    
027    import org.apache.wiki.api.exceptions.WikiException;
028    
029    /**
030     * <p>
031     * Discrete unit of work in a Workflow, such as a {@link Decision} or a
032     * {@link Task}. Decisions require user input, while Tasks do not. All Steps,
033     * however, possess these properties:
034     * </p>
035     * <ul>
036     * <li><strong>actor</strong>: the Principal responsible for executing the
037     * Step; returned by {@link Step#getActor()}.</li>
038     * <li><strong>availableOutcomes</strong>: a collection of possible
039     * "outcomes," such as "approve decision" ({@link Outcome#DECISION_APPROVE}),
040     * "reassign decision" ({@link Outcome#DECISION_REASSIGN}), "abort step" ({@link Outcome#STEP_ABORT})
041     * and others. The range of possible Outcomes for the Step is returned by
042     * {@link Step#getAvailableOutcomes()}; see the Outcome class for more details.</li>
043     * <li><strong>errors</strong>: an collection of Strings indicating errors
044     * returned by the Step. These values are returned by {@link Step#getErrors()}.</li>
045     * <li><strong>started</strong> and <strong>completed</strong>: whether the
046     * Step has started/finished. These values are returned by
047     * {@link Step#isStarted()} and {@link Step#isCompleted()}.</li>
048     * <li><strong>startTime</strong> and <strong>endTime</strong>: the time when
049     * the Step started and finished. These values are returned by
050     * {@link Step#getStartTime()} and {@link Step#getEndTime()}, respectively.</li>
051     * <li><strong>workflow</strong>: the parent Workflow. </li>
052     * </ul>
053     * <p>
054     * Steps contain a {@link #getMessageKey()} method that returns a key that can
055     * be used with the {@link org.apache.wiki.i18n.InternationalizationManager}.
056     * See also {@link Workflow#getMessageArguments()}, which is a convenience
057     * method that returns message arguments.
058     * </p>
059     * 
060     * @since 2.5
061     */
062    public interface Step extends Serializable
063    {
064    
065        /**
066         * Adds a successor Step to this one, which will be triggered by a supplied
067         * Outcome. Implementations should respect the order in which Outcomes are
068         * added; {@link #getAvailableOutcomes()} should return them in the same
069         * order they were added.
070         * 
071         * @param outcome
072         *            the Outcome triggering a particular successor Step
073         * @param step
074         *            the Step to associated with this Outcomes (<code>null</code>
075         *            denotes no Steps)
076         */
077        void addSuccessor( Outcome outcome, Step step );
078    
079        /**
080         * Returns a Collection of available outcomes, such as "approve", "deny" or
081         * "reassign", in the order in which they were added via
082         * {@link #addSuccessor(Outcome, Step)}. Concrete implementations should
083         * always return a defensive copy of the outcomes, not the original backing
084         * collection.
085         * 
086         * @return the set of outcomes
087         */
088        Collection getAvailableOutcomes();
089    
090        /**
091         * Returns a List of error strings generated by this Step. If this Step
092         * generated no errors, this method returns a zero-length array.
093         * 
094         * @return the errors
095         */
096        List getErrors();
097    
098        /**
099         * <p>
100         * Executes the processing for this Step and returns an Outcome indicating
101         * if it succeeded ({@link Outcome#STEP_COMPLETE} or
102         * {@link Outcome#STEP_ABORT}). Processing instructions can do just about
103         * anything, such as executing custom business logic or changing the Step's
104         * final outcome via {@link #setOutcome(Outcome)}. A return value of
105         * <code>STEP_COMPLETE</code> indicates that the instructions executed completely,
106         * without errors; <code>STEP_ABORT</code> indicates that the Step and its
107         * parent Workflow should be aborted (that is, fail silently without error).
108         * If the execution step encounters any errors, it should throw a
109         * WikiException or a subclass.
110         * </p>
111         * <p>
112         * Note that successful execution of this methods does not necessarily mean
113         * that the Step is considered "complete"; rather, it just means that it has
114         * executed. Therefore, it is possible that <code>execute</code> could run
115         * multiple times.
116         * </p>
117         * 
118         * @return the result of the Step, expressed as an Outcome
119         * @throws WikiException
120         *             if the step encounters errors while executing
121         */
122        Outcome execute() throws WikiException;
123    
124        /**
125         * The Principal responsible for completing this Step, such as a system user
126         * or actor assigned to a Decision.
127         * 
128         * @return the responsible Principal
129         */
130        Principal getActor();
131    
132        /**
133         * The end time for this Step. This value should be set when the step
134         * completes. Returns {@link Workflow#TIME_NOT_SET} if not completed yet.
135         * 
136         * @return the end time
137         */
138        Date getEndTime();
139    
140        /**
141         * Message key for human-friendly name of this Step, including any parameter
142         * substitutions. By convention, the message prefix should be a lower-case
143         * version of the Step's type, plus a period (<em>e.g.</em>,
144         * <code>task.</code> and <code>decision.</code>).
145         * 
146         * @return the message key for this Step.
147         */
148        String getMessageKey();
149    
150        /**
151         * Returns the message arguments for this Step, typically by delegating to the
152         * parent Workflow's {@link Workflow#getMessageArguments()} method.
153         * 
154         * @return the message arguments.
155         */
156        Serializable[] getMessageArguments();
157    
158        /**
159         * Returns the Outcome of this Step's processing; by default,
160         * {@link Outcome#STEP_CONTINUE}.
161         * 
162         * @return the outcome
163         */
164        Outcome getOutcome();
165    
166        /**
167         * The start time for this Step. Returns {@link Workflow#TIME_NOT_SET} if
168         * not started yet.
169         * 
170         * @return the start time
171         */
172        Date getStartTime();
173    
174        /**
175         * Gets the Workflow that is the parent of this Step.
176         * 
177         * @return the workflow
178         */
179        Workflow getWorkflow();
180    
181        /**
182         * Determines whether the Step is completed; if not, it is by definition
183         * awaiting action by the owner or in process. If a Step has completed, it
184         * <em>must also</em> return a non-<code>null</code> result for
185         * {@link #getOutcome()}.
186         * 
187         * @return <code>true</code> if the Step has completed; <code>false</code>
188         *         if not.
189         */
190        boolean isCompleted();
191    
192        /**
193         * Determines whether the Step has started.
194         * 
195         * @return <code>true</code> if the Step has started; <code>false</code>
196         *         if not.
197         */
198        boolean isStarted();
199    
200        /**
201         * Starts the Step, and sets the start time to the moment when this method
202         * is first invoked. If this Step has already been started, this method
203         * throws an {@linkplain IllegalStateException}. If the Step cannot
204         * be started because the underlying implementation encounters an error,
205         * it the implementation should throw a WikiException.
206         * 
207         * @throws WikiException if the step encounters errors while starting
208         */
209        void start() throws WikiException;
210    
211        /**
212         * Sets the current Outcome for the step. If the Outcome is a "completion"
213         * Outcome, it should also sets the completon time and mark the Step as
214         * complete. Once a Step has been marked complete, this method cannot be
215         * called again. If the supplied Outcome is not in the set returned by
216         * {@link #getAvailableOutcomes()}, or is not  {@link Outcome#STEP_CONTINUE}
217         * or {@link Outcome#STEP_ABORT}, this method returns an
218         * IllegalArgumentException. If the caller attempts to set an Outcome
219         * and the Step has already completed, this method throws an 
220         * IllegalStateException.
221         * 
222         * @param outcome whether the step should be considered completed
223         */
224        void setOutcome( Outcome outcome );
225    
226        /**
227         * Convenience method that returns the owner of the Workflow by delegating
228         * to {@link Workflow#getOwner()}.
229         * 
230         * @return the owner of the Workflow
231         */
232        Principal getOwner();
233    
234        /**
235         * Identifies the next Step for a particular Outcome; if there is no next
236         * Step for this Outcome, this method returns <code>null</code>.
237         * 
238         * @param outcome
239         *            the outcome
240         * @return the next step
241         */
242        Step getSuccessor( Outcome outcome );
243    
244    }