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 java.security.Principal;
022
023/**
024 * AbstractStep subclass that executes instructions, uninterrupted, and results
025 * in an Outcome. Concrete classes only need to implement {@link Task#execute()}.
026 * When the execution step completes, <code>execute</code> must return
027 * {@link Outcome#STEP_COMPLETE}, {@link Outcome#STEP_CONTINUE} or
028 * {@link Outcome#STEP_ABORT}. Subclasses can add any errors by calling the
029 * helper method {@link AbstractStep#addError(String)}. The execute method should
030 * <em>generally</em> capture and add errors to the error list instead of
031 * throwing a WikiException.
032 * <p>
033 *
034 * @since 2.5
035 */
036public abstract class Task extends AbstractStep
037{
038    private static final long serialVersionUID = 4630293957752430807L;
039    
040    private Step m_successor = null;
041
042    /**
043     * Protected constructor that creates a new Task with a specified message key.
044     * After construction, the protected method {@link #setWorkflow(Workflow)} should be
045     * called.
046     *
047     * @param messageKey
048     *            the Step's message key, such as
049     *            <code>decision.editPageApproval</code>. By convention, the
050     *            message prefix should be a lower-case version of the Step's
051     *            type, plus a period (<em>e.g.</em>, <code>task.</code>
052     *            and <code>decision.</code>).
053     */
054    public Task( String messageKey )
055    {
056        super( messageKey );
057        super.addSuccessor( Outcome.STEP_COMPLETE, null );
058        super.addSuccessor( Outcome.STEP_ABORT, null );
059    }
060
061    /**
062     * Constructs a new instance of a Task, with an associated Workflow and
063     * message key.
064     *
065     * @param workflow
066     *            the associated workflow
067     * @param messageKey
068     *            the i18n message key
069     */
070    public Task( Workflow workflow, String messageKey )
071    {
072        this( messageKey );
073        setWorkflow( workflow );
074    }
075
076    /**
077     * Returns {@link SystemPrincipal#SYSTEM_USER}.
078     * @return the system principal
079     */
080    public final Principal getActor()
081    {
082        return SystemPrincipal.SYSTEM_USER;
083    }
084
085    /**
086     * Sets the successor Step to this one, which will be triggered if the Task
087     * completes successfully (that is, {@link Step#getOutcome()} returns
088     * {@link Outcome#STEP_COMPLETE}. This method is really a convenient
089     * shortcut for {@link Step#addSuccessor(Outcome, Step)}, where the first
090     * parameter is {@link Outcome#STEP_COMPLETE}.
091     *
092     * @param step
093     *            the successor
094     */
095    public final synchronized void setSuccessor( Step step )
096    {
097        m_successor = step;
098    }
099
100    /**
101     * Identifies the next Step after this Task finishes successfully. This
102     * method will always return the value set in method
103     * {@link #setSuccessor(Step)}, regardless of the current completion state.
104     *
105     * @return the next step
106     */
107    public final synchronized Step getSuccessor()
108    {
109        return m_successor;
110    }
111
112}