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