org.kynosarges.tektosyne.graph

Interface GraphAgent<T>

Type Parameters:

T - the type of all nodes in the Graph

public interface GraphAgent<T>

Represents an agent that can navigate a Graph. Moves across direct node connections defined by the Graph, allowing the implementation of pathfinding algorithms.

Method Summary

Modifier and Type	Method and Description
boolean	canMakeStep(T source, T target) Determines whether the GraphAgent can move from one specified Graph node to another neighboring node.
default boolean	canOccupy(T target) Determines whether the GraphAgent can permanently occupy the specified Graph node.
double	getStepCost(T source, T target) Determines the step cost for moving the GraphAgent from one specified Graph node to another neighboring node.
default boolean	isNearTarget(T node, T target, double distance) Determines whether two specified Graph nodes are near enough to end a move.
boolean	relaxedRange() Indicates whether the GraphAgent can enter Graph nodes that exceed the maximum path cost.

Method Detail

relaxedRange

boolean relaxedRange()

Indicates whether the GraphAgent can enter Graph nodes that exceed the maximum path cost. If relaxedRange() is false, the maximum path cost for a movement is the absolute upper limit that determines reachable nodes. The GraphAgent will not enter any node whose total path cost exceeds this limit, as determined by getStepCost(T, T).

If relaxedRange() is true, the GraphAgent can enter any node as the final step of a movement path, regardless of the actual getStepCost(T, T) result for that node, as long as the total path cost of all previous steps is less than the maximum path cost.

Returns:

true if the GraphAgent may end its movement on a Graph node that exceeds the movement’s maximum path cost, else false

canMakeStep

boolean canMakeStep(T source,
                    T target)

Determines whether the GraphAgent can move from one specified Graph node to another neighboring node. Considers only whether the GraphAgent could move to target if already placed on source, not whether the GraphAgent could move to either source or target from its actual present Graph node, if any.

canMakeStep should succeed if the GraphAgent could occupy target either temporarily or permanently. Use canOccupy(T) to impose additional restrictions on stopping a movement at specific nodes.

Parameters:

source - the Graph node where the move starts

target - the Graph node where the move ends, which must be a direct neighbor of source

Returns:

true if the GraphAgent can move from source to target, else false

Throws:

java.lang.IllegalArgumentException - if source and target are not direct neighbors in the Graph

java.lang.NullPointerException - if source or target is null

canOccupy

default boolean canOccupy(T target)

Determines whether the GraphAgent can permanently occupy the specified Graph node. Determines whether the GraphAgent could stop at target and permanently occupy that node, assuming target has already been reached during movement.

canOccupy should not consider whether the GraphAgent could temporarily occupy target during a continuing multi-step movement, or whether target could be reached at all from any other node.

The default implementation simply returns true. Pathfinding algorithms always specify a target node for which canMakeStep(T, T) has already succeeded, so you should return false only if you wish to specifically prevent the GraphAgent from ending a move on target.

Parameters:

target - the Graph node to occupy

Returns:

true if the GraphAgent can permanently occupy target, else false

Throws:

java.lang.NullPointerException - if target is null

getStepCost

double getStepCost(T source,
                   T target)

Determines the step cost for moving the GraphAgent from one specified Graph node to another neighboring node. Does not verify whether the GraphAgent can actually move from source to target. Clients should call canMakeStep(T, T) to ensure this condition.

getStepCost should compute the movement cost under the assumption that the GraphAgent was already placed on source. The cost of reaching source from its actual present Graph node, if any, should be ignored.

Parameters:

source - the Graph node where the move starts

target - the Graph node where the move ends, which must be a direct neighbor of source

Returns:

the cost for moving the GraphAgent from source to target, equal to or greater than the result of Graph.getDistance(T, T) for these nodes

Throws:

java.lang.IllegalArgumentException - if source and target are not direct neighbors in the Graph

java.lang.NullPointerException - if source or target is null

isNearTarget

default boolean isNearTarget(T node,
                             T target,
                             double distance)

Determines whether two specified Graph nodes are near enough to end a move. The default implementation ignores distance and returns true exactly if source and target are the same object.

More complex implementations might check for a maximum distance, or examine application-specific properties of node and target.

Parameters:

node - the Graph node to examine

target - the Graph node that is the target of the move

distance - the Graph.getDistance(T, T) result for node and target, if known, or a negative value to have isNearTarget(T, T, double) compute it

Returns:

true if a move toward target should be considered complete once node is reached, else false

Throws:

java.lang.NullPointerException - if node or target is null