com.google.common.graph.SuccessorsFunction Maven / Gradle / Ivy
/*
* Copyright (C) 2014 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.google.common.graph;
import com.google.common.annotations.Beta;
import com.google.errorprone.annotations.DoNotMock;
/**
* A functional interface for graph-structured data.
*
* This interface is meant to be used as the type of a parameter to graph algorithms (such as
* breadth first traversal) that only need a way of accessing the successors of a node in a graph.
*
*
Usage
*
* Given an algorithm, for example:
*
* {@code
* public someGraphAlgorithm(N startNode, SuccessorsFunction successorsFunction);
* }
*
* you will invoke it depending on the graph representation you're using.
*
* If you have an instance of one of the primary {@code common.graph} types ({@link Graph},
* {@link ValueGraph}, and {@link Network}):
*
*
{@code
* someGraphAlgorithm(startNode, graph);
* }
*
* This works because those types each implement {@code SuccessorsFunction}. It will also work with
* any other implementation of this interface.
*
* If you have your own graph implementation based around a custom node type {@code MyNode},
* which has a method {@code getChildren()} that retrieves its successors in a graph:
*
*
{@code
* someGraphAlgorithm(startNode, MyNode::getChildren);
* }
*
* If you have some other mechanism for returning the successors of a node, or one that doesn't
* return an {@code Iterable}, then you can use a lambda to perform a more general
* transformation:
*
*
{@code
* someGraphAlgorithm(startNode, node -> ImmutableList.of(node.leftChild(), node.rightChild()));
* }
*
* Graph algorithms that need additional capabilities (accessing both predecessors and
* successors, iterating over the edges, etc.) should declare their input to be of a type that
* provides those capabilities, such as {@link Graph}, {@link ValueGraph}, or {@link Network}.
*
*
Additional documentation
*
* See the Guava User Guide for the {@code common.graph} package ("Graphs Explained") for
* additional documentation, including notes for
* implementors
*
* @author Joshua O'Madadhain
* @author Jens Nyman
* @param Node parameter type
* @since 23.0
*/
@Beta
@DoNotMock("Implement with a lambda, or use GraphBuilder to build a Graph with the desired edges")
@ElementTypesAreNonnullByDefault
public interface SuccessorsFunction {
/**
* Returns all nodes in this graph adjacent to {@code node} which can be reached by traversing
* {@code node}'s outgoing edges in the direction (if any) of the edge.
*
* This is not the same as "all nodes reachable from {@code node} by following outgoing
* edges". For that functionality, see {@link Graphs#reachableNodes(Graph, Object)}.
*
*
Some algorithms that operate on a {@code SuccessorsFunction} may produce undesired results
* if the returned {@link Iterable} contains duplicate elements. Implementations of such
* algorithms should document their behavior in the presence of duplicates.
*
*
The elements of the returned {@code Iterable} must each be:
*
*
* - Non-null
*
- Usable as {@code Map} keys (see the Guava User Guide's section on
* graph elements for details)
*
*
* @throws IllegalArgumentException if {@code node} is not an element of this graph
*/
Iterable successors(N node);
}