001/*
002 * Copyright (C) 2014 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.graph;
018
019import com.google.common.annotations.Beta;
020import java.util.Set;
021
022/**
023 * A functional interface for <a
024 * href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)">graph</a>-structured data.
025 *
026 * <p>This interface is meant to be used as the type of a parameter to graph algorithms (such as
027 * breadth first traversal) that only need a way of accessing the successors of a node in a graph.
028 *
029 * <h3>Usage</h3>
030 *
031 * Given an algorithm, for example:
032 *
033 * <pre>{@code
034 *   public <N> someGraphAlgorithm(N startNode, SuccessorsFunction<N> successorsFunction);
035 * }</pre>
036 *
037 * you will invoke it depending on the graph representation you're using.
038 *
039 * <p>If you have an instance of one of the primary {@code common.graph} types ({@link Graph},
040 * {@link ValueGraph}, and {@link Network}):
041 *
042 * <pre>{@code
043 *   someGraphAlgorithm(startNode, graph);
044 * }</pre>
045 *
046 * This works because those types each implement {@code SuccessorsFunction}. It will also work with
047 * any other implementation of this interface.
048 *
049 * <p>If you have your own graph implementation based around a custom node type {@code MyNode},
050 * which has a method {@code getChildren()} that retrieves its successors in a graph:
051 *
052 * <pre>{@code
053 *   someGraphAlgorithm(startNode, MyNode::getChildren);
054 * }</pre>
055 *
056 * <p>If you have some other mechanism for returning the successors of a node, or one that doesn't
057 * return a {@code Set<N>}, then you can use a lambda to perform a more general transformation:
058 *
059 * <pre>{@code
060 *   someGraphAlgorithm(startNode, node -> ImmutableSet.copyOf(node.getChildren());
061 * }</pre>
062 *
063 * <p>Graph algorithms that need additional capabilities (accessing both predecessors and
064 * successors, iterating over the edges, etc.) should declare their input to be of a type that
065 * provides those capabilities, such as {@link Graph}, {@link ValueGraph}, or {@link Network}.
066 *
067 * <h3>Additional documentation</h3>
068 *
069 * <p>See the Guava User Guide for the {@code common.graph} package (<a
070 * href="https://github.com/google/guava/wiki/GraphsExplained">"Graphs Explained"</a>) for
071 * additional documentation, including <a
072 * href="https://github.com/google/guava/wiki/GraphsExplained#notes-for-implementors">notes for
073 * implementors</a>
074 *
075 * @author Joshua O'Madadhain
076 * @author Jens Nyman
077 * @param <N> Node parameter type
078 * @since 22.0
079 */
080// TODO(b/35456940): Update the documentation to reflect the new interfaces
081@Beta
082public interface SuccessorsFunction<N> {
083
084  /**
085   * Returns all nodes in this graph adjacent to {@code node} which can be reached by traversing
086   * {@code node}'s outgoing edges in the direction (if any) of the edge.
087   *
088   * <p>This is <i>not</i> the same as "all nodes reachable from {@code node} by following outgoing
089   * edges". For that functionality, see {@link Graphs#reachableNodes(Graph, Object)}.
090   *
091   * @throws IllegalArgumentException if {@code node} is not an element of this graph
092   */
093  Set<N> successors(N node);
094}