001    package toolbus;
002    
003    import java.util.List;
004    import toolbus.environment.Environment;
005    import toolbus.exceptions.ToolBusException;
006    import toolbus.parsercup.PositionInformation;
007    import toolbus.process.ProcessInstance;
008    import aterm.ATerm;
009    
010    /**
011     * The interface StateElement captures all operations that can be performed on an element of a
012     * State. Recall that all proces expressions are compiled to a finite automaton consisting of States
013     * and transitions. The most typical example of a StateElement is an Atom.
014     */
015    public interface StateElement{
016            
017            /**
018             * Check whether a StateElement contains another StateElement. In the simplest case of Atom this
019             * is just an identity test. In composite cases (e.g. Merge), it requires a recursive search.
020             * 
021             * @param elem
022             *            the StateElement
023             * @return true (contained in) or false (not contained in)
024             */
025            boolean contains(StateElement elem);
026            
027            /**
028             * Add a test to this state element. Tests implement conditionals but not delays / timeouts.
029             * 
030             * @param test
031             * @param env
032             *            to be used for executing the test
033             * @throws ToolBusException
034             */
035            void setTest(ATerm test, Environment env) throws ToolBusException;
036            
037            /**
038             * Returns a collection containing all tests that are associated with this state element.
039             * 
040             * @return A collection containing all tests that are associated with this state element.
041             */
042            List<ATerm> getTests();
043            
044            /**
045             * Is this StateElelement enabled for execution, i.e., are its associated tests all true? If
046             * enabled, the StateElement is ready for execution.
047             * 
048             * @return true (enabled) or false (not enabled).
049             * @throws ToolBusException
050             */
051            boolean isEnabled() throws ToolBusException;
052            
053            /**
054             * @return the ProcessInstance to which the StateElement belongs
055             */
056            ProcessInstance getProcess();
057            
058            /**
059             * Activate the StateElement, i.e. make it ready for execution. This may involve initialization
060             * and the setting of timers.
061             */
062            void activate();
063            
064            /**
065             * Execute this StateElement
066             * 
067             * @return true if execution was completed.
068             * @throws ToolBusException
069             */
070            boolean execute() throws ToolBusException;
071            
072            /**
073             * Executes the state element in debug mode.
074             * 
075             * @return The collection of partners that cooperated with the execution of the state element.
076             * Null if the execution did not complete.
077             * 
078             * @throws ToolBusException
079             */
080            ProcessInstance[] debugExecute() throws ToolBusException;
081            
082            /**
083             * @return the successor State of the StateElement
084             */
085            State gotoNextStateAndActivate();
086            
087            /**
088             * Get the successor of the StateElement for a given other StateElement elem. This typically
089             * used for a composite StateElement to get a specific successor. TODO: Probably this method
090             * should be combined with the previous one.
091             * 
092             * @param elem
093             * @return the successor State of the StateElement
094             */
095            State gotoNextStateAndActivate(StateElement elem);
096            
097            /**
098             * Returns the position information associated to the implementing state element.
099             * @return The position information associated to the implementing state element.
100             */
101            PositionInformation getPosInfo();
102            
103            /**
104             * @see toolbus.process.ProcessExpression#getFollow()
105             */
106            State getFollow();
107    }