    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}