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.io.Serializable;
022import java.security.Principal;
023import java.util.Map;
024
025
026/**
027 * AbstractStep subclass that executes instructions, uninterrupted, and results in an Outcome. Concrete classes only need to implement
028 * {@link Task#execute(org.apache.wiki.api.core.Context)}. When the execution step completes, <code>execute</code> must return {@link Outcome#STEP_COMPLETE},
029 * {@link Outcome#STEP_CONTINUE} or {@link Outcome#STEP_ABORT}. Subclasses can add any errors by calling the helper method
030 * {@link AbstractStep#addError(String)}. The execute method should <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;
041
042    /**
043     * Public constructor that creates a new Task with a specified message key. After construction, the protected method
044     * {@link #setWorkflow(int, Map)} should be called.
045     *
046     * @param messageKey the Step's message key, such as <code>decision.editPageApproval</code>. By convention, the message prefix should be
047     *                   a lower-case version of the Step's type, plus a period (<em>e.g.</em>, <code>task.</code> and <code>decision.</code>).
048     */
049    public Task( final String messageKey ) {
050        super( messageKey );
051        super.addSuccessor( Outcome.STEP_COMPLETE, null );
052        super.addSuccessor( Outcome.STEP_ABORT, null );
053    }
054
055    /**
056     * Constructs a new instance of a Task, with an associated Workflow and message key.
057     *
058     * @param workflowId      the parent workflow id to set
059     * @param workflowContext the parent workflow context to set
060     * @param messageKey      the i18n message key
061     */
062    public Task( final int workflowId, final Map< String, Serializable > workflowContext, final String messageKey ) {
063        this( messageKey );
064        setWorkflow( workflowId, workflowContext );
065    }
066
067    /**
068     * Returns {@link SystemPrincipal#SYSTEM_USER}.
069     *
070     * @return the system principal
071     */
072    public final Principal getActor() {
073        return SystemPrincipal.SYSTEM_USER;
074    }
075
076    /**
077     * Sets the successor Step to this one, which will be triggered if the Task completes successfully (that is, {@link Step#getOutcome()}
078     * returns {@link Outcome#STEP_COMPLETE}. This method is really a convenient shortcut for {@link Step#addSuccessor(Outcome, Step)},
079     * where the first parameter is {@link Outcome#STEP_COMPLETE}.
080     *
081     * @param step the successor
082     */
083    public final synchronized void setSuccessor( final Step step ) {
084        m_successor = step;
085    }
086
087    /**
088     * Identifies the next Step after this Task finishes successfully. This method will always return the value set in method
089     * {@link #setSuccessor(Step)}, regardless of the current completion state.
090     *
091     * @return the next step
092     */
093    public final synchronized Step getSuccessor() {
094        return m_successor;
095    }
096
097}