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 com.google.errorprone.annotations.CanIgnoreReturnValue; 021 022/** 023 * A subinterface of {@link Graph} which adds mutation methods. When mutation is not required, users 024 * should prefer the {@link Graph} interface. 025 * 026 * @author James Sexton 027 * @author Joshua O'Madadhain 028 * @param <N> Node parameter type 029 * @since 20.0 030 */ 031@Beta 032@ElementTypesAreNonnullByDefault 033public interface MutableGraph<N> extends Graph<N> { 034 035 /** 036 * Adds {@code node} if it is not already present. 037 * 038 * <p><b>Nodes must be unique</b>, just as {@code Map} keys must be. They must also be non-null. 039 * 040 * @return {@code true} if the graph was modified as a result of this call 041 */ 042 @CanIgnoreReturnValue 043 boolean addNode(N node); 044 045 /** 046 * Adds an edge connecting {@code nodeU} to {@code nodeV} if one is not already present. 047 * 048 * <p>If the graph is directed, the resultant edge will be directed; otherwise, it will be 049 * undirected. 050 * 051 * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method will 052 * silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph. 053 * 054 * @return {@code true} if the graph was modified as a result of this call 055 * @throws IllegalArgumentException if the introduction of the edge would violate {@link 056 * #allowsSelfLoops()} 057 */ 058 @CanIgnoreReturnValue 059 boolean putEdge(N nodeU, N nodeV); 060 061 /** 062 * Adds an edge connecting {@code endpoints} (in the order, if any, specified by {@code 063 * endpoints}) if one is not already present. 064 * 065 * <p>If this graph is directed, {@code endpoints} must be ordered and the added edge will be 066 * directed; if it is undirected, the added edge will be undirected. 067 * 068 * <p>If this graph is directed, {@code endpoints} must be ordered. 069 * 070 * <p>If either or both endpoints are not already present in this graph, this method will silently 071 * {@link #addNode(Object) add} each missing endpoint to the graph. 072 * 073 * @return {@code true} if the graph was modified as a result of this call 074 * @throws IllegalArgumentException if the introduction of the edge would violate {@link 075 * #allowsSelfLoops()} 076 * @throws IllegalArgumentException if the endpoints are unordered and the graph is directed 077 * @since 27.1 078 */ 079 @CanIgnoreReturnValue 080 boolean putEdge(EndpointPair<N> endpoints); 081 082 /** 083 * Removes {@code node} if it is present; all edges incident to {@code node} will also be removed. 084 * 085 * @return {@code true} if the graph was modified as a result of this call 086 */ 087 @CanIgnoreReturnValue 088 boolean removeNode(N node); 089 090 /** 091 * Removes the edge connecting {@code nodeU} to {@code nodeV}, if it is present. 092 * 093 * @return {@code true} if the graph was modified as a result of this call 094 */ 095 @CanIgnoreReturnValue 096 boolean removeEdge(N nodeU, N nodeV); 097 098 /** 099 * Removes the edge connecting {@code endpoints}, if it is present. 100 * 101 * <p>If this graph is directed, {@code endpoints} must be ordered. 102 * 103 * @throws IllegalArgumentException if the endpoints are unordered and the graph is directed 104 * @return {@code true} if the graph was modified as a result of this call 105 * @since 27.1 106 */ 107 @CanIgnoreReturnValue 108 boolean removeEdge(EndpointPair<N> endpoints); 109}