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}