All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.facebook.presto.jdbc.internal.guava.graph.Network Maven / Gradle / Ivy

There is a newer version: 0.289
Show newest version
/*
 * 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.facebook.presto.jdbc.internal.guava.graph;

import com.facebook.presto.jdbc.internal.guava.annotations.Beta;
import java.util.Optional;
import java.util.Set;
import org.checkerframework.checker.nullness.qual.Nullable;

/**
 * An interface for graph-structured data,
 * whose edges are unique objects.
 *
 * 

A graph is composed of a set of nodes and a set of edges connecting pairs of nodes. * *

There are three primary interfaces provided to represent graphs. In order of increasing * complexity they are: {@link Graph}, {@link ValueGraph}, and {@link Network}. You should generally * prefer the simplest interface that satisfies your use case. See the * "Choosing the right graph type" section of the Guava User Guide for more details. * *

Capabilities

* *

{@code Network} supports the following use cases (definitions of * terms): * *

    *
  • directed graphs *
  • undirected graphs *
  • graphs that do/don't allow parallel edges *
  • graphs that do/don't allow self-loops *
  • graphs whose nodes/edges are insertion-ordered, sorted, or unordered *
  • graphs whose edges are unique objects *
* *

Building a {@code Network}

* *

The implementation classes that {@code common.graph} provides are not public, by design. To * create an instance of one of the built-in implementations of {@code Network}, use the {@link * NetworkBuilder} class: * *

{@code
 * MutableNetwork graph = NetworkBuilder.directed().build();
 * }
* *

{@link NetworkBuilder#build()} returns an instance of {@link MutableNetwork}, which is a * subtype of {@code Network} that provides methods for adding and removing nodes and edges. If you * do not need to mutate a graph (e.g. if you write a method than runs a read-only algorithm on the * graph), you should use the non-mutating {@link Network} interface, or an {@link * ImmutableNetwork}. * *

You can create an immutable copy of an existing {@code Network} using {@link * ImmutableNetwork#copyOf(Network)}: * *

{@code
 * ImmutableNetwork immutableGraph = ImmutableNetwork.copyOf(graph);
 * }
* *

Instances of {@link ImmutableNetwork} do not implement {@link MutableNetwork} (obviously!) and * are contractually guaranteed to be unmodifiable and thread-safe. * *

The Guava User Guide has more * information on (and examples of) building graphs. * *

Additional documentation

* *

See the Guava User Guide for the {@code common.graph} package ("Graphs Explained") for * additional documentation, including: * *

* * @author James Sexton * @author Joshua O'Madadhain * @param Node parameter type * @param Edge parameter type * @since 20.0 */ @Beta public interface Network extends SuccessorsFunction, PredecessorsFunction { // // Network-level accessors // /** Returns all nodes in this network, in the order specified by {@link #nodeOrder()}. */ Set nodes(); /** Returns all edges in this network, in the order specified by {@link #edgeOrder()}. */ Set edges(); /** * Returns a live view of this network as a {@link Graph}. The resulting {@link Graph} will have * an edge connecting node A to node B if this {@link Network} has an edge connecting A to B. * *

If this network {@link #allowsParallelEdges() allows parallel edges}, parallel edges will be * treated as if collapsed into a single edge. For example, the {@link #degree(Object)} of a node * in the {@link Graph} view may be less than the degree of the same node in this {@link Network}. */ Graph asGraph(); // // Network properties // /** * Returns true if the edges in this network are directed. Directed edges connect a {@link * EndpointPair#source() source node} to a {@link EndpointPair#target() target node}, while * undirected edges connect a pair of nodes to each other. */ boolean isDirected(); /** * Returns true if this network allows parallel edges. Attempting to add a parallel edge to a * network that does not allow them will throw an {@link IllegalArgumentException}. */ boolean allowsParallelEdges(); /** * Returns true if this network allows self-loops (edges that connect a node to itself). * Attempting to add a self-loop to a network that does not allow them will throw an {@link * IllegalArgumentException}. */ boolean allowsSelfLoops(); /** Returns the order of iteration for the elements of {@link #nodes()}. */ ElementOrder nodeOrder(); /** Returns the order of iteration for the elements of {@link #edges()}. */ ElementOrder edgeOrder(); // // Element-level accessors // /** * Returns the nodes which have an incident edge in common with {@code node} in this network. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ Set adjacentNodes(N node); /** * Returns all nodes in this network adjacent to {@code node} which can be reached by traversing * {@code node}'s incoming edges against the direction (if any) of the edge. * *

In an undirected network, this is equivalent to {@link #adjacentNodes(Object)}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ @Override Set predecessors(N node); /** * Returns all nodes in this network adjacent to {@code node} which can be reached by traversing * {@code node}'s outgoing edges in the direction (if any) of the edge. * *

In an undirected network, this is equivalent to {@link #adjacentNodes(Object)}. * *

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)}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ @Override Set successors(N node); /** * Returns the edges whose {@link #incidentNodes(Object) incident nodes} in this network include * {@code node}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ Set incidentEdges(N node); /** * Returns all edges in this network which can be traversed in the direction (if any) of the edge * to end at {@code node}. * *

In a directed network, an incoming edge's {@link EndpointPair#target()} equals {@code node}. * *

In an undirected network, this is equivalent to {@link #incidentEdges(Object)}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ Set inEdges(N node); /** * Returns all edges in this network which can be traversed in the direction (if any) of the edge * starting from {@code node}. * *

In a directed network, an outgoing edge's {@link EndpointPair#source()} equals {@code node}. * *

In an undirected network, this is equivalent to {@link #incidentEdges(Object)}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ Set outEdges(N node); /** * Returns the count of {@code node}'s {@link #incidentEdges(Object) incident edges}, counting * self-loops twice (equivalently, the number of times an edge touches {@code node}). * *

For directed networks, this is equal to {@code inDegree(node) + outDegree(node)}. * *

For undirected networks, this is equal to {@code incidentEdges(node).size()} + (number of * self-loops incident to {@code node}). * *

If the count is greater than {@code Integer.MAX_VALUE}, returns {@code Integer.MAX_VALUE}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ int degree(N node); /** * Returns the count of {@code node}'s {@link #inEdges(Object) incoming edges} in a directed * network. In an undirected network, returns the {@link #degree(Object)}. * *

If the count is greater than {@code Integer.MAX_VALUE}, returns {@code Integer.MAX_VALUE}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ int inDegree(N node); /** * Returns the count of {@code node}'s {@link #outEdges(Object) outgoing edges} in a directed * network. In an undirected network, returns the {@link #degree(Object)}. * *

If the count is greater than {@code Integer.MAX_VALUE}, returns {@code Integer.MAX_VALUE}. * * @throws IllegalArgumentException if {@code node} is not an element of this network */ int outDegree(N node); /** * Returns the nodes which are the endpoints of {@code edge} in this network. * * @throws IllegalArgumentException if {@code edge} is not an element of this network */ EndpointPair incidentNodes(E edge); /** * Returns the edges which have an {@link #incidentNodes(Object) incident node} in common with * {@code edge}. An edge is not considered adjacent to itself. * * @throws IllegalArgumentException if {@code edge} is not an element of this network */ Set adjacentEdges(E edge); /** * Returns the set of edges directly connecting {@code nodeU} to {@code nodeV}. * *

In an undirected network, this is equal to {@code edgesConnecting(nodeV, nodeU)}. * *

The resulting set of edges will be parallel (i.e. have equal {@link #incidentNodes(Object)}. * If this network does not {@link #allowsParallelEdges() allow parallel edges}, the resulting set * will contain at most one edge (equivalent to {@code edgeConnecting(nodeU, nodeV).asSet()}). * * @throws IllegalArgumentException if {@code nodeU} or {@code nodeV} is not an element of this * network */ Set edgesConnecting(N nodeU, N nodeV); /** * Returns the single edge directly connecting {@code nodeU} to {@code nodeV}, if one is present, * or {@code Optional.empty()} if no such edge exists. * *

In an undirected network, this is equal to {@code edgeConnecting(nodeV, nodeU)}. * * @throws IllegalArgumentException if there are multiple parallel edges connecting {@code nodeU} * to {@code nodeV} * @throws IllegalArgumentException if {@code nodeU} or {@code nodeV} is not an element of this * network * @since 23.0 */ Optional edgeConnecting(N nodeU, N nodeV); /** * Returns the single edge directly connecting {@code nodeU} to {@code nodeV}, if one is present, * or {@code null} if no such edge exists. * *

In an undirected network, this is equal to {@code edgeConnectingOrNull(nodeV, nodeU)}. * * @throws IllegalArgumentException if there are multiple parallel edges connecting {@code nodeU} * to {@code nodeV} * @throws IllegalArgumentException if {@code nodeU} or {@code nodeV} is not an element of this * network * @since 23.0 */ @Nullable E edgeConnectingOrNull(N nodeU, N nodeV); /** * Returns true if there is an edge directly connecting {@code nodeU} to {@code nodeV}. This is * equivalent to {@code nodes().contains(nodeU) && successors(nodeU).contains(nodeV)}, and to * {@code edgeConnectingOrNull(nodeU, nodeV) != null}. * *

In an undirected graph, this is equal to {@code hasEdgeConnecting(nodeV, nodeU)}. * * @since 23.0 */ boolean hasEdgeConnecting(N nodeU, N nodeV); // // Network identity // /** * Returns {@code true} iff {@code object} is a {@link Network} that has the same elements and the * same structural relationships as those in this network. * *

Thus, two networks A and B are equal if all of the following are true: * *

    *
  • A and B have equal {@link #isDirected() directedness}. *
  • A and B have equal {@link #nodes() node sets}. *
  • A and B have equal {@link #edges() edge sets}. *
  • Every edge in A and B connects the same nodes in the same direction (if any). *
* *

Network properties besides {@link #isDirected() directedness} do not affect equality. * For example, two networks may be considered equal even if one allows parallel edges and the * other doesn't. Additionally, the order in which nodes or edges are added to the network, and * the order in which they are iterated over, are irrelevant. * *

A reference implementation of this is provided by {@link AbstractNetwork#equals(Object)}. */ @Override boolean equals(@Nullable Object object); /** * Returns the hash code for this network. The hash code of a network is defined as the hash code * of a map from each of its {@link #edges() edges} to their {@link #incidentNodes(Object) * incident nodes}. * *

A reference implementation of this is provided by {@link AbstractNetwork#hashCode()}. */ @Override int hashCode(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy