001    package com.hammurapi.flow.runtime;
002    
003    import java.util.Collection;
004    import java.util.List;
005    import java.util.concurrent.Future;
006    
007    import com.hammurapi.util.Context;
008    
009    /**
010     * Extended invocation semantics to use in flow execution.
011     * @author Pavel
012     * @param <S> Flow state type.
013     * @param <A> Argument type.
014     */
015    public interface Invocable<S, A> {
016            
017            /**
018             * Invokes this invocable.
019             * @param flowState Shared object available to all invocations during execution. Drawing an analogy with object-oriented programming, 
020             * flow definition corresponds to class, and flowState corresponds to instance of the class, which keeps state. 
021             * @param args Arguments. If one or more arguments are instances of TokenIterator, then synapses shall
022             * iterate over them and invoke connected invocable for each element returned by TokenIterator.next(). 
023             * In this case <code>invoke</code> returns a collection of futures with size greater than one.
024             * @param properties Property set.
025             * @param context Context.
026             * @param processingPath Processing path. The purpose of <code>processingPath</code> is 
027             * similar to the purpose of stack trace. This argument shall not be used in flow elements
028             * logic. Synapses modify this element by adding information about processing steps, and throw exception if the 
029             * path becomes too long (infinite loop). 
030             * @return Collection of futures.
031             * @throws Exception
032             */
033            Collection<Future<?>> invoke(S flowState, A[] args, PropertySet properties, Context context, List<ProcessingPathElement> processingPath) throws Exception;
034                    
035    }