--- a/gnv-artifacts/src/main/java/de/intevation/gnv/chart/AbstractXYLineChart.java	Tue Mar 23 14:11:51 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/chart/AbstractXYLineChart.java	Wed Mar 24 14:48:55 2010 +0000
@@ -29,36 +29,107 @@
 
 
 /**
- * @author Ingo Weinzierl <ingo.weinzierl@intevation.de>
+ * This abstract class defines some methods to adjust chart settings after its
+ * creation.
+ *
+ * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  */
 public abstract class AbstractXYLineChart
 extends               AbstractChart
 {
+    /**
+     * Constant field used to expand the area between data and chart border. Its
+     * value is {@value}.<br>
+     * A value of 0.05 equals 5 percent.
+     */
     public static final double LOWER_MARGIN = 0.05D;
+
+    /**
+     * Constant field used to expand the area between data and chart border. Its
+     * value is {@value}.<br>
+     * A value of 0.05 equals 5 percent.
+     */
     public static final double UPPER_MARGIN = 0.05D;
 
+    /**
+     * Logger used to log with log4j.
+     */
     private static Logger log      = Logger.getLogger(AbstractXYLineChart.class);
 
+    /**
+     * Field of supported colors used for lines and data points in charts.
+     * Colors are: {@value}.
+     */
     protected static Color[] COLOR = {
         Color.black, Color.red, Color.green, Color.blue, Color.yellow,
         Color.gray, Color.orange, Color.pink, Color.cyan
     };
 
+    /**
+     * Static field to remember the index of the previously used color.
+     */
     protected static int nextColor = 0;
 
+    /**
+     * Default <code>PlotOrientation</code>. Its value is {@value}.
+     */
     protected PlotOrientation PLOT_ORIENTATION = PlotOrientation.VERTICAL;
 
-    /** Map to store datasets for each parameter */
+    /**
+     * Map to store datasets for each parameter.
+     */
     protected Map datasets;
 
-    /** Map to store max ranges of each parameter (axis.setAutoRange(true)
+    /**
+     * Map to store max ranges of each parameter (axis.setAutoRange(true)
      * doesn't seem to work */
     protected Map ranges;
 
+    /**
+     * This method is called by <code>Chart</code> to bring the data into the
+     * right form fitting to JFreeChart objects.
+     */
     protected abstract void initData();
+
+    /**
+     * Add a value of <code>row</code> to <code>series</code>.
+     *
+     * @param row <code>Result</code> Object returned from database. Contains
+     * a value used to add to <code>series</code>
+     * @param series A JFreeChart Series object.
+     */
     protected abstract void addValue(Result row, Series series);
+
+    /**
+     * Add <code>series</code> to JFreeChart's Dataset object currently which is
+     * processing.
+     *
+     * @param series Series to add.
+     * @param label Label used show in legend.
+     * @param idx Currently not used.
+     */
     protected abstract void addSeries(Series series, String label, int idx);
+
+    /**
+     * Abstract method which is called by <code>Chart</code> interface after
+     * chart creation. It turns an axis' label into a locale specific format.
+     *
+     * @param axis Axis to adjust.
+     * @param local java.util.Locale object used specify the format.
+     */
     protected abstract void localizeDomainAxis(Axis axis, Locale locale);
+
+    /**
+     * Abstract method to create a label for a series of parameters.
+     *
+     * @param breakPoint1 Identifier returned from database. These identifier
+     * are used to identify the results from database which are all stored in
+     * one big java.util.Collection.
+     * @param breakPoint2 Identifier returned from database.
+     * @param breakPoint3 Identifier returned from database.
+     *
+     * @return Concatinated string of parameter name and measurement.
+     */
     protected abstract String createSeriesName(
         String breakPoint1,
         String breakPoint2,
@@ -66,6 +137,9 @@
     );
 
 
+    /**
+     * @see de.intevation.gnv.chart.Chart#generateChart()
+     */
     public JFreeChart generateChart() {
         log.debug("generate XYLineChart");
         nextColor = 0;
@@ -86,6 +160,9 @@
     }
 
 
+    /**
+     * @see de.intevation.gnv.chart.AbstractChart#initChart()
+     */
     protected void initChart() {
         chart = ChartFactory.createXYLineChart(
             labels.getTitle(),
@@ -100,6 +177,18 @@
     }
 
 
+    /**
+     * Method used to adjust the axes after chart generation. Methods for i18n
+     * support ({@link #localizeDomainAxis and {@link #localizeRangeAxis) are
+     * called and axes of this series are expanded ({@link org.jfree.data.Range#expand(
+     * Range, double, double}).
+     *
+     * @param seriesKey Identifier of an axis which have to be adjusted.
+     * @param idx Set the axis identified by <code>seriesKey</code> to position
+     * <code>idx</code>.
+     *
+     * @see org.jfree.data.Range#expand(Range, double, double)
+     */
     protected void prepareAxis(String seriesKey, int idx) {
         log.debug("prepare axis of xychart");
 
@@ -138,6 +227,16 @@
     }
 
 
+    /**
+     * Method to adjust the rendering of a series in a chart. Line color and
+     * symbols of vertices are configured here.
+     *
+     * @param idx Position of the renderer.
+     * @param seriesCount Maximum number of series in this chart.
+     * @param renderLines Lines are displayed if true, otherwise they are not.
+     * @param renderShapes Vertices are displayed if true, otherwise they are
+     * not.
+     */
     protected void adjustRenderer(
         int     idx,
         int     seriesCount,
@@ -169,12 +268,27 @@
     }
 
 
+    /**
+     * Method to adjust the plot rendering. Disable horizontal grid lines if 
+     * <code>plot</code> contains only a single y-axis.
+     *
+     * @param plot JFreeChart Plot object to be adjusted.
+     */
     protected void adjustPlot(XYPlot plot) {
         if (plot.getRangeAxisCount() > 1)
             plot.setRangeGridlinesVisible(false);
     }
 
 
+    /**
+     * Abstract method which is called after chart creation. It turns an 
+     * axis' label into a locale specific format.
+     *
+     * @param axis Axis to adjust.
+     * @param local java.util.Locale object used specify the format.
+     *
+     * @param axis
+     */
     protected void localizeRangeAxis(Axis axis, Locale locale) {
         if (locale == null)
             return;
@@ -189,6 +303,13 @@
     }
 
 
+    /**
+     * Return the maximum y-range of <code>dataset</code>.
+     *
+     * @param dataset Dataset to be scaned.
+     *
+     * @return JFreeChart Range object containing min and max y-value.
+     */
     public Range getMaxRangeOfDataset(XYDataset dataset) {
         int    seriesCount = dataset.getSeriesCount();
         double upper       = Double.NEGATIVE_INFINITY;
@@ -212,6 +333,15 @@
     }
 
 
+    /**
+     * Return the maximum y-range of <code>dataset</code> with a margin of
+     * <code>percent</code> percent.
+     *
+     * @param dataset Dataset to be scaned.
+     *
+     * @return JFreeChart Range object containing min and max y-value with a
+     * margin.
+     */
     public Range getMaxRangeOfDatasetWithMargin(
         XYDataset dataset,
         double    percent
@@ -225,6 +355,13 @@
     }
 
 
+    /**
+     * Method to find a parameter specified by its value.
+     *
+     * @param label Search string.
+     *
+     * @return Value of a parameter with the given label.
+     */
     protected String findParameter(String label) {
         Iterator iter = parameters.iterator();
 
@@ -240,6 +377,14 @@
     }
 
 
+    /**
+     * Method to find a description of a given collection of values.
+     *
+     * @param values Collection to be scaned.
+     * @param id Identifier and search string of the searched value.
+     *
+     * @return title
+     */
     protected String findValueTitle(Collection values, String id) {
         log.debug("find description of dataset");
 
@@ -256,6 +401,15 @@
     }
 
 
+    /**
+     * Method to store the maximum range. Since we need to adjust the range of
+     * each range axis, we have to memorize its range - each parameter uses an
+     * own range axis.
+     *
+     * @param ranges Map where ranges of each axis will be stored in.
+     * @param value A given value on an axis.
+     * @param parameter Parameter name which belongs to <code>value</code>.
+     */
     protected void storeMaxRange(Map ranges, double value, String parameter) {
         Range  range     = null;