com.github.rinde.rinsim.geom.Graph Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of rinsim-geom Show documentation
There is a newer version: 4.4.6
/*
 * Copyright (C) 2011-2016 Rinde van Lon, iMinds-DistriNet, KU Leuven
 *
 * 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.github.rinde.rinsim.geom;

import java.util.Collection;
import java.util.Set;

import org.apache.commons.math3.random.RandomGenerator;

import com.google.common.base.Optional;

/**
 * Common interface for graphs (V,E). Nodes are represented by {@link Point}s
 * and connections are represented by {@link Connection}s. Graphs are directed.
 * @author Rinde van Lon
 * @author Bartosz Michalik - added connection data handling
 * @param  The type of {@link ConnectionData} that is used in the
 *          connections.
 * @since 1.0
 */
public interface Graph {

  /**
   * Checks whether the specified point is a node in this graph.
   * @param node The node to check.
   * @return true if the point is a node in this graph,
   *         false otherwise.
   */
  boolean containsNode(Point node);

  /**
   * @param node The node to check for outgoing connections.
   * @return The outgoing connections starting from the specified node.
   */
  Collection getOutgoingConnections(Point node);

  /**
   * @param node The node to check for incoming connections.
   * @return The incoming connections starting from the specified node.
   */
  Collection getIncomingConnections(Point node);

  /**
   * Checks if a directed connection between from and
   * to exists.
   * @param from The starting node.
   * @param to The end node.
   * @return true if the connection exist, false
   *         otherwise.
   */
  boolean hasConnection(Point from, Point to);

  /**
   * Checks if the same (as defined by {@link Connection#equals(Object)})
   * connection exists in this graph.
   * @param  The type of connection.
   * @param connection The connection to check.
   * @return true if the connection exist, false
   *         otherwise.
   */
   boolean hasConnection(Connection connection);

  /**
   * Returns a {@link Connection} between from and to.
   * @param from The starting node.
   * @param to The end node.
   * @return the {@link Connection}.
   * @throws IllegalArgumentException if connection does not exist.
   */
  Connection getConnection(Point from, Point to);

  /**
   * Get the data associated with connection.
   * @param from Start of connection
   * @param to End of connection
   * @return connection data or {@link Optional#absent()} if there is no data or
   *         connection does not exists.
   */
  Optional connectionData(Point from, Point to);

  /**
   * Computes the length of the connection between from and
   * to.
   * @param from Start of connection.
   * @param to End of connection.
   * @return The length of the connection.
   * @throws IllegalArgumentException if connection does not exist.
   */
  double connectionLength(Point from, Point to);

  /**
   * @return The total number of connections in this graph.
   */
  int getNumberOfConnections();

  /**
   * @return All connections in this graph.
   */
  Set> getConnections();

  /**
   * @return The total number of nodes in this graph.
   */
  int getNumberOfNodes();

  /**
   * @return All nodes in this graph.
   */
  Set getNodes();

  /**
   * Add connection to the graph.
   * @param from starting node
   * @param to end node
   * @param connectionData data associated with the connection
   * @throws IllegalArgumentException if the connection already exists.
   */
  void addConnection(Point from, Point to, E connectionData);

  /**
   * Add a connection to the graph.
   * @param from Starting node
   * @param to End node
   * @throws IllegalArgumentException if the connection already exists.
   */
  void addConnection(Point from, Point to);

  /**
   * Add connection to the graph.
   * @param connection the connection to add.
   * @throws IllegalArgumentException if the connection already exists.
   */
  void addConnection(Connection connection);

  /**
   * Set connection data. Precondition: connection from -> to exists.
   * @param from Start point of connection.
   * @param to End point of connection.
   * @param connectionData The connection data used for the connection.
   * @return old connection data or {@link Optional#absent()} if there was no
   *         connection data.
   * @throws IllegalArgumentException when the connection between nodes do not
   *           exist.
   */
  Optional setConnectionData(Point from, Point to, E connectionData);

  /**
   * Remove connection data. Precondition: connection from -> to exists.
   * @param from Start point of connection.
   * @param to End point of connection.
   * @return old connection data or {@link Optional#absent()} if there was no
   *         connection data.
   * @throws IllegalArgumentException when the connection between nodes do not
   *           exist.
   */
  Optional removeConnectionData(Point from, Point to);

  /**
   * Adds connections to the graph.
   * @param connections The connections to add.
   * @throws IllegalArgumentException if any of the connections already exists.
   */
  void addConnections(Iterable> connections);

  /**
   * Merges other into this graph.
   * @param other The graph to merge into this graph.
   */
  void merge(Graph other);

  /**
   * @return true if this graph contains no nodes and connections,
   *         false otherwise.
   */
  boolean isEmpty();

  /**
   * Removes the specified node from the graph, all connected connections
   * (incoming and outgoing) are removed as well.
   * @param node The node to remove.
   */
  void removeNode(Point node);

  /**
   * Removes connection between from and to.
   * @param from Start node of connection.
   * @param to End node of connection.
   * @throws IllegalArgumentException if connection does not exist.
   */
  void removeConnection(Point from, Point to);

  /**
   * Get a random node in graph.
   * @param generator used to generate the random point.
   * @return random {@link Point}
   */
  Point getRandomNode(RandomGenerator generator);

}