1 package cz.cuni.amis.pogamut.ut2004.agent.navigation;
2
3 import java.util.List;
4 import java.util.logging.Logger;
5
6 import cz.cuni.amis.pogamut.base.agent.navigation.IPathExecutor;
7 import cz.cuni.amis.pogamut.base.agent.navigation.IPathExecutorHelper;
8 import cz.cuni.amis.pogamut.base3d.worldview.object.ILocated;
9 import cz.cuni.amis.pogamut.ut2004.bot.impl.UT2004Bot;
10 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.NavPointNeighbourLink;
11 import cz.cuni.amis.pogamut.ut2004.communication.messages.gbinfomessages.Self;
12
13 /**
14 * Navigator purpose is to actually move the bot through the UT2004 environment - if you did not read {@link IPathExecutor}
15 * and {@link UT2004PathExecutor} documentation, do it now. If you did, read on.
16 * <p><p>
17 * The {@link IUT2004PathNavigator} navigator is the easiest-to-implement piece of {@link UT2004PathExecutor} in
18 * terms that it has only two methods to implement. On the other hand - it is acrually very hard to navigate the bot
19 * through UT2004 environment. But! If you need to actually change the way how bot is running inside the UT2004,
20 * implementing own {@link IUT2004PathNavigator} is the best thing to do (you should probably start
21 * by copy-pasting the code from {@link UT2004PathExecutorNavigator} into your new class and experiment with it a bit).
22 * <p><p>
23 * This navigator interface is actually used by {@link UT2004PathExecutor} that covers the tricky part when and how
24 * to call its methods {@link IUT2004PathNavigator#navigate()} and {@link IUT2004PathNavigator#reset()}.
25 *
26 * @author Jimmy
27 *
28 * @param <PATH_ELEMENT>
29 */
30 public interface IUT2004PathNavigator<PATH_ELEMENT extends ILocated> {
31
32 /**
33 * Sets the {@link UT2004Bot} instance that the navigator should navigate. Use its {@link UT2004Bot#getAct()}
34 * to pass commands to the bot.
35 *
36 * @param bot
37 */
38 public void setBot(UT2004Bot bot);
39
40 /**
41 * Sets the {@link IPathExecutorHelper} who is using the navigator, i.e., are calling its
42 * {@link IUT2004PathNavigator#navigate(Self)} and {@link IUT2004PathNavigator#reset()}
43 * methods.
44 * <p><p>
45 * Used by {@link IPathExecutorHelper} implementation to inject its instance into the navigator,
46 * so the navigator may call methods such as {@link IPathExecutorHelper#checkStuckDetectors()},
47 * {@link IPathExecutorHelper#switchToAnotherPathElement(int)}, {@link IPathExecutorHelper#stuck()}
48 * and {@link IPathExecutorHelper#targetReached()}.
49 *
50 * @param owner
51 */
52 public void setExecutor(IUT2004PathExecutorHelper<PATH_ELEMENT> owner);
53
54 /**
55 * This method is regularly called by {@link UT2004PathExecutor} to continue the navigation of the bot
56 * inside the UT2004.
57 *
58 * @param focus where the bot should have its focus
59 */
60 public void navigate(ILocated focus);
61
62 /**
63 * Returns current link the bot is following (if such link exist... may return null).
64 * @return
65 */
66 public NavPointNeighbourLink getCurrentLink();
67
68 /**
69 * {@link UT2004PathExecutor} reports that execution of current path has been terminated - clean up your internal data
70 * structure and prepare to navigate the bot along the new path in the future.
71 */
72 public void reset();
73
74 /**
75 * {@link UT2004PathExecutor} reports that new path has been received and the {@link IUT2004PathNavigator#navigate()}
76 * is about to be called in near future. The new path is passed as a parameter.
77 *
78 * @param path
79 */
80 public void newPath(List<PATH_ELEMENT> path);
81
82 /**
83 * Path has been prolonged ... some elements (already passed) has been removed, some added.
84 *
85 * @param path
86 * @parm currentPathIndex path index into new path (points to the same element as in previous path)
87 */
88 public void pathExtended(List<PATH_ELEMENT> path, int currentPathIndex);
89
90 public Logger getLog();
91
92 }