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}