de.ipcon.tools.graph

Class GraphPath

java.lang.Object

de.ipcon.tools.graph.GraphPath

public class GraphPath
extends java.lang.Object

Represents an immutable, ordered sequence of connected edges originating from a specific startNode (an OnlyToDirectedGraphNodeI) in a graph. A GraphPath defines a concrete route or walk through the graph.

Immutability: Once a GraphPath instance is created, its state (including the start node and the sequence of edges) cannot be changed. Methods that appear to modify the path, such as appendEdge(GraphEdgeI), actually return a new GraphPath instance, leaving the original path unaltered. This immutability makes GraphPath objects inherently thread-safe and reliable for use in concurrent environments or as keys in hash-based collections (provided equals(Object) and hashCode() are correctly implemented).

Structure: A path is fundamentally defined by its start node and an ordered sequence of its edges (which are GraphEdgeI instances).

• A path can consist solely of a start node if it has no edges. In this scenario, the getStartNode() is also considered the getEndNode().
• For a path with one or more edges:
  • The first edge in the sequence (edges[0]) should originate from the getStartNode() (i.e., edges[0].getFromNode() should be equivalent to startNode).
  • Each subsequent edge edges[i] should start from the node where the previous edge edges[i-1] ended (i.e., edges[i].getFromNode() should be equivalent to edges[i-1].getToNode()).
  This forms a continuous walk through the graph. The final node reached after traversing all edges is accessible via getEndNode().

Usage: This class is typically used to:

• Represent the output of graph traversal or pathfinding algorithms (e.g., Dijkstra's, A*).
• Log or reconstruct a sequence of steps taken through a graph.
• Define specific routes for analysis, processing, or visualization.

Key methods for interacting with a path include getStartNode(), getEndNode(), and appendEdge(GraphEdgeI) for creating a new, extended path.

See Also:

The interface for graph nodes that form the start/end points and connections., The interface for graph edges that constitute the segments of the path.

Field Summary

Fields

Modifier and Type	Field and Description
GraphEdgeI[]	edges The sequence of edges forming this path.
OnlyToDirectedGraphNodeI	startNode The starting node of this path.

Constructor Summary

Constructors

Constructor and Description
GraphPath(GraphPath basePath, GraphEdgeI newEdge) Constructs a new GraphPath by taking a base path and appending a new edge.
GraphPath(OnlyToDirectedGraphNodeI startNode) Constructs a GraphPath with a specified start node and no edges.

Method Summary

Modifier and Type	Method and Description
GraphPath	appendEdge(GraphEdgeI newEdge) Appends a new edge to the current path, returning a new GraphPath instance.
boolean	equals(java.lang.Object o)
OnlyToDirectedGraphNodeI	getEndNode() Returns the ending node of this path.
OnlyToDirectedGraphNodeI	getStartNode() Returns the starting node of this path.
int	hashCode()
java.lang.String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

startNode

public final OnlyToDirectedGraphNodeI startNode

The starting node of this path.

edges

public final GraphEdgeI[] edges

The sequence of edges forming this path. This array is effectively immutable after the GraphPath object is constructed. It's an empty array if the path consists only of the start node.

Constructor Detail

GraphPath

public GraphPath(OnlyToDirectedGraphNodeI startNode)

Constructs a GraphPath with a specified start node and no edges.

Parameters:

startNode - The starting node of the path. Must not be null.

GraphPath

public GraphPath(GraphPath basePath,
                 GraphEdgeI newEdge)

Constructs a new GraphPath by taking a base path and appending a new edge. This constructor is typically used by methods like appendEdge(GraphEdgeI).

Parameters:

basePath - The base path. Must not be null.

newEdge - The new edge to append. Must not be null.

Throws:

java.lang.IllegalArgumentException - if the newEdge does not logically follow the basePath (Note: specific internal validation for edge connectivity might be subject to implementation details or specific use-case relaxations, as indicated by any FIXME comments within the constructor's source).

Method Detail

appendEdge

public GraphPath appendEdge(GraphEdgeI newEdge)

Appends a new edge to the current path, returning a new GraphPath instance. The original GraphPath remains unchanged, ensuring immutability.

Parameters:

newEdge - The edge to append. Must not be null.

Returns:

A new GraphPath instance representing the current path extended by the new edge.

getStartNode

public OnlyToDirectedGraphNodeI getStartNode()

Returns the starting node of this path.

Returns:

The starting OnlyToDirectedGraphNodeI of the path.

getEndNode

public OnlyToDirectedGraphNodeI getEndNode()

Returns the ending node of this path. If the path has no edges, this is the startNode. Otherwise, it's the 'toNode' of the last edge in the path.

Returns:

The ending OnlyToDirectedGraphNodeI of the path.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object