cz.cuni.amis.pogamut.base.agent.navigation
Interface IPathExecutor<PATH_ELEMENT>

Type Parameters:

PATH_ELEMENT -

All Known Subinterfaces:

IPathExecutorHelper<PATH_ELEMENT>, IPathExecutorWithPlanner<PATH_ELEMENT>, IUnrealPathExecutor<PATH_ELEMENT>, IUT2004PathExecutorHelper<PATH_ELEMENT>

All Known Implementing Classes:

AbstractPathExecutor, BasePathExecutor, UT2004PathExecutor

public interface IPathExecutor<PATH_ELEMENT>

Path executor object is responsible for navigation of the agent through the environment along the list of PATH_ELEMENTs.

Every path executor has PathExecutorState that are represented by IPathExecutorState objects. There is an exact definition how every IPathExecutor implementation must behave (i.e., there is a definition of state transitions), this definition can be found in javadoc of PathExecutorState enum.

Implementation of path executor is allowed to fine-tune its states by defining own IPathExecutorState objects adding additional sub-states (i.e., making itself an hierarchy-FSM object).

Every path executor may contain arbitrary number of IStuckDetectors that checks whether the agent is still able to finish the intended path (stuck may happen due to two reasons 1) the path executor fails to steer the agent safely through the environment, 2) the path no longer exist).

Method Summary

void	addStuckDetector(IStuckDetector stuckDetector) Adds IStuckDetector into the executor to watch over the path execution.
void	followPath(IPathFuture<? extends PATH_ELEMENT> path) Makes the agent follow given path.
java.util.logging.Logger	getLog() Returns log used by path executor (may be null, you should always check that).
java.util.List<PATH_ELEMENT>	getPath() If the isExecuting() and the path has been already computed, returns path the executor is currently following.
PATH_ELEMENT	getPathElement() If the isExecuting() and the path has been already computed, returns current path element the executor is navigating to.
int	getPathElementIndex() Returns an index pointing into getPath() that marks the element the path executor is currently heading to.
IPathFuture<PATH_ELEMENT>	getPathFuture() Returns current path that the executor is following.
ImmutableFlag<IPathExecutorState>	getState() Returns a flag with the state of the executor - it is desirable you to set up listeners on this flag as it publish important informations about the path execution.
boolean	inState(PathExecutorState... states) True if the path executor is in one of 'states', false otherwise.
boolean	isExecuting() Determines, whether the path executor instance has been submitted with IPathFuture and working on getting the bot to its target.
boolean	isPathUnavailable() True if the path does not exist (is null) or can't be computed at all (an exception has happened or the computation has been canceled).
boolean	isStuck() Sets to true whenever the path executor detect that the bot has stuck and is unable to reach the path destination.
boolean	isTargetReached() Sets to true whenever the path executor reaches the end of the provided path.
boolean	notInState(PathExecutorState... states) True if the path executor's state is not among 'states', false otherwise.
void	removeStuckDetector(IStuckDetector stuckDetector) Removes IStuckDetector from the executor (must be the same instance, equals() is NOT USED).
void	stop() Stops the path executor unconditionally.

Method Detail

followPath

void followPath(IPathFuture<? extends PATH_ELEMENT> path)

Makes the agent follow given path. Events are fired at different stages of movement (see getState() and appropriate event-listener hooking method ImmutableFlag.addListener(cz.cuni.amis.utils.flag.FlagListener)).

Parameters:

path - to follow

getState

ImmutableFlag<IPathExecutorState> getState()

Returns a flag with the state of the executor - it is desirable you to set up listeners on this flag as it publish important informations about the path execution.

Note that the flag contains IPathExecutorState NOT PathExecutorState itself - this way, every IPathExecutor implementor can create own IPathExecutorState implementation that may carry much more information about the state that just PathExecutorState extending the meanings of core PathExecutorStates.

It is advisable to study PathExecutorState javadoc, as it contains a description how the states can change giving you a picture how IPathExecutor is working (this description is a contract for every IPathExecutor implementation).

Listeners to the state can be attached via ImmutableFlag.addListener(cz.cuni.amis.utils.flag.FlagListener).

Returns:

flag with the state

getPathFuture

IPathFuture<PATH_ELEMENT> getPathFuture()

Returns current path that the executor is following.

Returns null if not isExecuting().

Returns:

current path

getPath

java.util.List<PATH_ELEMENT> getPath()

If the isExecuting() and the path has been already computed, returns path the executor is currently following. Returns null otherwise.

First path element is agent's starting position and the last path element is agent's target.

Returns:

current path or null

getPathElementIndex

int getPathElementIndex()

Returns an index pointing into getPath() that marks the element the path executor is currently heading to.

Returns -1 if not isExecuting().

Returns:

getPathElement

PATH_ELEMENT getPathElement()

If the isExecuting() and the path has been already computed, returns current path element the executor is navigating to.

Returns:

path element or null

inState

boolean inState(PathExecutorState... states)

True if the path executor is in one of 'states', false otherwise.

Parameters:

states -

Returns:

notInState

boolean notInState(PathExecutorState... states)

True if the path executor's state is not among 'states', false otherwise.

Parameters:

states -

Returns:

isExecuting

boolean isExecuting()

Determines, whether the path executor instance has been submitted with IPathFuture and working on getting the bot to its target.

Note that true is also returned for the situation in which the path executor awaits the path computation to be finished.

Returns:

returns true, if this instance is controlling the agent and navigate it along PATH_ELEMENTs (or at least waiting for the path). False otherwise

isTargetReached

boolean isTargetReached()

Sets to true whenever the path executor reaches the end of the provided path.

False otherwise (note that stop() will switch this to 'false' again).

Returns:

whether the target is reached

isStuck

boolean isStuck()

Sets to true whenever the path executor detect that the bot has stuck and is unable to reach the path destination.

False otherwise (note that IPathExecuto#stop() will switch this to 'false' again).

Returns:

isPathUnavailable

boolean isPathUnavailable()

True if the path does not exist (is null) or can't be computed at all (an exception has happened or the computation has been canceled).

False otherwise (note that false does not mark the situation that the path has been computed).

Returns:

stop

void stop()

Stops the path executor unconditionally.

addStuckDetector

void addStuckDetector(IStuckDetector stuckDetector)

Adds IStuckDetector into the executor to watch over the path execution.

Parameters:

pathListener -

removeStuckDetector

void removeStuckDetector(IStuckDetector stuckDetector)

Removes IStuckDetector from the executor (must be the same instance, equals() is NOT USED).

Parameters:

pathListener -

getLog

java.util.logging.Logger getLog()

Returns log used by path executor (may be null, you should always check that).

Returns:

log