cz.cuni.amis.pogamut.base.agent.navigation.impl
Class BasePathExecutor<PATH_ELEMENT>

java.lang.Object
  cz.cuni.amis.pogamut.base.agent.navigation.impl.AbstractPathExecutor<PATH_ELEMENT>
      cz.cuni.amis.pogamut.base.agent.navigation.impl.BasePathExecutor<PATH_ELEMENT>

All Implemented Interfaces:

IPathExecutor<PATH_ELEMENT>, IPathExecutorHelper<PATH_ELEMENT>

Direct Known Subclasses:

UT2004PathExecutor

public abstract class BasePathExecutor<PATH_ELEMENT>
extends AbstractPathExecutor<PATH_ELEMENT>
implements IPathExecutorHelper<PATH_ELEMENT>

BasePathExecutor provides a stub implementation of abstract methods of the AbstractPathExecutor which correctly sets the path executor states along the way and provide methods for reporting failures.

Note that it is somewhat hard to use this stub-implementation as the base for implementing your own IPathExecutor implementation - the AbstractPathExecutor might be more suitable. That's because this implementation is defining a way how its fields are used, how methods should be synchronized, how they are called (method protocol), etc.

Implementation notes:

• As the IPathExecutorState may have different implementation providing different kind of the information about the path - BasePathExecutor defines createState(PathExecutorState) as a hook for custom IPathExecutorState implementation (currently it uses simple BasePathExecutorState).
• Many methods here are made final - this might seem to block your inventions, but it is actually for your own good. If you find yourself in need to override some method that is made final, it is advised that you switch to AbstractPathExecutor or copy-paste the BasePathExecutor code and do your changes in copied code.
• There are several important final methods that drive the BasePathExecutor.
  • followPath(IPathFuture) - interface public method / meant to be called from the outside - begin following the path / handles path future listener
  • pathComputed() - protected method / it is automatically called by the BasePathExecutor whenever the path future returns the path
  • pathComputationFailed() - protected method / it is automatically called by the BasePathExecutor whenever path future reports FutureStatus.CANCELED or FutureStatus.COMPUTATION_EXCEPTION.
  • switchToAnotherPathElement(int) - protected method / meant to be called from within the path executor (descendant) whenever the executor should start to navigate towards another path element
  • BasePathExecutor#stuck(IStuckDetector) - protected method / automatically called by BasePathExecutor#executePath() whenever one of the AbstractPathExecutor.stuckDetectors reports stuck
  • stop() - interface public method / meant to be called both from the outside or from the inside of path executor / stops the path executor
