| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You 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. |
| --> |
| <document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| <properties> |
| <title>Commons Graph - Getting started</title> |
| <author email="dev@commons.apache.org">Commons Documentation Team</author> |
| </properties> |
| <body> |
| <section name="Understanding the model"> |
| <p>A <a href="../apidocs/org/apache/commons/graph/Graph.html">Graph</a> data structure consists of a finite set of |
| ordered pairs, called <a href="../apidocs/org/apache/commons/graph/Edge.html">Edge</a>s or arcs, of certain entity |
| called <a href="../apidocs/org/apache/commons/graph/Vertex.html">Vertex</a> or node.</p> |
| |
| <p>An <a href="../apidocs/org/apache/commons/graph/UndirectedGraph.html">UndirectedGraph</a> is one in which edges |
| have no orientation. The edge <code>(a, b)</code> is identical to the edge <code>(b, a)</code>, i.e., they are not |
| ordered pairs, but sets {u, v} (or 2-multisets) of vertices.</p> |
| |
| <p>A <a href="../apidocs/org/apache/commons/graph/DirectedGraph.html">DirectedGraph</a> is a Graph where an |
| edge <code>e = (a, b)</code> is considered to be directed from <code>a</code> to <code>b</code>; |
| <code>a</code> is called the head and <code>b</code> is called the tail of the arc.</p> |
| |
| <subsection name="Mutable Graphs"> |
| <p>A <a href="../apidocs/org/apache/commons/graph/MutableGraph">MutableGraph</a> is a graph that supports the |
| addition and removal of vertices and edges.</p> |
| |
| <p>The Apache Commons Graph design aims to eliminate all the boilerplate to describe vertices/edges relations |
| without sacrificing maintainability.</p> |
| |
| <p>In Apache Commons Graph users implement connections, the |
| <a href="../apidocs/org/apache/commons/graph/builder/GraphConnection.html">GraphConnection</a> passes a |
| <a href="../apidocs/org/apache/commons/graph/builder/GraphConnector.html">GraphConnector</a> to your connection, |
| and your module uses the connector to add vertices and link them through edges.</p> |
| |
| <source>class MyConnection |
| implements GraphConnection<BaseLabeledVertex, BaseLabeledWeightedEdge<Double>> |
| { |
| |
| public void connect( GraphConnector<BaseLabeledVertex, BaseLabeledWeightedEdge<Double>> graphConnector ) |
| { |
| BaseLabeledVertex start = graphConnector.addVertex( new BaseLabeledVertex( "start" ) ); |
| BaseLabeledVertex a = graphConnector.addVertex( new BaseLabeledVertex( "a" ) ); |
| BaseLabeledVertex b = graphConnector.addVertex( new BaseLabeledVertex( "b" ) ); |
| BaseLabeledVertex c = graphConnector.addVertex( new BaseLabeledVertex( "c" ) ); |
| BaseLabeledVertex d = graphConnector.addVertex( new BaseLabeledVertex( "d" ) ); |
| BaseLabeledVertex e = graphConnector.addVertex( new BaseLabeledVertex( "e" ) ); |
| BaseLabeledVertex goal = graphConnector.addVertex( new BaseLabeledVertex( "goal" ) ); |
| |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "start <-> a", 1.5D ) ).from( start ).to( a ); |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "start <-> d", 2D ) ).from( start ).to( d ); |
| |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "a <-> b", 2D ) ).from( a ).to( b ); |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "b <-> c", 3D ) ).from( b ).to( c ); |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "c <-> goal", 3D ) ).from( c ).to( goal ); |
| |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "d <-> e", 3D ) ).from( d ).to( e ); |
| graphConnector.addEdge( new BaseLabeledWeightedEdge<Double>( "e <-> goal", 2D ) ).from( e ).to( goal ); |
| } |
| |
| }</source> |
| |
| <p>DRY (Don't Repeat Yourself): Repeating "graphConnector" over and over for each binding can get a little tedious. |
| The Apache COmmons Graph package provides a support class named |
| <a href="../apidocs/org/apache/commons/graph/builder/AbstractGraphConnection.html">AbstractGraphConnection</a> |
| which implicitly gives you access to <code>GraphConnector</code>'s methods. For example, we could extend |
| <code>AbstractGraphConnection</code> and rewrite the above connections as:</p> |
| |
| <source>class MyConnection |
| extends AbstractGraphConnection<BaseLabeledVertex, BaseLabeledWeightedEdge<Double>> |
| { |
| |
| public void connect() |
| { |
| BaseLabeledVertex start = addVertex( new BaseLabeledVertex( "start" ) ); |
| BaseLabeledVertex a = addVertex( new BaseLabeledVertex( "a" ) ); |
| BaseLabeledVertex b = addVertex( new BaseLabeledVertex( "b" ) ); |
| BaseLabeledVertex c = addVertex( new BaseLabeledVertex( "c" ) ); |
| BaseLabeledVertex d = addVertex( new BaseLabeledVertex( "d" ) ); |
| BaseLabeledVertex e = addVertex( new BaseLabeledVertex( "e" ) ); |
| BaseLabeledVertex goal = addVertex( new BaseLabeledVertex( "goal" ) ); |
| |
| addEdge( new BaseLabeledWeightedEdge<Double>( "start <-> a", 1.5D ) ).from( start ).to( a ); |
| addEdge( new BaseLabeledWeightedEdge<Double>( "start <-> d", 2D ) ).from( start ).to( d ); |
| |
| addEdge( new BaseLabeledWeightedEdge<Double>( "a <-> b", 2D ) ).from( a ).to( b ); |
| addEdge( new BaseLabeledWeightedEdge<Double>( "b <-> c", 3D ) ).from( b ).to( c ); |
| addEdge( new BaseLabeledWeightedEdge<Double>( "c <-> goal", 3D ) ).from( c ).to( goal ); |
| |
| addEdge( new BaseLabeledWeightedEdge<Double>( "d <-> e", 3D ) ).from( d ).to( e ); |
| addEdge( new BaseLabeledWeightedEdge<Double>( "e <-> goal", 2D ) ).from( e ).to( goal ); |
| } |
| |
| }</source> |
| |
| <p>We'll use this syntax throughout the rest of the guide.</p> |
| |
| <p></p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
