001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: * (C) 2002, Refractions Reserach Inc.
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation;
010: * version 2.1 of the License.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: */
017: package org.geotools.graph.build;
018:
019: import java.util.Collection;
020:
021: import org.geotools.graph.structure.Edge;
022: import org.geotools.graph.structure.Graph;
023: import org.geotools.graph.structure.Node;
024:
025: /**
026: * Build the physical components of a Graph. The GraphBuilder manages the
027: * details of component creation, addition, and removal from the graph.<BR>
028: * <BR>
029: * Graph components are created through calls to buildNode() and buildEdge(Node,
030: * Node), and then added to the graph through calls to addNode(Node), and
031: * addEdge(Edge).<BR>
032: * <BR>
033: * The GraphBuilder class is the lower level of the graph construction process.
034: * The builder does not manage the entities being modelled by the graph
035: * components. This is done at a higher level by the GraphGenerator.
036: * class.
037: *
038: * @see Graph
039: * @see GraphGenerator
040: *
041: * @author Justin Deoliveira, Refractions Research Inc, jdeolive@refractions.net
042: *
043: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/extension/graph/src/main/java/org/geotools/graph/build/GraphBuilder.java $
044: */
045: public interface GraphBuilder {
046:
047: /**
048: * Returns the graph being built.
049: *
050: * @return Graph The graph being built.
051: */
052: public Graph getGraph();
053:
054: /**
055: * Builds a new node for the graph. This method does not add the new node to
056: * the graph, this must be done with the addNode(Node) method.
057: *
058: * @return Node The newly built node.
059: */
060: public Node buildNode();
061:
062: /**
063: * Builds a new edge for the graph. This method does not add the new node to
064: * the graph, this must be done with the addEdge(Edge) method.
065: *
066: * @param nodeA Adjacent node to edge.
067: * @param nodeB Adjacent node to edge.
068: *
069: * @return Edge the newly built Edge.
070: */
071: public Edge buildEdge(Node nodeA, Node nodeB);
072:
073: /**
074: * Adds a node to the graph.
075: *
076: * @param node Node to be added to graph.
077: */
078: public void addNode(Node node);
079:
080: /**
081: * Adds an edge to the graph.
082: *
083: * @param edge Edge to be added to graph.
084: */
085: public void addEdge(Edge edge);
086:
087: /**
088: * Removes an node from the graph.
089: *
090: * @param node Node to be removed from graph.
091: */
092: public void removeNode(Node node);
093:
094: /**
095: * Removes a collection of nodes from the graph.
096: *
097: * @param nodes A collection of nodes to be removed from the graph.
098: */
099: public void removeNodes(Collection nodes);
100:
101: /**
102: * Removes an edge from the graph.
103: *
104: * @param edge Edge to be removed from graph.
105: */
106: public void removeEdge(Edge edge);
107:
108: /**
109: * Removes a collection of edges from the graph.
110: *
111: * @param edges Collection of edges to be removed from the graph.
112: */
113: public void removeEdges(Collection edges);
114:
115: /**
116: * Returns a clone of the builder. A deep clone copies the underlying
117: * graph structure, a non deep clone results in an empty builder
118: *
119: * @param deep Deep or non deep clone.
120: *
121: * @return A graph builder.
122: */
123: public Object clone(boolean deep) throws Exception;
124:
125: /** Constructs a graph builder from a pre built graph. The nodes and edges
126: * of the existing graph are imported into the builder. Relationships between
127: * nodes and edges are assummed to be preexistant.
128: *
129: * @param g A pre built graph.
130: */
131: public void importGraph(Graph g);
132:
133: }
|