1 package cz.cuni.amis.pogamut.base.agent.navigation;
2
3 import cz.cuni.amis.pogamut.base.agent.navigation.impl.BasePathExecutor;
4
5 /**
6 * If you did not read {@link IPathExecutor} javadoc - do it now! Following javadoc assumes you know what {@link IPathExecutor} is
7 * and how its interface works.
8 * <p><p>
9 * As the {@link IPathExecutor} interface is meant to provide a gateway for the user to navigate his/her bot
10 * through the environment, it can't be used (as is) as an interface for further {@link IPathExecutor} functionality
11 * decomposition into (for instance) navigators (i.e., to implement actual path-following into the different
12 * object that actual {@link IPathExecutor} implementation)
13 * <p><p>
14 * Note that example implementation is {@link BasePathExecutor} where new interface methods has better javadoc (bound to the
15 * actual {@link BasePathExecutor} implementation) that can give you hints how they are usually implemented.
16 *
17 * @author Jimmy
18 *
19 * @param <PATH_ELEMENT>
20 */
21 public interface IPathExecutorHelper<PATH_ELEMENT> extends IPathExecutor<PATH_ELEMENT> {
22
23 /**
24 * Asks all {@link IStuckDetector} registered inside executor via {@link IPathExecutor#addStuckDetector(IStuckDetector)}
25 * whether the agent has stuck.
26 * <p><p>
27 * This method checks (one-by-one) stuck detectors whether some of them is reporting that the agent has stuck.
28 * If the stuck is detected, particular {@link IStuckDetector} is returned. It the stuck is not detected,
29 * null is returned.
30 *
31 * @return first detector to report that agent has stuck or null
32 */
33 public IStuckDetector checkStuckDetectors();
34
35 /**
36 * Switches from current path element index into the new one.
37 * <p><p>
38 * Effective only if {@link IPathExecutor#isExecuting()}.
39 *
40 * @param index
41 */
42 public void switchToAnotherPathElement(int index);
43
44 /**
45 * Reports that the agent has stuck - this stuck is detected either by some registered {@link IStuckDetector}
46 * or some other part of the {@link IPathExecutor}.
47 * <p><p>
48 * Effective only if {@link IPathExecutor#isExecuting()}.
49 *
50 * @param detector
51 */
52 public void stuck();
53
54 /**
55 * Reports that the agent has reached its target.
56 * <p><p>
57 * Effective only if {@link IPathExecutor#isExecuting()}.
58 */
59 public void targetReached();
60
61 }