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

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;

/**
 * A builder for constructing instances of {@link MutableNetwork} or {@link ImmutableNetwork} with
 * user-defined properties.
 *
 * 

A network built by this class will have the following properties by default: * *

    *
  • 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 *
* *

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 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}. */ 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}. */ 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 */ 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 */ 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 ConfigurableMutableNetwork<>(this); } @SuppressWarnings("unchecked") private NetworkBuilder cast() { return (NetworkBuilder) this; } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy