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 */
019package org.apache.wiki.workflow;
020
021import org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.exceptions.WikiException;
023import org.apache.wiki.event.WikiEventEmitter;
024import org.apache.wiki.event.WorkflowEvent;
025
026import java.io.Serializable;
027import java.security.Principal;
028import java.util.*;
029import java.util.concurrent.ConcurrentHashMap;
030import java.util.concurrent.atomic.AtomicInteger;
031
032
033/**
034 * <p>
035 * Sequence of {@link Step} objects linked together. Workflows are always initialized with a message key that denotes the name of the
036 * Workflow, and a Principal that represents its owner.
037 * </p>
038 * <h2>Workflow lifecycle</h2>
039 * A Workflow's state (obtained by {@link #getCurrentState()}) will be one of the following:
040 * </p>
041 * <ul>
042 * <li><strong>{@link #CREATED}</strong>: after the Workflow has been instantiated, but before it has been started using the {@link #start(Context)}
043 * method.</li>
044 * <li><strong>{@link #RUNNING}</strong>: after the Workflow has been started using the {@link #start(Context)} method, but before it has
045 * finished processing all Steps. Note that a Workflow can only be started once; attempting to start it again results in an
046 * IllegalStateException. Callers can place the Workflow into the WAITING state by calling {@link #waitstate()}.</li>
047 * <li><strong>{@link #WAITING}</strong>: when the Workflow has temporarily paused, for example because of a pending Decision. Once the
048 * responsible actor decides what to do, the caller can change the Workflow back to the RUNNING state by calling the {@link #restart(Context)}
049 * method (this is done automatically by the Decision class, for instance, when the {@link Decision#decide(Outcome, Context)} method is invoked)</li>
050 * <li><strong>{@link #COMPLETED}</strong>: after the Workflow has finished processing all Steps, without errors.</li>
051 * <li><strong>{@link #ABORTED}</strong>: if a Step has elected to abort the Workflow.</li>
052 * </ul>
053 * <h2>Steps and processing algorithm</h2>
054 * <p>
055 * Workflow Step objects can be of type {@link Decision}, {@link Task} or other Step subclasses. Decisions require user input, while Tasks
056 * do not. See the {@link Step} class for more details.
057 * </p>
058 * <p>
059 * After instantiating a new Workflow (but before telling it to {@link #start(Context)}), calling classes should specify the first Step by
060 * executing the {@link #setFirstStep(Step)} method. Additional Steps can be chained by invoking the first step's
061 * {@link Step#addSuccessor(Outcome, Step)} method.
062 * </p>
063 * <p>
064 * When a Workflow's <code>start</code> method is invoked, the Workflow retrieves the first Step and processes it. This Step, and subsequent
065 * ones, are processed as follows:
066 * </p>
067 * <ul>
068 * <li>The Step's {@link Step#start()} method executes, which sets the start time.</li>
069 * <li>The Step's {@link Step#execute(Context)} method is called to begin processing, which will return an Outcome to indicate completion,
070 * continuation or errors:</li>
071 * <ul>
072 * <li>{@link Outcome#STEP_COMPLETE} indicates that the execution method ran without errors, and that the Step should be considered
073 * "completed."</li>
074 * <li>{@link Outcome#STEP_CONTINUE} indicates that the execution method ran without errors, but that the Step is not "complete" and should
075 * be put into the WAITING state.</li>
076 * <li>{@link Outcome#STEP_ABORT} indicates that the execution method encountered errors, and should abort the Step <em>and</em> the
077 * Workflow as a whole. When this happens, the Workflow will set the current Step's Outcome to {@link Outcome#STEP_ABORT} and invoke the
078 * Workflow's {@link #abort(Context)} method. The Step's processing errors, if any, can be retrieved by {@link Step#getErrors()}.</li>
079 * </ul>
080 * <li>The Outcome of the <code>execute</code> method also affects what happens next. Depending on the result (and assuming the Step did
081 * not abort), the Workflow will either move on to the next Step or put the Workflow into the {@link Workflow#WAITING} state:</li>
082 * <ul>
083 * <li>If the Outcome denoted "completion" (<em>i.e.</em>, its {@link Step#isCompleted()} method returns <code>true</code>) then the Step
084 * is considered complete; the Workflow looks up the next Step by calling the current Step's {@link Step#getSuccessor(Outcome)} method. If
085 * <code>successor()</code> returns a non-<code>null</code> Step, the return value is marked as the current Step and added to the Workflow's
086 * Step history. If <code>successor()</code> returns <code>null</code>, then the Workflow has no more Steps and it enters the
087 * {@link #COMPLETED} state.</li>
088 * <li>If the Outcome did not denote "completion" (<em>i.e.</em>, its {@link Step#isCompleted()} method returns <code>false</code>), then
089 * the Step still has further work to do. The Workflow enters the {@link #WAITING} state and stops further processing until a caller
090 * restarts it.</li>
091 * </ul>
092 * </ul>
093 * </p>
094 * <p>
095 * The currently executing Step can be obtained by {@link #getCurrentStep()}. The actor for the current Step is returned by
096 * {@link #getCurrentActor()}.
097 * </p>
098 * <p>
099 * To provide flexibility for specific implementations, the Workflow class provides two additional features that enable Workflow
100 * participants (<em>i.e.</em>, Workflow subclasses and Step/Task/Decision subclasses) to share context and state information. These two
101 * features are <em>named attributes</em> and <em>message arguments</em>:
102 * </p>
103 * <ul>
104 * <li><strong>Named attributes</strong> are simple key-value pairs that Workflow participants can get or set. Keys are Strings; values
105 * can be any Object. Named attributes are set with {@link #setAttribute(String, Serializable)} and retrieved with {@link #getAttribute(String)}.</li>
106 * <li><strong>Message arguments</strong> are used in combination with JSPWiki's {@link org.apache.wiki.i18n.InternationalizationManager} to
107 * create language-independent user interface messages. The message argument array is retrieved via {@link #getMessageArguments()}; the
108 * first two array elements will always be these: a String representing work flow owner's name, and a String representing the current
109 * actor's name. Workflow participants can add to this array by invoking {@link #addMessageArgument(Serializable)}.</li>
110 * </ul>
111 * <h2>Example</h2>
112 * <p>
113 * Workflow Steps can be very powerful when linked together. JSPWiki provides two abstract subclasses classes that you can use to build
114 * your own Workflows: Tasks and Decisions. As noted, Tasks are Steps that execute without user intervention, while Decisions require
115 * actors (<em>aka</em> Principals) to take action. Decisions and Tasks can be mixed freely to produce some highly elaborate branching
116 * structures.
117 * </p>
118 * <p>
119 * Here is a simple case. For example, suppose you would like to create a Workflow that (a) executes a initialization Task, (b) pauses to
120 * obtain an approval Decision from a user in the Admin group, and if approved, (c) executes a "finish" Task. Here's sample code that
121 * illustrates how to do it:
122 * </p>
123 *
124 * <pre>
125 *    // Create workflow; owner is current user
126 * 1  Workflow workflow = new Workflow( &quot; workflow.myworkflow &quot;, context.getCurrentUser() );
127 *
128 *    // Create custom initialization task
129 * 2  Step initTask = new InitTask( this );
130 *
131 *    // Create finish task
132 * 3  Step finishTask = new FinishTask( this );
133 *
134 *    // Create an intermediate decision step
135 * 4  Principal actor = new GroupPrincipal( &quot;Admin&quot; );
136 * 5  Step decision = new SimpleDecision( this, &quot;decision.AdminDecision&quot;, actor );
137 *
138 *    // Hook the steps together
139 * 6  initTask.addSuccessor( Outcome.STEP_COMPLETE, decision );
140 * 7  decision.addSuccessor( Outcome.DECISION_APPROVE, finishTask );
141 *
142 *    // Set workflow's first step
143 * 8  workflow.setFirstStep( initTask );
144 * </pre>
145 *
146 * <p>
147 * Some comments on the source code:
148 * </p>
149 * <ul>
150 * <li>Line 1 instantiates the workflow with a sample message key and designated owner Principal, in this case the current wiki user</li>
151 * <li>Lines 2 and 3 instantiate the custom Task subclasses, which contain the business logic</li>
152 * <li>Line 4 creates the relevant GroupPrincipal for the <code>Admin</code> group, who will be the actor in the Decision step</li>
153 * <li>Line 5 creates the Decision step, passing the Workflow, sample message key, and actor in the constructor</li>
154 * <li>Line 6 specifies that if the InitTask's Outcome signifies "normal completion" (STEP_COMPLETE), the SimpleDecision step should be
155 * invoked next</li>
156 * <li>Line 7 specifies that if the actor (anyone possessing the <code>Admin</code> GroupPrincipal) selects DECISION_APPROVE, the FinishTask
157 * step should be invoked</li>
158 * <li>Line 8 adds the InitTask (and all of its successor Steps, nicely wired together) to the workflow</li>
159 * </ul>
160 */
161public class Workflow implements Serializable {
162
163    private static final long serialVersionUID = 5228149040690660032L;
164
165    private static final AtomicInteger idsCounter = new AtomicInteger( 1 );
166
167    /** ID value: the workflow ID has not been set. */
168    public static final int ID_NOT_SET = 0;
169
170    /** State value: Workflow completed all Steps without errors. */
171    public static final int COMPLETED = 50;
172
173    /** State value: Workflow aborted before completion. */
174    public static final int ABORTED = 40;
175
176    /** State value: Workflow paused, typically because a Step returned an Outcome that doesn't signify "completion." */
177    public static final int WAITING = 30;
178
179    /** State value: Workflow started, and is running. */
180    public static final int RUNNING = -1;
181
182    /** State value: Workflow instantiated, but not started. */
183    public static final int CREATED = -2;
184
185    /** attribute map. */
186    private Map< String, Serializable > m_attributes;
187
188    /** The initial Step for this Workflow. */
189    private Step m_firstStep;
190
191    /** Flag indicating whether the Workflow has started yet. */
192    private boolean m_started;
193
194    private final LinkedList< Step > m_history;
195
196    private int m_id;
197
198    private final String m_key;
199
200    private final Principal m_owner;
201
202    private final List<Serializable> m_messageArgs;
203
204    private int m_state;
205
206    private Step m_currentStep;
207
208    /**
209     * Constructs a new Workflow object with a supplied message key, owner Principal, and undefined unique identifier {@link #ID_NOT_SET}.
210     * Once instantiated the Workflow is considered to be in the {@link #CREATED} state; a caller must explicitly invoke the
211     * {@link #start(Context)} method to begin processing.
212     *
213     * @param messageKey the message key used to construct a localized workflow name, such as <code>workflow.saveWikiPage</code>
214     * @param owner the Principal who owns the Workflow. Typically, this is the user who created and submitted it
215     */
216    public Workflow( final String messageKey, final Principal owner ) {
217        m_attributes = new ConcurrentHashMap<>();
218        m_currentStep = null;
219        m_history = new LinkedList<>();
220        m_id = idsCounter.getAndIncrement();
221        m_key = messageKey;
222        m_messageArgs = new ArrayList<>();
223        m_owner = owner;
224        m_started = false;
225        m_state = CREATED;
226        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.CREATED );
227    }
228
229    /**
230     * Aborts the Workflow by setting the current Step's Outcome to {@link Outcome#STEP_ABORT}, and the Workflow's overall state to
231     * {@link #ABORTED}. It also appends the aborted Step into the workflow history, and sets the current step to <code>null</code>.
232     * If the Step is a Decision, it is removed from the DecisionQueue. This method can be called at any point in the lifecycle prior
233     * to completion, but it cannot be called twice. It finishes by calling the {@link #cleanup()} method to flush retained objects.
234     * If the Workflow had been previously aborted, this method throws an IllegalStateException.
235     */
236    public final synchronized void abort( final Context context ) {
237        // Check corner cases: previous abort or completion
238        if( m_state == ABORTED ) {
239            throw new IllegalStateException( "The workflow has already been aborted." );
240        }
241        if( m_state == COMPLETED ) {
242            throw new IllegalStateException( "The workflow has already completed." );
243        }
244
245        if( m_currentStep != null ) {
246            if( m_currentStep instanceof Decision ) {
247                WikiEventEmitter.fireWorkflowEvent( m_currentStep, WorkflowEvent.DQ_REMOVAL, context );
248            }
249            m_currentStep.setOutcome( Outcome.STEP_ABORT );
250            m_history.addLast( m_currentStep );
251        }
252        m_state = ABORTED;
253        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.ABORTED );
254        cleanup();
255    }
256
257    /**
258     * Appends a message argument object to the array returned by {@link #getMessageArguments()}. The object <em>must</em> be an type
259     * used by the {@link java.text.MessageFormat}: String, Date, or Number (BigDecimal, BigInteger, Byte, Double, Float, Integer, Long,
260     * Short). If the object is not of type String, Number or Date, this method throws an IllegalArgumentException.
261     *
262     * @param obj the object to add
263     */
264    public final void addMessageArgument( final Serializable obj ) {
265        if( obj instanceof String || obj instanceof Date || obj instanceof Number ) {
266            m_messageArgs.add( obj );
267            return;
268        }
269        throw new IllegalArgumentException( "Message arguments must be of type String, Date or Number." );
270    }
271
272    /**
273     * Returns the actor Principal responsible for the current Step. If there is
274     * no current Step, this method returns <code>null</code>.
275     *
276     * @return the current actor
277     */
278    public final synchronized Principal getCurrentActor() {
279        if( m_currentStep == null ) {
280            return null;
281        }
282        return m_currentStep.getActor();
283    }
284
285    /**
286     * Returns the workflow state: {@link #CREATED}, {@link #RUNNING}, {@link #WAITING}, {@link #COMPLETED} or {@link #ABORTED}.
287     *
288     * @return the workflow state
289     */
290    public final int getCurrentState()
291    {
292        return m_state;
293    }
294
295    /**
296     * Returns the current Step, or <code>null</code> if the workflow has not started or already completed.
297     *
298     * @return the current step
299     */
300    public final Step getCurrentStep()
301    {
302        return m_currentStep;
303    }
304
305    /**
306     * Retrieves a named Object associated with this Workflow. If the Workflow has completed or aborted, this method always returns
307     * <code>null</code>.
308     *
309     * @param attr the name of the attribute
310     * @return the value
311     */
312    public final Object getAttribute( final String attr ) {
313        return m_attributes.get( attr );
314    }
315
316    /**
317     * Retrieves workflow's attributes.
318     *
319     * @return workflow's attributes.
320     */
321    public final Map< String, Serializable > getAttributes() {
322        return m_attributes;
323    }
324
325    /**
326     * The end time for this Workflow, expressed as a system time number. This value is equal to the end-time value returned by the final
327     * Step's {@link Step#getEndTime()} method, if the workflow has completed. Otherwise, this method returns {@link Step#TIME_NOT_SET}.
328     *
329     * @return the end time
330     */
331    public final Date getEndTime() {
332        if( isCompleted() ) {
333            final Step last = m_history.getLast();
334            if( last != null ) {
335                return last.getEndTime();
336            }
337        }
338        return Step.TIME_NOT_SET;
339    }
340
341    /**
342     * Returns the unique identifier for this Workflow. If not set, this method returns ID_NOT_SET ({@value #ID_NOT_SET}).
343     *
344     * @return the unique identifier
345     */
346    public final synchronized int getId()
347    {
348        return m_id;
349    }
350
351    /**
352     * <p>
353     * Returns an array of message arguments, used by {@link java.text.MessageFormat} to create localized messages. The first
354     * two array elements will always be these:
355     * </p>
356     * <ul>
357     * <li>String representing the name of the workflow owner (<em>i.e.</em>,{@link #getOwner()})</li>
358     * <li>String representing the name of the current actor (<em>i.e.</em>,{@link #getCurrentActor()}).
359     * If the current step is <code>null</code> because the workflow hasn't started or has already
360     * finished, the value of this argument will be a dash character (<code>-</code>)</li>
361     * </ul>
362     * <p>
363     * Workflow and Step subclasses are free to append items to this collection with {@link #addMessageArgument(Serializable)}.
364     * </p>
365     *
366     * @return the array of message arguments
367     */
368    public final Serializable[] getMessageArguments() {
369        final List< Serializable > args = new ArrayList<>();
370        args.add( m_owner.getName() );
371        final Principal actor = getCurrentActor();
372        args.add( actor == null ? "-" : actor.getName() );
373        args.addAll( m_messageArgs );
374        return args.toArray( new Serializable[0] );
375    }
376
377    /**
378     * Returns an i18n message key for the name of this workflow; for example,
379     * <code>workflow.saveWikiPage</code>.
380     *
381     * @return the name
382     */
383    public final String getMessageKey()
384    {
385        return m_key;
386    }
387
388    /**
389     * The owner Principal on whose behalf this Workflow is being executed; that is, the user who created the workflow.
390     *
391     * @return the name of the Principal who owns this workflow
392     */
393    public final Principal getOwner()
394    {
395        return m_owner;
396    }
397
398    /**
399     * The start time for this Workflow, expressed as a system time number. This value is equal to the start-time value returned by the
400     * first Step's {@link Step#getStartTime()} method, if the workflow has started already. Otherwise, this method returns
401     * {@link Step#TIME_NOT_SET}.
402     *
403     * @return the start time
404     */
405    public final Date getStartTime()
406    {
407        return isStarted() ? m_firstStep.getStartTime() : Step.TIME_NOT_SET;
408    }
409
410    /**
411     * Returns a Step history for this Workflow as a List, chronologically, from the first Step to the currently executing one. The first
412     * step is the first item in the array. If the Workflow has not started, this method returns a zero-length array.
413     *
414     * @return an array of Steps representing those that have executed, or are currently executing
415     */
416    public final List< Step > getHistory()
417    {
418        return Collections.unmodifiableList( m_history );
419    }
420
421    /**
422     * Returns <code>true</code> if the workflow had been previously aborted.
423     *
424     * @return the result
425     */
426    public final boolean isAborted()
427    {
428        return m_state == ABORTED;
429    }
430
431    /**
432     * Determines whether this Workflow is completed; that is, if it has no additional Steps to perform. If the last Step in the workflow is
433     * finished, this method will return <code>true</code>.
434     *
435     * @return <code>true</code> if the workflow has been started but has no more steps to perform; <code>false</code> if not.
436     */
437    public final synchronized boolean isCompleted() {
438        // If current step is null, then we're done
439        return m_started && m_state == COMPLETED;
440    }
441
442    /**
443     * Determines whether this Workflow has started; that is, its {@link #start(Context)} method has been executed.
444     *
445     * @return <code>true</code> if the workflow has been started; <code>false</code> if not.
446     */
447    public final boolean isStarted()
448    {
449        return m_started;
450    }
451
452    /**
453     * Convenience method that returns the predecessor of the current Step. This method simply examines the Workflow history and returns the
454     * second-to-last Step.
455     *
456     * @return the predecessor, or <code>null</code> if the first Step is currently executing
457     */
458    public final Step getPreviousStep()
459    {
460        return previousStep( m_currentStep );
461    }
462
463    /**
464     * Restarts the Workflow from the {@link #WAITING} state and puts it into the {@link #RUNNING} state again. If the Workflow had not
465     * previously been paused, this method throws an IllegalStateException. If any of the Steps in this Workflow throw a WikiException,
466     * the Workflow will abort and propagate the exception to callers.
467     *
468     * @param context current wiki context
469     * @throws WikiException if the current task's {@link Task#execute( Context )} method throws an exception
470     */
471    public final synchronized void restart( final Context context ) throws WikiException {
472        if( m_state != WAITING ) {
473            throw new IllegalStateException( "Workflow is not paused; cannot restart." );
474        }
475        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.STARTED );
476        m_state = RUNNING;
477        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.RUNNING );
478
479        // Process current step
480        try {
481            processCurrentStep( context );
482        } catch( final WikiException e ) {
483            abort( context );
484            throw e;
485        }
486    }
487
488    /**
489     * Temporarily associates an object with this Workflow, as a named attribute, for the duration of workflow execution. The passed
490     * object can be anything required by an executing Step, although it <em>should</em> be serializable. Note that when the workflow
491     * completes or aborts, all attributes will be cleared.
492     *
493     * @param attr the attribute name
494     * @param obj  the value
495     */
496    public final void setAttribute( final String attr, final Serializable obj ) {
497        m_attributes.put( attr, obj );
498    }
499
500    /**
501     * Sets the first Step for this Workflow, which will be executed immediately
502     * after the {@link #start( Context )} method executes. Note than the Step is not
503     * marked as the "current" step or added to the Workflow history until the
504     * {@link #start( Context )} method is called.
505     *
506     * @param step the first step for the workflow
507     */
508    public final synchronized void setFirstStep( final Step step )
509    {
510        m_firstStep = step;
511    }
512
513    /**
514     * Sets the unique identifier for this Workflow.
515     *
516     * @param id the unique identifier
517     */
518    public final synchronized void setId( final int id )
519    {
520        this.m_id = id;
521    }
522
523    /**
524     * Starts the Workflow and sets the state to {@link #RUNNING}. If the Workflow has already been started (or previously aborted), this
525     * method returns an {@linkplain IllegalStateException}. If any of the Steps in this Workflow throw a WikiException, the Workflow will
526     * abort and propagate the exception to callers.
527     *
528     * @param context current wiki context.
529     * @throws WikiException if the current Step's {@link Step#start()} method throws an exception of any kind
530     */
531    public final synchronized void start( final Context context ) throws WikiException {
532        if( m_state == ABORTED ) {
533            throw new IllegalStateException( "Workflow cannot be started; it has already been aborted." );
534        }
535        if( m_started ) {
536            throw new IllegalStateException( "Workflow has already started." );
537        }
538        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.STARTED );
539        m_started = true;
540        m_state = RUNNING;
541
542        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.RUNNING );
543        // Mark the first step as the current one & add to history
544        m_currentStep = m_firstStep;
545        m_history.add( m_currentStep );
546
547        // Process current step
548        try {
549            processCurrentStep( context );
550        } catch( final WikiException e ) {
551            abort( context );
552            throw e;
553        }
554    }
555
556    /**
557     * Sets the Workflow in the {@link #WAITING} state. If the Workflow is not running or has already been paused, this method throws an
558     * IllegalStateException. Once paused, the Workflow can be un-paused by executing the {@link #restart(Context)} method.
559     */
560    public final synchronized void waitstate() {
561        if ( m_state != RUNNING ) {
562            throw new IllegalStateException( "Workflow is not running; cannot pause." );
563        }
564        m_state = WAITING;
565        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.WAITING );
566    }
567
568    /**
569     * Clears the attribute map and sets the current step field to <code>null</code>.
570     */
571    protected void cleanup() {
572        m_currentStep = null;
573        m_attributes = null;
574    }
575
576    /**
577     * Protected helper method that changes the Workflow's state to {@link #COMPLETED} and sets the current Step to <code>null</code>. It
578     * calls the {@link #cleanup()} method to flush retained objects. This method will no-op if it has previously been called.
579     */
580    protected final synchronized void complete() {
581        if( !isCompleted() ) {
582            m_state = COMPLETED;
583            WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.COMPLETED );
584            cleanup();
585        }
586    }
587
588    /**
589     * Protected method that returns the predecessor for a supplied Step.
590     *
591     * @param step the Step for which the predecessor is requested
592     * @return its predecessor, or <code>null</code> if the first Step was supplied.
593     */
594    protected final Step previousStep( final Step step ) {
595        final int index = m_history.indexOf( step );
596        return index < 1 ? null : m_history.get( index - 1 );
597    }
598
599    /**
600     * Protected method that processes the current Step by calling {@link Step#execute( Context )}. If the <code>execute</code> throws an
601     * exception, this method will propagate the exception immediately to callers without aborting.
602     *
603     * @throws WikiException if the current Step's {@link Step#start()} method throws an exception of any kind
604     */
605    protected final void processCurrentStep( final Context context ) throws WikiException {
606        while ( m_currentStep != null ) {
607            // Start and execute the current step
608            if( !m_currentStep.isStarted() ) {
609                m_currentStep.start();
610            }
611            final Outcome result = m_currentStep.execute( context );
612            if( Outcome.STEP_ABORT.equals( result ) ) {
613                abort( context );
614                break;
615            }
616
617            if( !m_currentStep.isCompleted() ) {
618                m_currentStep.setOutcome( result );
619            }
620
621            // Get the execution Outcome; if not complete, pause workflow and exit
622            final Outcome outcome = m_currentStep.getOutcome();
623            if ( !outcome.isCompletion() ) {
624                waitstate();
625                break;
626            }
627
628            // Get the next Step; if null, we're done
629            final Step nextStep = m_currentStep.getSuccessor( outcome );
630            if ( nextStep == null ) {
631                complete();
632                break;
633            }
634
635            // Add the next step to Workflow history, and mark as current
636            m_history.add( nextStep );
637            m_currentStep = nextStep;
638        }
639
640    }
641
642}