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.util.Synchronizer;
024
025import java.io.IOException;
026import java.io.ObjectInputStream;
027import java.io.Serializable;
028import java.security.Principal;
029import java.util.*;
030import java.util.concurrent.locks.ReentrantLock;
031
032/**
033 * Abstract superclass that provides a complete implementation of most Step methods; subclasses need only implement {@link #execute(Context)} and
034 * {@link #getActor()}.
035 *
036 * @since 2.5
037 */
038public abstract class AbstractStep implements Step {
039
040    private static final long serialVersionUID = 8635678679349653768L;
041
042    /** Timestamp of when the step started. */
043    private Date m_start;
044
045    /** Timestamp of when the step ended. */
046    private Date m_end;
047
048    private final String m_key;
049
050    private boolean m_completed;
051
052    private final Map< Outcome, Step > m_successors;
053
054    private int workflowId;
055
056    /** attribute map. */
057    private Map< String, Serializable > workflowContext;
058
059    private Outcome m_outcome;
060
061    private final List<String> m_errors;
062
063    private boolean m_started;
064
065    /**
066     * A lock used to ensure thread safety when accessing shared resources.
067     * This lock provides more flexibility and capabilities than the intrinsic locking mechanism,
068     * such as the ability to attempt to acquire a lock with a timeout, or to interrupt a thread
069     * waiting to acquire a lock.
070     *
071     * @see java.util.concurrent.locks.ReentrantLock
072     */
073    private transient ReentrantLock lock = new ReentrantLock();
074
075    private void readObject( final ObjectInputStream in ) throws IOException, ClassNotFoundException {
076        in.defaultReadObject();
077        // Locks are not part of the serialized form, so data written by earlier releases has none either.
078        lock = new ReentrantLock();
079    }
080
081    /**
082     * Protected constructor that creates a new Step with a specified message key. After construction, the method
083     * {@link #setWorkflow(int, Map)} should be called.
084     *
085     * @param messageKey the Step's message key, such as {@code decision.editPageApproval}. By convention, the message prefix should
086     *                   be a lower-case version of the Step's type, plus a period (<em>e.g.</em>, {@code task.} and {@code decision.}).
087     */
088    protected AbstractStep( final String messageKey ) {
089        m_started = false;
090        m_start = Step.TIME_NOT_SET;
091        m_completed = false;
092        m_end = Step.TIME_NOT_SET;
093        m_errors = new ArrayList<>();
094        m_outcome = Outcome.STEP_CONTINUE;
095        m_key = messageKey;
096        m_successors = new LinkedHashMap<>();
097    }
098
099    /**
100     * Constructs a new Step belonging to a specified Workflow and having a specified message key.
101     *
102     * @param workflowId the parent workflow id to set
103     * @param workflowContext the parent workflow context to set
104     * @param messageKey the Step's message key, such as {@code decision.editPageApproval}. By convention, the message prefix should
105     *                   be a lower-case version of the Step's type, plus a period (<em>e.g.</em>, {@code task.} and {@code decision.}).
106     */
107    public AbstractStep( final int workflowId, final Map< String, Serializable > workflowContext, final String messageKey ) {
108        this( messageKey );
109        setWorkflow( workflowId, workflowContext );
110    }
111
112    /**
113     * {@inheritDoc}
114     */
115    @Override
116    public final void addSuccessor(final Outcome outcome, final Step step ) {
117        m_successors.put( outcome, step );
118    }
119
120    /**
121     * {@inheritDoc}
122     */
123    @Override
124    public final Collection< Outcome > getAvailableOutcomes() {
125        final Set< Outcome > outcomes = m_successors.keySet();
126        return Collections.unmodifiableCollection( outcomes );
127    }
128
129    /**
130     * {@inheritDoc}
131     */
132    @Override
133    public final List< String > getErrors() {
134        return Collections.unmodifiableList( m_errors );
135    }
136
137    /**
138     * {@inheritDoc}
139     */
140    @Override
141    public abstract Outcome execute(Context ctx ) throws WikiException;
142
143    /**
144     * {@inheritDoc}
145     */
146    @Override
147    public abstract Principal getActor();
148
149    /**
150     * {@inheritDoc}
151     */
152    @Override
153    public final Date getEndTime() {
154        return m_end;
155    }
156
157    /**
158     * {@inheritDoc}
159     */
160    @Override
161    public final String getMessageKey() {
162        return m_key;
163    }
164
165    /**
166     * {@inheritDoc}
167     */
168    @Override
169    public final Outcome getOutcome() {
170       return Synchronizer.synchronize(lock, () -> m_outcome);
171    }
172
173    /**
174     * {@inheritDoc}
175     */
176    @Override
177    public final Date getStartTime() {
178        return m_start;
179    }
180
181    /**
182     * {@inheritDoc}
183     */
184    @Override
185    public final boolean isCompleted() {
186        return m_completed;
187    }
188
189    /**
190     * {@inheritDoc}
191     */
192    @Override
193    public final boolean isStarted() {
194        return m_started;
195    }
196
197    /**
198     * {@inheritDoc}
199     */
200    @Override
201    public final void setOutcome(final Outcome outcome ) {
202        Synchronizer.synchronize(lock, () -> {
203            // Is this an allowed Outcome?
204            if( !m_successors.containsKey( outcome ) ) {
205                if( !Outcome.STEP_CONTINUE.equals( outcome ) && !Outcome.STEP_ABORT.equals( outcome ) ) {
206                    throw new IllegalArgumentException( "Outcome " + outcome.getMessageKey() + " is not supported for this Step." );
207                }
208            }
209
210            // Is this a "completion" outcome?
211            if( outcome.isCompletion() ) {
212                if( m_completed ) {
213                    throw new IllegalStateException( "Step has already been marked complete; cannot set again." );
214                }
215                m_completed = true;
216                m_end = new Date( System.currentTimeMillis() );
217            }
218            m_outcome = outcome;
219        });
220
221    }
222
223    /**
224     * {@inheritDoc}
225     */
226    @Override
227    public final void start() throws WikiException {
228        Synchronizer.synchronize(lock, () -> {
229            if( m_started ) {
230                throw new IllegalStateException( "Step already started." );
231            }
232            m_started = true;
233            m_start = new Date( System.currentTimeMillis() );
234        });
235    }
236
237    /**
238     * {@inheritDoc}
239     */
240    @Override
241    public final Step getSuccessor(final Outcome outcome ) {
242        return m_successors.get( outcome );
243    }
244
245    // --------------------------Helper methods--------------------------
246
247    /**
248     * method that sets the parent Workflow id and context post-construction.
249     *
250     * @param workflowId the parent workflow id to set
251     * @param workflowContext the parent workflow context to set
252     */
253    @Override
254    public final void setWorkflow(final int workflowId, final Map< String, Serializable > workflowContext ) {
255        Synchronizer.synchronize(lock, () -> {
256            this.workflowId = workflowId;
257            this.workflowContext = workflowContext;
258        });
259    }
260
261    public int getWorkflowId() {
262        return workflowId;
263    }
264
265    public Map< String, Serializable > getWorkflowContext() {
266        return workflowContext;
267    }
268
269    /**
270     * Protected helper method that adds a String representing an error message to the Step's cached errors list.
271     *
272     * @param message the error message
273     */
274    protected final void addError( final String message ) {
275        Synchronizer.synchronize(lock, () -> {
276            m_errors.add( message );
277        });
278    }
279
280}