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 }