• Important final methods from the previous paragraph are usually split into three parts
  1. their actual implementation that can't be overridden, it (usually) changes the state of the path executor and recalls pre/post methods
  2. pre-phase method that is called (from within the method's implementation) just before the state of the executor is changed
  3. post-phase method that is called (from within the method's implementation) just after the state of the executor is changed
  Pre/Post-phase methods are usually abstract (if not, they contain meaningful implementation but that can be overriden if wished for) and are meant to be implemented in descendants. They allow you to fine control the state of the executor before and after the change of its state without the need to program boring part of the code that changes the state in a correct way. Think of implementing the descendant of this class as implementing reactions to the changes of executor's state.
• Additionally, there are methods that are not called from anywhere of BasePathExecutor. These are:
  • switchToAnotherPathElement(int) - this method should be called either from prePathComputedImpl() or pathComputed() to mark the index of the path element that is going to be pursued first (this index will likely be '0').
  • BasePathExecutor#stuck(IStuckDetector) - use this method to report that the stuck has been detected
  • checkStuckDetectors()
• It is up to the descendant how the path execution will be actually implemented (either by some event-driven model, i.e., reacting on the events that will come from the environment, or spawning some thread that will regularly perform some operation, etc.).

Field Summary

protected java.lang.Object	mutex Mutex object synchronizing access to followPath(IPathFuture) and stop() methods.
protected IPathFuture<PATH_ELEMENT>	pathFuture Current path future of the path executor.
protected int	previousPathElementIndex Marks the index of the previous path element (path element that has been previously pursued) from the path element list of AbstractPathExecutor.getPath().

Fields inherited from class cz.cuni.amis.pogamut.base.agent.navigation.impl.AbstractPathExecutor

log, state, stuckDetectors

Constructor Summary

BasePathExecutor()

BasePathExecutor(java.util.logging.Logger log)

Method Summary

IStuckDetector	checkStuckDetectors() This method checks (one-by-one) stuck detectors whether some of them is reporting that the agent has stuck.
protected IPathExecutorState	createState(PathExecutorState state) Utility method that is responsible for creating new state for the path executor.
void	followPath(IPathFuture<? extends PATH_ELEMENT> path) Tell the executor to start navigating the agent along the 'path'.
protected abstract void	followPathImpl() Method that is called just after the executor's state is switched to PathExecutorState.FOLLOW_PATH_CALLED from within the followPath(IPathFuture) method.
int	getPathElementIndex() Returns an index pointing into IPathExecutor.getPath() that marks the element the path executor is currently heading to.
IPathFuture<PATH_ELEMENT>	getPathFuture() Returns current path that the executor is following.
protected void	pathComputationFailed() Path computation has failed, path is unavailable and the executor can't start navigate the agent through the environment.
protected abstract void	pathComputationFailedImpl() Method that is called just after the executor's state is switched to PathExecutorState.PATH_COMPUTATION_FAILED from within the pathComputationFailed() method.
protected void	pathComputed() Path has been computed and is available in pathFuture.
protected abstract void	pathComputedImpl() Method that is called just after the executor's state is switched to PathExecutorState.PATH_COMPUTED from within the pathComputed() method.
protected void	preFollowPathImpl() Method that is called just before the executor's state is switched to PathExecutorState.FOLLOW_PATH_CALLED from within the followPath(IPathFuture) method.
protected void	prePathComputationFailed() Method that is called just before the executor's state is switched to PathExecutorState.PATH_COMPUTATION_FAILED from within the pathComputationFailed() method.
protected void	prePathComputedImpl() Method that is called just before the executor's state is switched to PathExecutorState.PATH_COMPUTED from within the pathComputed() method.
protected void	preStuckImpl() Method that is called just before the executor's state is switched to PathExecutorState#STUCKD from within the BasePathExecutor#stuck(IStuckDetector) method.
protected void	preSwitchToAnotherPathElementImpl(int newIndex) Method that is called just before the executor's state is switched to PathExecutorState.SWITCHED_TO_ANOTHER_PATH_ELEMENT from within the switchToAnotherPathElement(int) method.
protected void	preTargetReachedImpl() Method that is called just before the executor's state is switched to PathExecutorState.TARGET_REACHED from within the targetReached() method.
void	stop() Used to stop the path executor, for more info see AbstractPathExecutor.stop().
protected void	stopImpl() Method that is called just before the executor's state is switched to PathExecutorState.STOPPED from within the stop() method.
protected abstract void	stopped() Method that is called just after the executor's state is switched to PathExecutorState.STOPPED from within the stop() method.
void	stuck() Method that changes the state to PathExecutorState.STUCK that should be called whenever some stuck detector detects that the agent is stuck.
protected abstract void	stuckImpl() Method that is called just after the executor's state is switched to PathExecutorState.STUCK from within the BasePathExecutor#stuck(IStuckDetector) method.
void	switchToAnotherPathElement(int index) Switches from current path element index into the new one.
protected abstract void	switchToAnotherPathElementImpl() Method that is called just after the executor's state is switched to PathExecutorState.SWITCHED_TO_ANOTHER_PATH_ELEMENT from within the switchToAnotherPathElement(int) method.
void	targetReached() Method that should be called whenever the path executor reaches the end of the path.
protected abstract void	targetReachedImpl() Method that is called just after the executor's state is switched to PathExecutorState.TARGET_REACHED from within the targetReached() method.

Methods inherited from class cz.cuni.amis.pogamut.base.agent.navigation.impl.AbstractPathExecutor

addStuckDetector, getLog, getPath, getPathElement, getState, inState, isExecuting, isPathUnavailable, isStuck, isTargetReached, notInState, removeStuckDetector, setLog, switchState

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface cz.cuni.amis.pogamut.base.agent.navigation.IPathExecutor

addStuckDetector, getLog, getPath, getPathElement, getState, inState, isExecuting, isPathUnavailable, isStuck, isTargetReached, notInState, removeStuckDetector

Field Detail

mutex

protected java.lang.Object mutex

Mutex object synchronizing access to followPath(IPathFuture) and stop() methods.

pathFuture

protected IPathFuture<PATH_ELEMENT> pathFuture

Current path future of the path executor. Path future is set in followPath(IPathFuture) and removed (set to 'null') in stop().

previousPathElementIndex

protected int previousPathElementIndex

Marks the index of the previous path element (path element that has been previously pursued) from the path element list of AbstractPathExecutor.getPath().

Setting value to this field manually must be done only inside preSwitchToAnotherPathElementImpl(int) and switchToAnotherPathElementImpl().

Constructor Detail

BasePathExecutor

public BasePathExecutor()

BasePathExecutor

public BasePathExecutor(java.util.logging.Logger log)

Method Detail

getPathElementIndex

public int getPathElementIndex()

Description copied from interface: IPathExecutor

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

Returns -1 if not IPathExecutor.isExecuting().

Specified by:

getPathElementIndex in interface IPathExecutor<PATH_ELEMENT>

Specified by:

getPathElementIndex in class AbstractPathExecutor<PATH_ELEMENT>

Returns:

getPathFuture

public IPathFuture<PATH_ELEMENT> getPathFuture()

Description copied from interface: IPathExecutor

Returns current path that the executor is following.

Returns null if not IPathExecutor.isExecuting().

Specified by:

getPathFuture in interface IPathExecutor<PATH_ELEMENT>

Specified by:

getPathFuture in class AbstractPathExecutor<PATH_ELEMENT>

Returns:

current path

createState

protected IPathExecutorState createState(PathExecutorState state)

Utility method that is responsible for creating new state for the path executor. You may override this method to fine-control which implementations IPathExecutorState are instantiated.

This method allows you to provide own IPathExecutorState implementation that may carry additional information about the executor's state.

Parameters:

state -

Returns:

followPath

public final void followPath(IPathFuture<? extends PATH_ELEMENT> path)

Tell the executor to start navigating the agent along the 'path'.

If called and the AbstractPathExecutor.isExecuting(), it first calls stop().

For more info see AbstractPathExecutor.followPath(IPathFuture)

Specified by:

followPath in interface IPathExecutor<PATH_ELEMENT>

Specified by:

followPath in class AbstractPathExecutor<PATH_ELEMENT>

Parameters:

path - path to navigate along

preFollowPathImpl

protected void preFollowPathImpl()

Method that is called just before the executor's state is switched to PathExecutorState.FOLLOW_PATH_CALLED from within the followPath(IPathFuture) method.

You may utilize this methods this way:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.

Current implementation ensures that the state of the path executor is cleared.

followPathImpl

protected abstract void followPathImpl()

Method that is called just after the executor's state is switched to PathExecutorState.FOLLOW_PATH_CALLED from within the followPath(IPathFuture) method.

You may utilize this method this way:

• Examine the state of the executor / values produced by executor state listeners.

pathComputed

protected final void pathComputed()

Path has been computed and is available in pathFuture. This method is automatically called from the followPath(IPathFuture) or by pathFutureListener whenever the path is ready.

Effective only if the state is: PathExecutorState.FOLLOW_PATH_CALLED

prePathComputedImpl

protected void prePathComputedImpl()

Method that is called just before the executor's state is switched to PathExecutorState.PATH_COMPUTED from within the pathComputed() method. Note that since this method is called, the path can be simply obtained by calling AbstractPathExecutor.getPath().

You may utilize this method (for instance) to:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.

Note that you should call switchToAnotherPathElement(int) (to mark the index of the first path element) in this method or in pathComputedImpl(). The first path element index will likely be '0'.

Resets all AbstractPathExecutor.stuckDetectors.

pathComputedImpl

protected abstract void pathComputedImpl()

Method that is called just after the executor's state is switched to PathExecutorState.PATH_COMPUTED from within the pathComputed() method. Note that the path can be simply obtained by calling AbstractPathExecutor.getPath().

You may utilize this method (for instance) to:

• Examine the state of the executor / values produced by executor state listeners.

Note that you should call switchToAnotherPathElement(int) (to mark the index of the first path element) in this method or in prePathComputedImpl(). The first path element index will likely be '0'.

pathComputationFailed

protected final void pathComputationFailed()

Path computation has failed, path is unavailable and the executor can't start navigate the agent through the environment. This method is automatically called from the followPath(IPathFuture) or by pathFutureListener whenever it is found out that the path can never be obtained from the pathFuture.

Effective only if the state is: PathExecutorState.FOLLOW_PATH_CALLED

prePathComputationFailed

protected void prePathComputationFailed()

Method that is called just before the executor's state is switched to PathExecutorState.PATH_COMPUTATION_FAILED from within the pathComputationFailed() method.

You may utilize this methods (for instance) to:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.
• Clean up some executor's fields.

Empty implementation, does not doing anything.

pathComputationFailedImpl

protected abstract void pathComputationFailedImpl()

Method that is called just after the executor's state is switched to PathExecutorState.PATH_COMPUTATION_FAILED from within the pathComputationFailed() method. Note that the path can be simply obtained by calling AbstractPathExecutor.getPath().

You may utilize this method (for instance) to:

• Examine the state of the executor / values produced by executor state listeners.
• Clean up some executor's fields.

switchToAnotherPathElement

public final void switchToAnotherPathElement(int index)

Switches from current path element index into the new one. You have to call this method from your implementation whenever you want to change pathElementIndex.

This method should be also called as a reaction to pathComputed() method call, i.e., from prePathComputedImpl() or pathComputedImpl() to change the index into '0' (or other index as you see fit).

Effective only if AbstractPathExecutor.isExecuting().

Specified by:

switchToAnotherPathElement in interface IPathExecutorHelper<PATH_ELEMENT>

preSwitchToAnotherPathElementImpl

protected void preSwitchToAnotherPathElementImpl(int newIndex)

Method that is called just before the executor's state is switched to PathExecutorState.SWITCHED_TO_ANOTHER_PATH_ELEMENT from within the switchToAnotherPathElement(int) method. Note that this method is called to alter values inside previousPathElementIndex and pathElementIndex by using 'newIndex'.

You may additionally utilize this method (for instance) to:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.

Current implementation does (and nothing else):

• previousPathElementIndex = pathElementIndex;
• pathElementIndex = newIndex;

Parameters:

newIndex - index of the path element that should be pursued now

switchToAnotherPathElementImpl

protected abstract void switchToAnotherPathElementImpl()

Method that is called just after the executor's state is switched to PathExecutorState.SWITCHED_TO_ANOTHER_PATH_ELEMENT from within the switchToAnotherPathElement(int) method. Note that this method is called after the values inside previousPathElementIndex and pathElementIndex are overwritten with new ones.

You may utilize this method (for instance) to:

• Examine the state of the executor / values produced by executor state listeners.

stop

public final void stop()

Used to stop the path executor, for more info see AbstractPathExecutor.stop().

Effective only if the state is NOT: PathExecutorState.STOPPED

Specified by:

stop in interface IPathExecutor<PATH_ELEMENT>

Specified by:

stop in class AbstractPathExecutor<PATH_ELEMENT>

stopImpl

protected void stopImpl()

Method that is called just before the executor's state is switched to PathExecutorState.STOPPED from within the stop() method. Note that this method is called to clean up internal data structures before we switch itself into PathExecutorState.STOPPED state.

You may additionally utilize this method (for instance) to:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.

Current implementation does (and nothing else):

• sets previousPathElementIndex and pathElementIndex to -1
• removes pathFutureListener from the pathFuture
• sets pathFuture to null

Parameters:

newIndex - index of the path element that should be pursued now

stopped

protected abstract void stopped()

Method that is called just after the executor's state is switched to PathExecutorState.STOPPED from within the stop() method.

You may utilize this method (for instance) to:

• Finish the internal data structures clean up.

checkStuckDetectors

public IStuckDetector checkStuckDetectors()

This method checks (one-by-one) stuck detectors whether some of them is reporting that the agent has stuck. If the stuck is detected, particular IStuckDetector is returned. It the stuck is not detected, null is returned.

Specified by:

checkStuckDetectors in interface IPathExecutorHelper<PATH_ELEMENT>

Returns:

first detector to report that agent has stuck or null

stuck

public final void stuck()

Method that changes the state to PathExecutorState.STUCK that should be called whenever some stuck detector detects that the agent is stuck.

It is currently called only from checkStuckDetectors() which must be called from the descendant.

Note that you may actually pass 'null' as 'detector' into the method.

Effective only if the state is: PathExecutorState.FOLLOW_PATH_CALLED or PathExecutorState.PATH_COMPUTED or PathExecutorState.SWITCHED_TO_ANOTHER_PATH_ELEMENT

Specified by:

stuck in interface IPathExecutorHelper<PATH_ELEMENT>

preStuckImpl

protected void preStuckImpl()

Method that is called just before the executor's state is switched to PathExecutorState#STUCKD from within the BasePathExecutor#stuck(IStuckDetector) method. Note that this method is called to clean up internal data structures before we switch itself into PathExecutorState.STUCK state.

You may utilize this method (for instance) to:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.

WARNING: 'null' may be passed as 'detector' if the stuck has been detected by different component

stuckImpl

protected abstract void stuckImpl()

Method that is called just after the executor's state is switched to PathExecutorState.STUCK from within the BasePathExecutor#stuck(IStuckDetector) method.

You may utilize this method (for instance) to:

• Finish the internal data structures clean up.

WARNING: 'null' may be passed as 'detector' if the stuck has been detected by different component

targetReached

public final void targetReached()

Method that should be called whenever the path executor reaches the end of the path. Currently this method is not called from anywhere of BasePathExecutor.

Effective only if the state is: PathExecutorState.FOLLOW_PATH_CALLED or PathExecutorState.PATH_COMPUTED or PathExecutorState.SWITCHED_TO_ANOTHER_PATH_ELEMENT

Specified by:

targetReached in interface IPathExecutorHelper<PATH_ELEMENT>

preTargetReachedImpl

protected void preTargetReachedImpl()

Method that is called just before the executor's state is switched to PathExecutorState.TARGET_REACHED from within the targetReached() method.

You may utilize this method (for instance) to:

• Initialize inner/public fields that can be used by executor state listeners.
• Store values that should be passed into createState(PathExecutorState) to create more-informed state object.
• Clean up some internal data structures as the target has been reached.

Empty implementation, does not doing anything.

targetReachedImpl

protected abstract void targetReachedImpl()

Method that is called just after the executor's state is switched to PathExecutorState.TARGET_REACHED from within the targetReached() method.

You may utilize this method (for instance) to:

• Examine the state of the executor / values produced by executor state listeners.
• Clean up some internal data structures as the target has been reached.