# HG changeset patch
# User Felix Wolfsteller <felix.wolfsteller@intevation.de>
# Date 1323345684 0
# Node ID 4781096f31f889ae5c1f5866dc36e282a595f02a
# Parent  be06dbc2ed1db747a38334689c24411ba4aeffdc
Mainly documentation.

flys-artifacts/trunk@3368 c6561f87-3c4e-4783-a992-168aeb5c3f6f

diff -r be06dbc2ed1d -r 4781096f31f8 flys-artifacts/ChangeLog
--- a/flys-artifacts/ChangeLog	Tue Dec 06 15:06:04 2011 +0000
+++ b/flys-artifacts/ChangeLog	Thu Dec 08 12:01:24 2011 +0000
@@ -1,4 +1,9 @@
-2011-11-30	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
+2011-12-08	Felix Wolfsteller	<felix.wolfsteller@intevation.de>
+
+	* src/main/java/de/intevation/flys/artifacts/services/CrossSectionKMService.java:
+	  Documentation added, let a value be its own neighbour (distance 0).
+
+2011-12-08	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
 
 	* src/main/java/de/intevation/flys/artifacts/states/CalculationSelect.java:
 	  Added "Bezugslinie" to list of calculation alternatives.
diff -r be06dbc2ed1d -r 4781096f31f8 flys-artifacts/src/main/java/de/intevation/flys/artifacts/services/CrossSectionKMService.java
--- a/flys-artifacts/src/main/java/de/intevation/flys/artifacts/services/CrossSectionKMService.java	Tue Dec 06 15:06:04 2011 +0000
+++ b/flys-artifacts/src/main/java/de/intevation/flys/artifacts/services/CrossSectionKMService.java	Thu Dec 08 12:01:24 2011 +0000
@@ -3,6 +3,7 @@
 import de.intevation.artifacts.CallMeta;
 import de.intevation.artifacts.GlobalContext;
 
+import de.intevation.artifacts.common.ArtifactNamespaceContext;
 import de.intevation.artifacts.common.utils.XMLUtils;
 
 import de.intevation.flys.artifacts.cache.CacheFactory;
@@ -12,6 +13,7 @@
 import de.intevation.flys.model.CrossSection;
 import de.intevation.flys.model.CrossSectionLine;
 
+import java.util.AbstractMap;
 import java.util.ArrayDeque;
 import java.util.Deque;
 import java.util.List;
@@ -31,6 +33,22 @@
 import org.w3c.dom.Element;
 import org.w3c.dom.NodeList;
 
+
+/**
+ * Service to find the next/previous km (measurement) of cross sections.
+ * Looking at the query for a single cross-section id at a single km, the
+ * service does the following:
+ *
+ * It returns the km itself if a measurement at that km was found and
+ * the N nearest other measurement points in both directions.
+ *
+ * That means, you can pass N=0 to find out whether a measurement at given km
+ * exists.
+ *
+ * If less than N neighbours exist in one direction, less are delivered
+ * (e.g. given measurements at [0,2,3,4,5,7,8,9] a query for km=8, N=3 will
+ * result in [4,5,7,8,9]).
+ */
 public class CrossSectionKMService
 extends      FLYSService
 {
@@ -39,9 +57,15 @@
 
     public static final String CACHE_NAME = "cross-section-kms";
 
+
+    /** Trivial constructor. */
     public CrossSectionKMService() {
     }
 
+
+    /**
+     * @param data
+     */
     @Override
     public Document doProcess(
         Document      data,
@@ -51,7 +75,7 @@
         logger.debug("CrossSectionKMService.doProcess");
 
         NodeList crossSectionNodes =
-            data.getElementsByTagName("cross-section");
+            data.getElementsByTagName("art:cross-section");
 
         Cache cache = CacheFactory.getCache(CACHE_NAME);
 
@@ -136,6 +160,12 @@
         return document;
     }
 
+
+    /**
+     * @param km  the kilometer from which to start searching for other
+     *            measurements
+     * @param N   number of neighboring measurements to find.
+     */
     public static Deque<Map.Entry<Double, Integer>> nearestNeighbors(
         NavigableMap<Double, Integer> map,
         double                        km,
@@ -144,6 +174,11 @@
         Deque<Map.Entry<Double, Integer>> result =
             new ArrayDeque<Map.Entry<Double, Integer>>(2*N);
 
+        if(map.get(km) != null) {
+            result.add(new AbstractMap.SimpleEntry<Double, Integer>(km,map.get(km)));
+
+        }
+
         int i = 0;
         for (Map.Entry<Double, Integer> entry:
              map.headMap(km, false).descendingMap().entrySet()) {
@@ -165,6 +200,11 @@
         return result;
     }
 
+
+    /**
+     * @param crossSectionId id of queried cross-section (in db).
+     * @return Mapping from kilometer to db-id.
+     */
     public static NavigableMap<Double, Integer> getUncached(
         Integer crossSectionId
     ) {