--- a/gnv-artifacts/src/main/java/de/intevation/gnv/chart/VerticalProfileChart.java	Tue Mar 23 14:11:51 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/chart/VerticalProfileChart.java	Wed Mar 24 14:48:55 2010 +0000
@@ -23,24 +23,64 @@
 
 
 /**
- * @author Ingo Weinzierl <ingo.weinzierl@intevation.de>
+ * This class is used to create xy charts of vertical profiles.
+ *
+ * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  */
 public class VerticalProfileChart
 extends      AbstractXYLineChart
 {
+    /**
+     * Default axis identifier which is used if @see #getDependendAxisName does
+     * not return a value. The value of this field is {@value}.
+     */
     public static final String DEFAULT_AXIS = "KPOSITION";
 
+    /**
+     * Logger used for logging with log4j.
+     */
     private static Logger log = Logger.getLogger(VerticalProfileChart.class);
 
+    /**
+     * Constant used for gap detection. Its value is {@value}.
+     */
     protected final double PERCENTAGE     = 5.0;
+
+    /**
+     * Constnat used for gap detection in @see #gridDetection. Its value is
+     * {@value}.
+     */
     protected final double GAP_MAX_LEVEL  = Math.sqrt(2.0);
+
+    /**
+     * Constant used for gap detection in @see #addGaps. Its value is {@value}.
+     */
     protected final int    GAP_MAX_VALUES = 60;
 
-    /** Map to store max ranges of each parameter (axis.setAutoRange(true)
-     * doesn't seem to work properly. */
+    /**
+     * Map to store max ranges of each parameter 
+     * (org.jfree.chart.axis.Axis.setAutoRange(true) doesn't seem to work 
+     * properly.
+     */
     protected Map values;
 
 
+    /**
+     * Constructor used to create xy-charts.
+     *
+     * @param labels Labels used to be displayed in title, subtitle and so on.
+     * @param theme ChartTheme used to adjust the rendering of this chart.
+     * @param parameters Collection containing a bunch of parameters.
+     * @param measurements Collection containing a bunch of measurements.
+     * @param dates Collection containing a bunch of date objects.
+     * @param result Collection containing a bunch of <code>Result</code>
+     * objects which contain the actual data items to be displayed.
+     * @param timeGaps Collection with timegap definitions.
+     * @param locale Locale used to specify the format of labels, numbers, ...
+     * @param linesVisible Render lines between data points if true, otherwise
+     * not.
+     * @param shapesVisible Render vertices as points if true, otherwise not.
+     */
     public VerticalProfileChart(
         ChartLabels labels,
         ChartTheme  theme,
@@ -70,6 +110,10 @@
     }
 
 
+    /**
+     * @see de.intevation.gnv.chart.AbstractXYLineChart#initData()
+     */
+    @Override
     protected void initData() {
         log.debug("init data for VerticalProfileChart");
 
@@ -145,11 +189,32 @@
     }
 
 
+    /**
+     * Extract the important value from <code>Result</code> object.
+     *
+     * @param row <code>Result</code> object which contains a required value.
+     *
+     * @return X-ordinate
+     */
     protected Object getValue(Result row) {
         return row.getDouble("XORDINATE");
     }
 
 
+    /**
+     * General method to start a gap detection. The switch between standard gap
+     * detection method <code>addGaps</code> and a specialized method
+     * <code>addGapsOnGrid</code> is done by a parameter <code>DATEID</code>
+     * which is stored a each <code>Result</code> object. Specialized method is
+     * used if <code>DATEID</code> equals 2, otherwise the standard method is
+     * used.
+     *
+     * @param results Array of <code>Result</code> objects storing data of
+     * this chart.
+     * @param series Series used to add gaps.
+     * @param startPos Index of first element of series in results.
+     * @param endPos Index of last element of series in results.
+     */
     protected void gapDetection(
         Result[] results,
         Series   series,
@@ -165,6 +230,15 @@
     }
 
 
+    /**
+     * Method to expand max range of a range axis identified by seriesKey.
+     * <code>LOWER_MARGIN</code> and <code>UPPER_MARGIN</code> are used to
+     * expand the range.
+     *
+     * @param seriesKey Key to identify the series stored at the current
+     * Dataset.
+     * @param idx Currently not used.
+     */
     protected void prepareRangeAxis(String seriesKey, int idx) {
         XYPlot plot      = chart.getXYPlot();
         NumberAxis xAxis = (NumberAxis) plot.getDomainAxis();
@@ -175,6 +249,10 @@
     }
 
 
+    /**
+     * @see de.intevation.gnv.chart.AbstractXYLineChart#addValue(Result, Series)
+     */
+    @Override
     protected void addValue(Result row, Series series) {
         ((XYSeries) series).add(
             row.getDouble("XORDINATE"),
@@ -183,6 +261,11 @@
     }
 
 
+    /**
+     * @see de.intevation.gnv.chart.AbstractXYLineChart#addSeries(Series, String,
+     * int)
+     */
+    @Override
     protected void addSeries(Series series, String parameter, int idx) {
         log.debug("add series (" + parameter + ")to chart");
 
@@ -203,6 +286,10 @@
     }
 
 
+    /**
+     * Method to add processed datasets to plot. Each dataset is adjusted using
+     * <code>prepareAxis</code> and <code>adjustRenderer</code> methods.
+     */
     protected void addDatasets() {
         Iterator   iter = parameters.iterator();
         XYPlot     plot = chart.getXYPlot();
@@ -232,6 +319,13 @@
     }
 
 
+    /**
+     * Method used to store the max y-range of each parameter in this chart.
+     *
+     * @param values Map to store max values for each parameter.
+     * @param val Value used to be a Double.
+     * @param parameter Title used to identify a range object stored in values.
+     */
     protected void storeMaxValue(Map values, Object val, String parameter) {
         double value = ((Double) val).doubleValue();
         Range  range = null;
@@ -250,12 +344,22 @@
     }
 
 
+    /**
+     * @see de.intevation.gnv.chart.AbstractXYLineChart#localizeDomainAxis(Axis,
+     * Locale)
+     */
+    @Override
     protected void localizeDomainAxis(Axis axis, Locale locale) {
         // call localizeRangeAxis from superclass which formats NumberAxis
         super.localizeRangeAxis(axis, locale);
     }
 
 
+    /**
+     * @see de.intevation.gnv.chart.AbstractXYLineChart#createSeriesName(String,
+     * String, String)
+     */
+    @Override
     protected String createSeriesName(
         String breakPoint1,
         String breakPoint2,
@@ -269,6 +373,18 @@
     }
 
 
+    /**
+     * Method used to add gaps between data points on grids. The real detection
+     * is done in <code>gridDetection</code>.
+     *
+     * @param results Array of <code>Result</code> objects storing the relevant
+     * values.
+     * @param series Series object where the gaps are added to.
+     * @param startPos Index of first element which should be used in gap
+     * detection. Other series are stored in results as well.
+     * @param endPos Index of last element which should be used in gap
+     * detection.
+     */
     protected void addGapsOnGrid(
         Result[] results,
         Series   series,
@@ -307,6 +423,24 @@
     }
 
 
+    /**
+     * Standarad method to add gaps. There are two different methods to detect
+     * gaps. <code>simpleDetection</code> is used if the number of data points
+     * in this chart is lower than <code>GAP_MAX_VALUES</code>. Otherwise
+     * <code>specialDetection</code> is used. A data point with
+     * <code>null</code> value is added where a gap should be. This lets
+     * JFreeChart break the current graph.
+     *
+     * @param results Array of <code>Result</code> objects storing the relevant
+     * values.
+     * @param series Series object where the gaps are added to.
+     * @param startValue First data point value in series.
+     * @param endValue Last data point value in series.
+     * @param startPos Index of first data point in results which contains all
+     * data points of all series.
+     * @param endPos Index of last data point in results which contains all data
+     * points of all series.
+     */
     protected void addGaps(
         Result[] results,
         Series   series,
@@ -347,6 +481,21 @@
     }
 
 
+    /**
+     * Simple method to detect gaps. A gap is detected if the delta between two 
+     * data points (current, last) is bigger than <code>PERCENTAGE</code> percent 
+     * of delta of start and end. 
+     * <br>
+     * (smallDelta &gt; delta / 100 * PERCENTAGE)
+     *
+     * @param start First data point value in a series.
+     * @param end Last data point value in a series.
+     * @param last Left value
+     * @param current Right value
+     *
+     * @return true, if a gap is detected between last and current - otherwise
+     * false.
+     */
     protected boolean simpleDetection(
         double start,
         double end,
@@ -360,6 +509,21 @@
     }
 
 
+    /**
+     * Method to detect gaps between two data points. Following formula is used
+     * for detection:<br>
+     * smallDelta &gt; (3.0 / (count - 1) * delta)<br>
+     * smallDelta = current - last<br>
+     * delta      = end - start
+     *
+     * @param start First data point value in a series.
+     * @param end Last data point value in a series.
+     * @param last Left value
+     * @param current Right value
+     *
+     * @return true, if a gap is detected between last and current - otherwise
+     * false.
+     */
     protected boolean specialDetection(
         double start,
         double end,
@@ -374,6 +538,16 @@
     }
 
     
+    /**
+     * Method used to detect gaps between two data points grids. If the delta
+     * between current and last is bigger than <code>GAP_MAX_LEVEL</code>, a gap
+     * is detected.
+     *
+     * @param last Left value
+     * @param current Right value
+     *
+     * @return True, if a gap was detected - otherwise false.
+     */
     protected boolean gridDetection(double last, double current) {
         if (log.isDebugEnabled()) {
             log.debug("######################################################");
@@ -387,6 +561,15 @@
     }
 
 
+    /**
+     * This method returns the key which is used to retrieve the y-value served
+     * by a <code>Result</code> object. 
+     *
+     * @param first <code>Result</code> object - not used in this class.
+     * @param second <code>Result</code> object - not used in this class.
+     *
+     * @return the string "KPOSITION"
+     */
     protected String getDependendAxisName(Result first, Result second) {
         return "KPOSITION";
     }