1 package cz.cuni.amis.pogamut.base.agent.navigation;
2
3 /**
4 * High-level description of the {@link IPathExecutor} state.
5 * <p><p>
6 * {@link IPathExecutor} initial state is INSTANTIATED.
7 * <p><p>
8 * Read javadocs for respective states to get the picture how the {@link IPathExecutor} works.
9 * <p><p>
10 * Note that the most important outcome of state & transition definitions is that the {@link IPathExecutor} must
11 * switch itself to state STOPPED before it may switch into FOLLOW_PATH_CALLED again.
12 *
13 * @author Jimmy
14 */
15 public enum PathExecutorState {
16
17 /**
18 * The {@link IPathExecutor} has been just instantiated and neither {@link IPathExecutor#followPath(IPathFuture)} nor
19 * {@link IPathExecutor#stop()} methods has been called since than.
20 * <p><p>
21 * Initial state of the {@link IPathExecutor}.
22 * <p><p>
23 * Next state may (only) be:
24 * <ul>
25 * <li>FOLLOW_PATH_CALLED - if {@link IPathExecutor#followPath(IPathFuture)} is called from the outside</li>
26 * <li>STOPPED - if {@link IPathExecutor#stop() is called from the outside</li>
27 * </ul>
28 */
29 INSTANTIATED,
30
31 /**
32 * {@link IPathExecutor#followPath(IPathFuture)} has been just called.
33 * <p><p>
34 * Next state may (only) be:
35 * <ul>
36 * <li>PATH_COMPUTED - whenever the {@link IPathFuture} provides a path (== the path computation finishes and the path exists)</li>
37 * <li>PATH_COMPUTATION_FAILED - whenever the {@link IPathFuture} fails to provide the path (computation does not finish, exception is returned, null path is returned)</li>
38 * <li>STOPPED - if {@link IPathExecutor#stop() is called</li>
39 * </ul>
40 */
41 FOLLOW_PATH_CALLED,
42
43 /**
44 * {@link IPathFuture} has returned a path. This state marks the beginning of the agent's navigation through
45 * the environment according to the path.
46 * <p><p>
47 * Next state may (only) be:
48 * <ul>
49 * <li>TARGET_REACHED - if provided path is zero-length (i.e. path start == path end)</li>
50 * <li>SWITCHED_TO_ANOTHER_PATH_ELEMENT - whenever the path executor starts to follow obtained path</li>
51 * <li>STUCK - if one of the executor's {@link IStuckDetector} reports that the bot has stuck</li>
52 * <li>STOPPED - if {@link IPathExecutor#stop() is called</li>
53 * </ul>
54 */
55 PATH_COMPUTED,
56
57 /**
58 * {@link IPathFuture} has failed to provide a path.
59 * <p><p>
60 * Next state may (only) be:
61 * <ul>
62 * <li>STOPPED - if {@link IPathExecutor#stop() is called</li>
63 * </ul>
64 */
65 PATH_COMPUTATION_FAILED,
66
67 /**
68 * {@link IPathExecutor} has switched to another path element (begun to navigate to another path element)
69 * <p><p>
70 * Next state may (only) be:
71 * <ul>
72 * <li>SWITCHED_TO_ANOTHER_PATH_ELEMENT - whenever the path executor starts to navigate the agent towards different path element</li>
73 * <li>TARGET_REACHED - whenever the agent gets to desired destination</li>
74 * <li>STUCK - if one of the executor's {@link IStuckDetector} reports that the bot has stuck</li>
75 * <li>STOPPED - if {@link IPathExecutor#stop() is called</li>
76 * </ul>
77 */
78 SWITCHED_TO_ANOTHER_PATH_ELEMENT,
79
80 /**
81 * {@link IPathExecutor} has successfully navigated the agent along the path. Path target has been reached.
82 * <p><p>
83 * Next state may (only) be:
84 * <ul>
85 * <li>STOPPED - if {@link IPathExecutor#stop() is called</li>
86 * </ul>
87 */
88 TARGET_REACHED,
89
90 /**
91 * One of the {@link IStuckDetector} has signalized that the agent is unable to reach its destination (navigate along
92 * the path for whatever reason). The {@link IPathExecutor} halted.
93 * <p><p>
94 * Next state may (only) be:
95 * <ul>
96 * <li>STOPPED - if {@link IPathExecutor#stop() is called</li>
97 * </ul>
98 * <p><p>
99 * Note that this is GREAT candidate for broadcasting custom {@link IPathExecutorState} that contains more information about the stuck, i.e.,
100 * PogamutUT2004 is using UT2004PathExecutorStuckState.
101 */
102 STUCK,
103
104 /**
105 * The {@link IPathExecutor#stop()} has been called and no {@link IPathExecutor#followPath(IPathFuture)} has been called
106 * since that.
107 * <p><p>
108 * Next state may (only) be:
109 * <ul>
110 * <li>FOLLOW_PATH_CALLED - if {@link IPathExecutor#followPath(IPathFuture)} is called from the outside</li>
111 * </ul>
112 */
113 STOPPED
114
115 }