    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.ArrayList;
    029import java.util.Collections;
    030import java.util.List;
    031import java.util.Map;
    032
    033
    034/**
    035 * <p>
    036 * AbstractStep subclass that asks an actor Principal to choose an Outcome on behalf of an owner (also a Principal). The actor
    037 * "makes the decision" by calling the {@link #decide(Outcome, Context)} method. When this method is called, it will set the Decision's Outcome to
    038 * the one supplied. If the parent Workflow is in the {@link Workflow#WAITING} state, it will be re-started. Any checked WikiExceptions
    039 * thrown by the workflow after re-start will be re-thrown to callers.
    040 * </p>
    041 * <p>
    042 * When a Decision completes, its {@link #isCompleted()} method returns <code>true</code>. It also tells its parent WorkflowManager to
    043 * remove it from the list of pending tasks by calling {@link DecisionQueue#remove(Decision)}.
    044 * </p>
    045 * <p>
    046 * To enable actors to choose an appropriate Outcome, Decisions can store arbitrary key-value pairs called "facts." These facts can be
    047 * presented by the user interface to show details the actor needs to know about. Facts are added by calling classes to the Decision,
    048 * in order of expected presentation, by the {@link #addFact(Fact)} method. They can be retrieved, in order, via {@link #getFacts()}.
    049 * </p>
    050 *
    051 * @since 2.5
    052 */
    053public abstract class Decision extends AbstractStep {
    054
    055    private static final long serialVersionUID = -6835601038263238062L;
    056
    057    private Principal m_actor;
    058
    059    private int m_id;
    060
    061    private final Outcome m_defaultOutcome;
    062
    063    private final List<Fact> m_facts;
    064
    065    /**
    066     * Constructs a new Decision for a required "actor" Principal, having a default Outcome.
    067     *
    068     * @param workflowId the parent workflow id to set
    069     * @param workflowContext the parent workflow context to set
    070     * @param messageKey the i18n message key that represents the message the actor will see
    071     * @param actor the Principal (<em>e.g.</em>, a WikiPrincipal, Role, GroupPrincipal) who is required to select an appropriate Outcome
    072     * @param defaultOutcome the Outcome that the user interface will recommend as the default choice
    073     */
    074    public Decision( final int workflowId, final Map< String, Serializable > workflowContext, final String messageKey, final Principal actor, final Outcome defaultOutcome ) {
    075        super( workflowId, workflowContext, messageKey );
    076        m_actor = actor;
    077        m_defaultOutcome = defaultOutcome;
    078        m_facts = new ArrayList<>();
    079        addSuccessor( defaultOutcome, null );
    080    }
    081
    082    /**
    083     * Appends a Fact to the list of Facts associated with this Decision.
    084     *
    085     * @param fact the new fact to add
    086     */
    087    public final void addFact( final Fact fact )
    088    {
    089        m_facts.add( fact );
    090    }
    091
    092    /**
    093     * <p>
    094     * Sets this Decision's outcome, and restarts the parent Workflow if it is
    095     * in the {@link Workflow#WAITING} state and this Decision is its currently
    096     * active Step. Any checked WikiExceptions thrown by the workflow after
    097     * re-start will be re-thrown to callers.
    098     * </p>
    099     * <p>
    100     * This method cannot be invoked if the Decision is not the current Workflow
    101     * step; all other invocations will throw an IllegalStateException. If the
    102     * Outcome supplied to this method is one one of the Outcomes returned by
    103     * {@link #getAvailableOutcomes()}, an IllegalArgumentException will be
    104     * thrown.
    105     * </p>
    106     *
    107     * @param outcome the Outcome of the Decision
    108     * @param context wiki context of the Decision
    109     * @throws WikiException if the act of restarting the Workflow throws an exception
    110     */
    111    public void decide( final Outcome outcome, final Context context ) throws WikiException {
    112        super.setOutcome( outcome );
    113        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.DQ_REMOVAL, context );
    114    }
    115
    116    /**
    117     * Default implementation that always returns {@link Outcome#STEP_CONTINUE} if the current Outcome isn't a completion (which will be
    118     * true if the {@link #decide(Outcome, Context)} method hasn't been executed yet. This method will also add the Decision to the associated
    119     * DecisionQueue.
    120     *
    121     * @return the Outcome of the execution
    122     * @throws WikiException never
    123     */
    124    @Override
    125    public Outcome execute(final Context context ) throws WikiException {
    126        if( getOutcome().isCompletion() ) {
    127            return getOutcome();
    128        }
    129
    130        // Put decision in the DecisionQueue
    131        WikiEventEmitter.fireWorkflowEvent( this, WorkflowEvent.DQ_ADDITION );
    132
    133        // Indicate we are waiting for user input
    134        return Outcome.STEP_CONTINUE;
    135    }
    136
    137    /**
    138     * {@inheritDoc}
    139     */
    140    @Override
    141    public final Principal getActor() {
    142        return m_actor;
    143    }
    144
    145    /**
    146     * Returns the default or suggested outcome, which must be one of those returned by {@link #getAvailableOutcomes()}. This method is
    147     * guaranteed to return a non-<code>null</code> Outcome.
    148     *
    149     * @return the default outcome.
    150     */
    151    public Outcome getDefaultOutcome() {
    152        return m_defaultOutcome;
    153    }
    154
    155    /**
    156     * Returns the Facts associated with this Decision, in the order in which they were added.
    157     *
    158     * @return the list of Facts
    159     */
    160    public final List< Fact > getFacts() {
    161        return Collections.unmodifiableList( m_facts );
    162    }
    163
    164    /**
    165     * Returns the unique identifier for this Decision. Normally, this ID is programmatically assigned when the Decision is added to the
    166     * DecisionQueue.
    167     *
    168     * @return the identifier
    169     */
    170    public final int getId() {
    171        return m_id;
    172    }
    173
    174    /**
    175     * Returns <code>true</code> if the Decision can be reassigned to another actor. This implementation always returns <code>true</code>.
    176     *
    177     * @return the result
    178     */
    179    public boolean isReassignable() {
    180        return true;
    181    }
    182
    183    /**
    184     * Reassigns the Decision to a new actor (that is, provide an outcome). If the Decision is not reassignable, this method throws an
    185     * IllegalArgumentException.
    186     *
    187     * @param actor the actor to reassign the Decision to
    188     */
    189    public final synchronized void reassign( final Principal actor ) {
    190        if( isReassignable() ) {
    191            m_actor = actor;
    192        } else {
    193            throw new IllegalArgumentException( "Decision cannot be reassigned." );
    194        }
    195    }
    196
    197    /**
    198     * Sets the unique identfier for this Decision.
    199     *
    200     * @param id the identifier
    201     */
    202    public final void setId( final int id ) {
    203        m_id = id;
    204    }
    205
    206}