/*
* GeoTools - The Open Source Java GIS Toolkit
* http://geotools.org
*
* (C) 2002-2008, Open Source Geospatial Foundation (OSGeo)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*/
package org.geotools.graph.build;
import java.util.Collection;
import org.geotools.graph.structure.Edge;
import org.geotools.graph.structure.Graph;
import org.geotools.graph.structure.Node;
/**
* Build the physical components of a Graph. The GraphBuilder manages the
* details of component creation, addition, and removal from the graph.<BR>
* <BR>
* Graph components are created through calls to buildNode() and buildEdge(Node,
* Node), and then added to the graph through calls to addNode(Node), and
* addEdge(Edge).<BR>
* <BR>
* The GraphBuilder class is the lower level of the graph construction process.
* The builder does not manage the entities being modelled by the graph
* components. This is done at a higher level by the GraphGenerator.
* class.
*
* @see Graph
* @see GraphGenerator
*
* @author Justin Deoliveira, Refractions Research Inc, jdeolive@refractions.net
*
*
* @source $URL$
*/
public interface GraphBuilder {
/**
* Returns the graph being built.
*
* @return Graph The graph being built.
*/
public Graph getGraph();
/**
* Builds a new node for the graph. This method does not add the new node to
* the graph, this must be done with the addNode(Node) method.
*
* @return Node The newly built node.
*/
public Node buildNode();
/**
* Builds a new edge for the graph. This method does not add the new node to
* the graph, this must be done with the addEdge(Edge) method.
*
* @param nodeA Adjacent node to edge.
* @param nodeB Adjacent node to edge.
*
* @return Edge the newly built Edge.
*/
public Edge buildEdge(Node nodeA, Node nodeB);
/**
* Adds a node to the graph.
*
* @param node Node to be added to graph.
*/
public void addNode(Node node);
/**
* Adds an edge to the graph.
*
* @param edge Edge to be added to graph.
*/
public void addEdge(Edge edge);
/**
* Removes an node from the graph.
*
* @param node Node to be removed from graph.
*/
public void removeNode(Node node);
/**
* Removes a collection of nodes from the graph.
*
* @param nodes A collection of nodes to be removed from the graph.
*/
public void removeNodes(Collection nodes);
/**
* Removes an edge from the graph.
*
* @param edge Edge to be removed from graph.
*/
public void removeEdge(Edge edge);
/**
* Removes a collection of edges from the graph.
*
* @param edges Collection of edges to be removed from the graph.
*/
public void removeEdges(Collection edges);
/**
* Returns a clone of the builder. A deep clone copies the underlying
* graph structure, a non deep clone results in an empty builder
*
* @param deep Deep or non deep clone.
*
* @return A graph builder.
*/
public Object clone(boolean deep) throws Exception;
/** Constructs a graph builder from a pre built graph. The nodes and edges
* of the existing graph are imported into the builder. Relationships between
* nodes and edges are assummed to be preexistant.
*
* @param g A pre built graph.
*/
public void importGraph(Graph g);
}