View Javadoc
1   /*
2    * Copyright (C) 2016 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package com.google.common.graph;
18  
19  import static com.google.common.base.Preconditions.checkNotNull;
20  import static com.google.common.graph.Graphs.checkNonNegative;
21  
22  import com.google.common.annotations.Beta;
23  import com.google.common.base.Optional;
24  
25  /**
26   * A builder for constructing instances of {@link MutableValueGraph} with user-defined properties.
27   *
28   * <p>A graph built by this class will have the following properties by default:
29   *
30   * <ul>
31   * <li>does not allow self-loops
32   * <li>orders {@link Graph#nodes()} in the order in which the elements were added
33   * </ul>
34   *
35   * <p>Example of use:
36   *
37   * <pre>{@code
38   * MutableValueGraph<String, Double> graph =
39   *     ValueGraphBuilder.undirected().allowsSelfLoops(true).build();
40   * graph.putEdgeValue("San Francisco", "San Francisco", 0.0);
41   * graph.putEdgeValue("San Jose", "San Jose", 0.0);
42   * graph.putEdgeValue("San Francisco", "San Jose", 48.4);
43   * }</pre>
44   *
45   * @author James Sexton
46   * @author Joshua O'Madadhain
47   * @since 20.0
48   */
49  @Beta
50  public final class ValueGraphBuilder<N, V> extends AbstractGraphBuilder<N> {
51  
52    /** Creates a new instance with the specified edge directionality. */
53    private ValueGraphBuilder(boolean directed) {
54      super(directed);
55    }
56  
57    /** Returns a {@link ValueGraphBuilder} for building directed graphs. */
58    public static ValueGraphBuilder<Object, Object> directed() {
59      return new ValueGraphBuilder<>(true);
60    }
61  
62    /** Returns a {@link ValueGraphBuilder} for building undirected graphs. */
63    public static ValueGraphBuilder<Object, Object> undirected() {
64      return new ValueGraphBuilder<>(false);
65    }
66  
67    /**
68     * Returns a {@link ValueGraphBuilder} initialized with all properties queryable from {@code
69     * graph}.
70     *
71     * <p>The "queryable" properties are those that are exposed through the {@link ValueGraph}
72     * interface, such as {@link ValueGraph#isDirected()}. Other properties, such as {@link
73     * #expectedNodeCount(int)}, are not set in the new builder.
74     */
75    public static <N, V> ValueGraphBuilder<N, V> from(ValueGraph<N, V> graph) {
76      return new ValueGraphBuilder<N, V>(graph.isDirected())
77          .allowsSelfLoops(graph.allowsSelfLoops())
78          .nodeOrder(graph.nodeOrder());
79    }
80  
81    /**
82     * Specifies whether the graph will allow self-loops (edges that connect a node to itself).
83     * Attempting to add a self-loop to a graph that does not allow them will throw an {@link
84     * UnsupportedOperationException}.
85     */
86    public ValueGraphBuilder<N, V> allowsSelfLoops(boolean allowsSelfLoops) {
87      this.allowsSelfLoops = allowsSelfLoops;
88      return this;
89    }
90  
91    /**
92     * Specifies the expected number of nodes in the graph.
93     *
94     * @throws IllegalArgumentException if {@code expectedNodeCount} is negative
95     */
96    public ValueGraphBuilder<N, V> expectedNodeCount(int expectedNodeCount) {
97      this.expectedNodeCount = Optional.of(checkNonNegative(expectedNodeCount));
98      return this;
99    }
100 
101   /** Specifies the order of iteration for the elements of {@link Graph#nodes()}. */
102   public <N1 extends N> ValueGraphBuilder<N1, V> nodeOrder(ElementOrder<N1> nodeOrder) {
103     ValueGraphBuilder<N1, V> newBuilder = cast();
104     newBuilder.nodeOrder = checkNotNull(nodeOrder);
105     return newBuilder;
106   }
107 
108   /**
109    * Returns an empty {@link MutableValueGraph} with the properties of this {@link
110    * ValueGraphBuilder}.
111    */
112   public <N1 extends N, V1 extends V> MutableValueGraph<N1, V1> build() {
113     return new ConfigurableMutableValueGraph<>(this);
114   }
115 
116   @SuppressWarnings("unchecked")
117   private <N1 extends N, V1 extends V> ValueGraphBuilder<N1, V1> cast() {
118     return (ValueGraphBuilder<N1, V1>) this;
119   }
120 }