View Javadoc

1   package cz.cuni.amis.pogamut.base.agent.navigation;
2   
3   import java.util.List;
4   import java.util.logging.Logger;
5   
6   import cz.cuni.amis.utils.flag.ImmutableFlag;
7   
8   /**
9    * Path executor object is responsible for navigation of the agent through the environment along the 
10   * list of PATH_ELEMENTs.
11   * <p><p>
12   * Every path executor has {@link PathExecutorState} that are represented by {@link IPathExecutorState} objects.
13   * There is an exact definition how every {@link IPathExecutor} implementation must behave (i.e., there is a definition
14   * of state transitions), this definition can be found in javadoc of {@link PathExecutorState} enum.
15   * <p><p>
16   * Implementation of path executor is allowed to fine-tune its states by defining own {@link IPathExecutorState} objects adding
17   * additional sub-states (i.e., making itself an hierarchy-FSM object).
18   * <p><p>
19   * Every path executor may contain arbitrary number of {@link IStuckDetector}s that checks whether the agent is 
20   * still able to finish the intended path (stuck may happen due to two reasons 1) the path executor fails to 
21   * steer the agent safely through the environment, 2) the path no longer exist).  
22   * 
23   * @author Jimmy
24   *
25   * @param <PATH_ELEMENT>
26   */
27  public interface IPathExecutor<PATH_ELEMENT> {
28  	
29  	/**
30       * Makes the agent follow given path. Events are fired at different stages
31       * of movement (see {@link IPathExecutor#getState()} and appropriate event-listener hooking method {@link ImmutableFlag#addListener(cz.cuni.amis.utils.flag.FlagListener)}).
32       * 
33       * @param path to follow
34       */
35      public void followPath(IPathFuture<? extends PATH_ELEMENT> path);
36      
37      /**
38       * Returns a flag with the state of the executor - it is desirable you to set up listeners on this
39       * flag as it publish important informations about the path execution.
40       * <p><p>
41       * Note that the flag contains {@link IPathExecutorState} NOT {@link PathExecutorState} itself - this way,
42       * every {@link IPathExecutor} implementor can create own {@link IPathExecutorState} implementation that may carry
43       * much more information about the state that just {@link PathExecutorState} extending the meanings of core 
44       * {@link PathExecutorState}s.
45       * <p><p>
46       * It is advisable to study {@link PathExecutorState} javadoc, as it contains a description how the states can change giving
47       * you a picture how {@link IPathExecutor} is working (this description is a contract for every {@link IPathExecutor}
48       * implementation).
49       * <p><p>
50       * Listeners to the state can be attached via {@link ImmutableFlag#addListener(cz.cuni.amis.utils.flag.FlagListener)}.
51       * 
52       * @return flag with the state
53       */
54      public ImmutableFlag<IPathExecutorState> getState();
55  	
56  	/**
57  	 * Returns current path that the executor is following. 
58  	 * <p><p>
59  	 * Returns null if not {@link IPathExecutor#isExecuting()}.
60  	 * 
61  	 * @return current path
62  	 */
63  	public IPathFuture<PATH_ELEMENT> getPathFuture();
64  	
65  	/**
66  	 * If the {@link IPathExecutor#isExecuting()} and the path has been already computed, returns path the executor
67  	 * is currently following. Returns null otherwise.
68  	 * <p><p>
69  	 * First path element is agent's starting position and the last path element is agent's target.
70  	 * 
71  	 * @return current path or null
72  	 */
73  	public List<PATH_ELEMENT> getPath();
74  	
75  	/**
76  	 * Returns path origin, from where we're running.
77  	 * @return
78  	 */
79  	public PATH_ELEMENT getPathFrom();
80  	
81  	/**
82  	 * Returns target where we're running.
83  	 * @return
84  	 */
85  	public PATH_ELEMENT getPathTo();
86  	
87  	/**
88  	 * Returns an index pointing into {@link IPathExecutor#getPath()} that marks the element
89  	 * the path executor is currently heading to.
90  	 * <p><p>
91  	 * Returns -1 if not {@link IPathExecutor#isExecuting()}.
92  	 * @return
93  	 */
94  	public int getPathElementIndex();
95  	
96  	/**
97  	 * If the {@link IPathExecutor#isExecuting()} and the path has been already computed, returns current path element
98  	 * the executor is navigating to.
99  	 * @return path element or null
100 	 */
101 	public PATH_ELEMENT getPathElement();
102 	
103 	/**
104 	 * True if the path executor is in one of 'states', false otherwise.
105 	 * @param states
106 	 * @return
107 	 */
108 	public boolean inState(PathExecutorState... states);
109 	
110 	/**
111 	 * True if the path executor's state is not among 'states', false otherwise.
112 	 * @param states
113 	 * @return
114 	 */
115 	public boolean notInState(PathExecutorState... states);
116 	
117 	/**
118 	 * Determines, whether the path executor instance has been submitted with {@link IPathFuture} 
119 	 * and working on getting the bot to its target.
120 	 * <p><p>
121 	 * Note that <i>true</i> is also returned for the situation in which the path executor awaits the path computation to be finished.
122 	 * 
123 	 * @return	returns true, if this instance is controlling the agent and navigate
124 	 *			it along PATH_ELEMENTs (or at least waiting for the path). False otherwise
125 	 */
126 	public boolean isExecuting();
127 	
128 	/**
129 	 * Sets to true whenever the path executor reaches the end of the provided path.
130 	 * <p><p>
131 	 * False otherwise (note that {@link IPathExecutor#stop()} will switch this to 'false' again).
132 	 * 
133 	 * @return whether the target is reached
134 	 */
135 	public boolean isTargetReached();
136 	
137 	/**
138 	 * Sets to true whenever the path executor detect that the bot has stuck and is unable to reach the
139 	 * path destination.
140 	 * <p><p>
141 	 * False otherwise (note that {@link IPathExecuto#stop()} will switch this to 'false' again).
142 	 * 
143 	 * @return
144 	 */
145 	public boolean isStuck();
146 	
147 	/**
148 	 * True if the path does not exist (is null) or can't be computed at all (an exception has happened 
149 	 * or the computation has been canceled).
150 	 * <p><p>
151 	 * False otherwise (note that false does not mark the situation that the path has been computed).
152 	 * 
153 	 * @return
154 	 */
155 	public boolean isPathUnavailable();
156 
157     /**
158      * Stops the path executor unconditionally.
159      */
160     public void stop();
161 
162      /**
163      * Adds {@link IStuckDetector} into the executor to watch over the path execution.
164      * @param pathListener
165      */
166     public void addStuckDetector(IStuckDetector stuckDetector);
167 
168     /**
169      * Removes {@link IStuckDetector} from the executor (must be the same instance, equals() is <b>NOT USED</b>).
170      * @param pathListener
171      */
172     public void removeStuckDetector(IStuckDetector stuckDetector);
173     
174     /**
175      * Removes all stuck detectors it has.
176      */
177     public void removeAllStuckDetectors();
178     
179     /**
180      * Returns log used by path executor (may be null, you should always check that).
181      * 
182      * @return log
183      */
184     public Logger getLog();
185     
186 }