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.util.Synchronizer;
022
023import java.io.IOException;
024import java.io.ObjectInputStream;
025import java.io.Serializable;
026import java.security.Principal;
027import java.util.Map;
028import java.util.concurrent.locks.ReentrantLock;
029
030
031/**
032 * AbstractStep subclass that executes instructions, uninterrupted, and results in an Outcome. Concrete classes only need to implement
033 * {@link Task#execute(org.apache.wiki.api.core.Context)}. When the execution step completes, <code>execute</code> must return {@link Outcome#STEP_COMPLETE},
034 * {@link Outcome#STEP_CONTINUE} or {@link Outcome#STEP_ABORT}. Subclasses can add any errors by calling the helper method
035 * {@link AbstractStep#addError(String)}. The execute method should <em>generally</em> capture and add errors to the error list instead of
036 * throwing a WikiException.
037 * <p>
038 *
039 * @since 2.5
040 */
041public abstract class Task extends AbstractStep {
042
043    private static final long serialVersionUID = 4630293957752430807L;
044
045    private Step m_successor;
046    /**
047     * A lock used to ensure thread safety when accessing shared resources.
048     * This lock provides more flexibility and capabilities than the intrinsic locking mechanism,
049     * such as the ability to attempt to acquire a lock with a timeout, or to interrupt a thread
050     * waiting to acquire a lock.
051     *
052     * @see java.util.concurrent.locks.ReentrantLock
053     */
054    private transient ReentrantLock lock = new ReentrantLock();
055
056    private void readObject( final ObjectInputStream in ) throws IOException, ClassNotFoundException {
057        in.defaultReadObject();
058        // Locks are not part of the serialized form, so data written by earlier releases has none either.
059        lock = new ReentrantLock();
060    }
061
062    /**
063     * Public constructor that creates a new Task with a specified message key. After construction, the protected method
064     * {@link #setWorkflow(int, Map)} should be called.
065     *
066     * @param messageKey the Step's message key, such as <code>decision.editPageApproval</code>. By convention, the message prefix should be
067     *                   a lower-case version of the Step's type, plus a period (<em>e.g.</em>, <code>task.</code> and <code>decision.</code>).
068     */
069    public Task( final String messageKey ) {
070        super( messageKey );
071        super.addSuccessor( Outcome.STEP_COMPLETE, null );
072        super.addSuccessor( Outcome.STEP_ABORT, null );
073    }
074
075    /**
076     * Constructs a new instance of a Task, with an associated Workflow and message key.
077     *
078     * @param workflowId      the parent workflow id to set
079     * @param workflowContext the parent workflow context to set
080     * @param messageKey      the i18n message key
081     */
082    public Task( final int workflowId, final Map< String, Serializable > workflowContext, final String messageKey ) {
083        this( messageKey );
084        setWorkflow( workflowId, workflowContext );
085    }
086
087    /**
088     * Returns {@link SystemPrincipal#SYSTEM_USER}.
089     *
090     * @return the system principal
091     */
092    @Override
093    public final Principal getActor() {
094        return SystemPrincipal.SYSTEM_USER;
095    }
096
097    /**
098     * Sets the successor Step to this one, which will be triggered if the Task completes successfully (that is, {@link Step#getOutcome()}
099     * returns {@link Outcome#STEP_COMPLETE}. This method is really a convenient shortcut for {@link Step#addSuccessor(Outcome, Step)},
100     * where the first parameter is {@link Outcome#STEP_COMPLETE}.
101     *
102     * @param step the successor
103     */
104    public final void setSuccessor( final Step step ) {
105        Synchronizer.synchronize(lock, () -> {
106            m_successor = step;
107        });
108    }
109
110    /**
111     * Identifies the next Step after this Task finishes successfully. This method will always return the value set in method
112     * {@link #setSuccessor(Step)}, regardless of the current completion state.
113     *
114     * @return the next step
115     */
116    public final Step getSuccessor() {
117        return Synchronizer.synchronize(lock, () -> m_successor);
118    }
119
120}