Improve javadoc, refactor and clean up (graphhopper#70)

stefanholder · Dec 20, 2016 · c0d3323 · c0d3323
1 parent e2fe456
commit c0d3323
Show file tree

Hide file tree

Showing 4 changed files with 236 additions and 156 deletions.
diff --git a/matching-core/src/main/java/com/graphhopper/matching/EdgeMatch.java b/matching-core/src/main/java/com/graphhopper/matching/EdgeMatch.java
@@ -61,8 +61,8 @@ public double getMinDistance() {
 
         double min = Double.MAX_VALUE;
         for (GPXExtension gpxExt : gpxExtensions) {
-            if (gpxExt.queryResult.getQueryDistance() < min) {
-                min = gpxExt.queryResult.getQueryDistance();
+            if (gpxExt.getQueryResult().getQueryDistance() < min) {
+                min = gpxExt.getQueryResult().getQueryDistance();
             }
         }
         return min;

diff --git a/matching-core/src/main/java/com/graphhopper/matching/GPXExtension.java b/matching-core/src/main/java/com/graphhopper/matching/GPXExtension.java
@@ -19,36 +19,98 @@
 
 import com.graphhopper.routing.VirtualEdgeIteratorState;
 import com.graphhopper.storage.index.QueryResult;
+import com.graphhopper.util.EdgeIteratorState;
 import com.graphhopper.util.GPXEntry;
 
 /**
+ * During map matching this represents a map matching candidate, i.e. a potential snapped
+ * point of a GPX entry. After map matching, this represents the map matched point of
+ * an GPX entry.
+ * <p>
+ * A GPXEntry can either be at an undirected real (tower) node or at a directed virtual node.
+ * If this is at a directed virtual node then incoming paths from any previous GPXExtension
+ * should arrive through {@link #getIncomingVirtualEdge()} and outgoing paths to any following
+ * GPXExtension should start with {@link #getOutgoingVirtualEdge()}. This is achieved by
+ * penalizing other edges for routing. Note that virtual nodes are always connected to their
+ * adjacent nodes via 2 virtual edges (not counting reverse virtual edges).
  *
  * @author Peter Karich
+ * @author kodonnell
+ * @author Stefan Holder
  */
 public class GPXExtension {
-    final GPXEntry entry;
-    final QueryResult queryResult;
-    private boolean directed;
-    public VirtualEdgeIteratorState incomingVirtualEdge;
-    public VirtualEdgeIteratorState outgoingVirtualEdge;
+    private final GPXEntry entry;
+    private final QueryResult queryResult;
+    private final boolean isDirected;
+    private final EdgeIteratorState incomingVirtualEdge;
+    private final EdgeIteratorState outgoingVirtualEdge;
 
+    /**
+     * Creates an undirected candidate for a real node.
+     */
     public GPXExtension(GPXEntry entry, QueryResult queryResult) {
-    	this.entry = entry;
+        this.entry = entry;
         this.queryResult = queryResult;
-        this.directed = false;
+        this.isDirected = false;
+        this.incomingVirtualEdge = null;
+        this.outgoingVirtualEdge = null;
     }
-
-    public GPXExtension(GPXEntry entry, QueryResult queryResult, VirtualEdgeIteratorState incomingVirtualEdge, VirtualEdgeIteratorState outgoingVirtualEdge) {
-        this(entry, queryResult);
+
+    /**
+     * Creates a directed candidate for a virtual node.
+     */
+    public GPXExtension(GPXEntry entry, QueryResult queryResult,
+                        VirtualEdgeIteratorState incomingVirtualEdge,
+                        VirtualEdgeIteratorState outgoingVirtualEdge) {
+        this.entry = entry;
+        this.queryResult = queryResult;
+        this.isDirected = true;
         this.incomingVirtualEdge = incomingVirtualEdge;
         this.outgoingVirtualEdge = outgoingVirtualEdge;
-        this.directed = true;
     }
 
+    public GPXEntry getEntry() {
+        return entry;
+    }
+
+    public QueryResult getQueryResult() {
+        return queryResult;
+    }
+
+    /**
+     * Returns whether this GPXExtension is directed. This is true if the snapped point
+     * is a virtual node, otherwise the snapped node is a real (tower) node and false is returned.
+     */
     public boolean isDirected() {
-    	return directed;
+        return isDirected;
+    }
+
+    /**
+     * Returns the virtual edge that should be used by incoming paths.
+     *
+     * @throws IllegalStateException if this GPXExtension is not directed.
+     */
+    public EdgeIteratorState getIncomingVirtualEdge() {
+        if (!isDirected) {
+            throw new IllegalStateException(
+                    "This method may only be called for directed GPXExtensions");
+        }
+        return incomingVirtualEdge;
     }
-
+
+    /**
+     * Returns the virtual edge that should be used by outgoing paths.
+     *
+     * @throws IllegalStateException if this GPXExtension is not directed.
+     */
+    public EdgeIteratorState getOutgoingVirtualEdge() {
+        if (!isDirected) {
+            throw new IllegalStateException(
+                    "This method may only be called for directed GPXExtensions");
+        }
+        return outgoingVirtualEdge;
+    }
+
     @Override
     public String toString() {
         return "GPXExtension{" +
@@ -59,12 +121,4 @@ public String toString() {
                 ", outgoingEdge=" + outgoingVirtualEdge +
                 '}';
     }
-
-    public QueryResult getQueryResult() {
-        return this.queryResult;
-    }
-
-    public GPXEntry getEntry() {
-        return entry;
-    }
 }