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 }