de.ipcon.tools.graph

Interface DirectedGraphNodeI

All Superinterfaces:

OnlyToDirectedGraphNodeI

All Known Subinterfaces:

EntityI

All Known Implementing Classes:

CBOEntity, EntityWrapper, InstrumentingEntity, VirtualEntity

public interface DirectedGraphNodeI
extends OnlyToDirectedGraphNodeI

Represents a node in a directed graph that is aware of both its incoming and outgoing edges. This interface extends OnlyToDirectedGraphNodeI by adding the capability to identify predecessor nodes and incoming edges.

Implementations of this interface provide a complete view of a node's local connectivity within a directed graph, allowing for bidirectional traversal and more comprehensive graph analysis (e.g., finding all paths, cycle detection, centrality measures).

In addition to the contract from OnlyToDirectedGraphNodeI for outgoing connections, this interface defines methods to access direct predecessor nodes (getFromNodes()) and the corresponding incoming edges (getIncomingEdges()).

See Also:

For nodes with only outgoing edge awareness., For the representation of edges.

Method Summary

Modifier and Type	Method and Description
java.util.Collection<? extends OnlyToDirectedGraphNodeI>	getFromNodes() Retrieves all direct predecessor nodes from which incoming edges to this node originate.
default java.util.Collection<GraphEdgeI>	getIncomingEdges() Retrieves all incoming directed edges that lead to this node.

Methods inherited from interface de.ipcon.tools.graph.OnlyToDirectedGraphNodeI

getOutgoingEdges, getToNodes

Method Detail

getFromNodes

java.util.Collection<? extends OnlyToDirectedGraphNodeI> getFromNodes()

Retrieves all direct predecessor nodes from which incoming edges to this node originate. These are the immediate "neighbors" in the backward direction of the graph. In a tree structure, this would typically be the parent of this node (if unique). In a more general directed graph, a node can have multiple predecessors.

Contract:

• Implementations of this method must not return null. If a node has no incoming edges (i.e., no predecessors, like a source node in a Directed Acyclic Graph (DAG)), an empty, non-null collection must be returned.
• The returned collection may or may not be modifiable by the caller; callers should generally not assume modifiability and treat it as read-only. If an immutable view is required, consider wrapping the returned collection (e.g., using Collections.unmodifiableCollection(Collection)).
• The order of nodes in the returned collection, if any, is implementation-dependent unless specified otherwise by the implementing class. Callers should not rely on a specific order unless documented by the concrete implementation.
• The collection should not contain null elements.

Returns:

A non-null, possibly empty, Collection of nodes (each implementing OnlyToDirectedGraphNodeI) representing all direct predecessor nodes. Each element in the collection is a node from which a single incoming edge leads to this node.

getIncomingEdges

default java.util.Collection<GraphEdgeI> getIncomingEdges()

Retrieves all incoming directed edges that lead to this node. Each edge connects a direct predecessor node (as obtained from getFromNodes()) to this node (as the destination/to-node).

This default implementation utilizes Java Streams. It processes the collection of nodes returned by getFromNodes(), filters out any null predecessor nodes, and then maps each valid predecessor node to a new DefaultGraphEdge. In these constructed edges, the predecessor node serves as the source (from-node), and this current node instance is the destination (to-node). The resulting edges are collected into a List.

Behavior of this default implementation:

• If getFromNodes() returns an empty collection, this method will also return an empty, non-null List.
• If getFromNodes() returns a collection containing null elements, these null elements are filtered out by the stream operation and will not result in edge creation.
• If getFromNodes() (contrary to its contract) were to return null, this default implementation returns an empty List due to the initial null check, ensuring robustness. However, implementers of getFromNodes() must adhere to its non-null return contract.
• The returned collection is a List, specifically an ArrayList, as created by Collectors.toList().

Overriding this method: Implementers of DirectedGraphNodeI may choose to override this default method if:

• They have a more direct or efficient way to access or construct incoming edge objects (e.g., if edges are stored explicitly or indexed by the target node).
• Their graph edges are instances of a specific subtype of GraphEdgeI (other than DefaultGraphEdge) or carry additional state or behavior.
• They need to control the specific instances or types of GraphEdgeI returned, or if DefaultGraphEdge(OnlyToDirectedGraphNodeI, OnlyToDirectedGraphNodeI) is not suitable for their edge creation logic for incoming edges.
• A different type of Collection is preferred for the result (e.g., a Set).

Returns:

A non-null, possibly empty, Collection (specifically a List in this default implementation) of GraphEdgeI instances representing all incoming edges to this node. In this default implementation, these are typically DefaultGraphEdge instances.

See Also:

getFromNodes(), GraphEdgeI, DefaultGraphEdge, For outgoing edges.