com.google.common.graph.NetworkBuilder Maven / Gradle / Ivy
/*
* Copyright (C) 2016 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 static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.graph.Graphs.checkNonNegative;
import com.google.common.annotations.Beta;
import com.google.common.base.Optional;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
/**
* A builder for constructing instances of {@link MutableNetwork} or {@link ImmutableNetwork} with
* user-defined properties.
*
* A {@code Network} built by this class has the following default properties:
*
*
* - does not allow parallel edges
*
- does not allow self-loops
*
- orders {@link Network#nodes()} and {@link Network#edges()} in the order in which the
* elements were added (insertion order)
*
*
* {@code Network}s built by this class also guarantee that each collection-returning accessor
* returns a (live) unmodifiable view; see the external
* documentation for details.
*
*
Examples of use:
*
*
{@code
* // Building a mutable network
* MutableNetwork network =
* NetworkBuilder.directed().allowsParallelEdges(true).build();
* flightNetwork.addEdge("LAX", "ATL", 3025);
* flightNetwork.addEdge("LAX", "ATL", 1598);
* flightNetwork.addEdge("ATL", "LAX", 2450);
*
* // Building a immutable network
* ImmutableNetwork immutableNetwork =
* NetworkBuilder.directed()
* .allowsParallelEdges(true)
* .immutable()
* .addEdge("LAX", "ATL", 3025)
* .addEdge("LAX", "ATL", 1598)
* .addEdge("ATL", "LAX", 2450)
* .build();
* }
*
* @author James Sexton
* @author Joshua O'Madadhain
* @param The most general node type this builder will support. This is normally {@code Object}
* unless it is constrained by using a method like {@link #nodeOrder}, or the builder is
* constructed based on an existing {@code Network} using {@link #from(Network)}.
* @param The most general edge type this builder will support. This is normally {@code Object}
* unless it is constrained by using a method like {@link #edgeOrder}, or the builder is
* constructed based on an existing {@code Network} using {@link #from(Network)}.
* @since 20.0
*/
@Beta
@ElementTypesAreNonnullByDefault
public final class NetworkBuilder extends AbstractGraphBuilder {
boolean allowsParallelEdges = false;
ElementOrder edgeOrder = ElementOrder.insertion();
Optional expectedEdgeCount = Optional.absent();
/** Creates a new instance with the specified edge directionality. */
private NetworkBuilder(boolean directed) {
super(directed);
}
/** Returns a {@link NetworkBuilder} for building directed networks. */
public static NetworkBuilder directed() {
return new NetworkBuilder<>(true);
}
/** Returns a {@link NetworkBuilder} for building undirected networks. */
public static NetworkBuilder undirected() {
return new NetworkBuilder<>(false);
}
/**
* Returns a {@link NetworkBuilder} initialized with all properties queryable from {@code
* network}.
*
* The "queryable" properties are those that are exposed through the {@link Network} interface,
* such as {@link Network#isDirected()}. Other properties, such as {@link
* #expectedNodeCount(int)}, are not set in the new builder.
*/
public static NetworkBuilder from(Network network) {
return new NetworkBuilder(network.isDirected())
.allowsParallelEdges(network.allowsParallelEdges())
.allowsSelfLoops(network.allowsSelfLoops())
.nodeOrder(network.nodeOrder())
.edgeOrder(network.edgeOrder());
}
/**
* Returns an {@link ImmutableNetwork.Builder} with the properties of this {@link NetworkBuilder}.
*
* The returned builder can be used for populating an {@link ImmutableNetwork}.
*
* @since 28.0
*/
public ImmutableNetwork.Builder immutable() {
NetworkBuilder castBuilder = cast();
return new ImmutableNetwork.Builder<>(castBuilder);
}
/**
* Specifies whether the network will allow parallel edges. Attempting to add a parallel edge to a
* network that does not allow them will throw an {@link UnsupportedOperationException}.
*
* The default value is {@code false}.
*/
@CanIgnoreReturnValue
public NetworkBuilder allowsParallelEdges(boolean allowsParallelEdges) {
this.allowsParallelEdges = allowsParallelEdges;
return this;
}
/**
* Specifies whether the network will allow 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
* UnsupportedOperationException}.
*
* The default value is {@code false}.
*/
@CanIgnoreReturnValue
public NetworkBuilder allowsSelfLoops(boolean allowsSelfLoops) {
this.allowsSelfLoops = allowsSelfLoops;
return this;
}
/**
* Specifies the expected number of nodes in the network.
*
* @throws IllegalArgumentException if {@code expectedNodeCount} is negative
*/
@CanIgnoreReturnValue
public NetworkBuilder expectedNodeCount(int expectedNodeCount) {
this.expectedNodeCount = Optional.of(checkNonNegative(expectedNodeCount));
return this;
}
/**
* Specifies the expected number of edges in the network.
*
* @throws IllegalArgumentException if {@code expectedEdgeCount} is negative
*/
@CanIgnoreReturnValue
public NetworkBuilder expectedEdgeCount(int expectedEdgeCount) {
this.expectedEdgeCount = Optional.of(checkNonNegative(expectedEdgeCount));
return this;
}
/**
* Specifies the order of iteration for the elements of {@link Network#nodes()}.
*
* The default value is {@link ElementOrder#insertion() insertion order}.
*/
public NetworkBuilder nodeOrder(ElementOrder nodeOrder) {
NetworkBuilder newBuilder = cast();
newBuilder.nodeOrder = checkNotNull(nodeOrder);
return newBuilder;
}
/**
* Specifies the order of iteration for the elements of {@link Network#edges()}.
*
* The default value is {@link ElementOrder#insertion() insertion order}.
*/
public NetworkBuilder edgeOrder(ElementOrder edgeOrder) {
NetworkBuilder newBuilder = cast();
newBuilder.edgeOrder = checkNotNull(edgeOrder);
return newBuilder;
}
/** Returns an empty {@link MutableNetwork} with the properties of this {@link NetworkBuilder}. */
public MutableNetwork build() {
return new StandardMutableNetwork<>(this);
}
@SuppressWarnings("unchecked")
private NetworkBuilder cast() {
return (NetworkBuilder) this;
}
}