--- a/gnv-artifacts/src/main/java/de/intevation/gnv/state/timeseries/TimeSeriesOutputState.java	Wed Apr 07 07:52:27 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/state/timeseries/TimeSeriesOutputState.java	Thu Apr 08 10:10:04 2010 +0000
@@ -86,12 +86,29 @@
  */
 public class TimeSeriesOutputState extends OutputStateBase {
 
+    /**
+     * A boolean property to enable caching of charts after they have been
+     * created. This property can be adjusted via system property 'cache.chart'.
+     * 'true' of 'false' are valid options - defaults to 'false'.<br>
+     * <b>NOTE:</b> If chart caching is enabled, charts aren't sensible to
+     * changes in the parameterization anymore, after a first chart has been
+     * created for an artifact.
+     */
     protected static final boolean CACHE_CHART =
         Boolean.parseBoolean(System.getProperty("cache.chart", "false"));
 
+    /**
+     * A field parsing a system property to adjust the alignment of pdf exports.
+     * The system property is 'export.pdf.landscape' and should be true or
+     * false. If this property is true, PDFs will be created in landscape
+     * format.
+     */
     protected static final boolean PDF_FORMAT_LANDSCAPE =
         Boolean.parseBoolean(System.getProperty("export.pdf.landscape","true"));
 
+    /**
+     * Supported image export formats.
+     */
     protected static final String[] IMG_EXPORT_FORMAT = {
         "PNG", "JPEG", "GIF"
     };
@@ -109,6 +126,9 @@
 
     private List<TimeGap> timeGapDefinitions = null;
 
+    /**
+     * Key in resource bundle the x-axis title is stored.
+     */
     protected String domainLable = "chart.timeseries.title.xaxis";
 
     protected String featureValuesName = "featureid";
@@ -116,6 +136,10 @@
     protected String measuremenValueName = "measurementid";
     protected String dateValueName = "dateid";
 
+
+    /**
+     * Array used to specify the columns used in csv exports.
+     */
     public static final String [] TIMESERIES_CSV_PROFILE_COLUMNS = {
         "XORDINATE",
         "YORDINATE",
@@ -125,6 +149,9 @@
     };
 
 
+    /**
+     * Column labels used in csv exports.
+     */
     public static final String [] TIMESERIES_TIMESERIES_CSV_COLUMN_LABEL = {
         "Date/Time",
         "Value",
@@ -133,6 +160,10 @@
         "TimeseriesID"
     };
 
+
+    /**
+     * Array used to specify the column in csv exports on meshes.
+     */
     public static final String [] TIMESERIES_MESH_CSV_COLUMN_LABEL = {
         "Date/Time",
         "Value",
@@ -141,6 +172,10 @@
         "MeshID"
     };
 
+
+    /**
+     * Array used to specify the columns in odv exports.
+     */
     public static final String [] TIMESERIES_ODV_PROFILE_NAMES = {
           "CRUISE",
           "STATION",
@@ -153,6 +188,9 @@
     };
 
 
+    /**
+     * Column labels used in odv exports.
+     */
     public static final String [] ODV_COLUMN_HEADER = {
         "Cruise",
         "Station",
@@ -165,6 +203,7 @@
         "QF"
     };
 
+    
     /**
      * Profile for exporting data to odv
      */
@@ -185,6 +224,16 @@
     }
 
 
+    /**
+     * Calls <code>getChartResult</code> which puts the data used for chart
+     * creation into cache. This redruces waiting periods after selecting an
+     * output type.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @param context The CallContext object.
+     * @throws StateException if an error occured while fetching the data used
+     * for chart creation.
+     */
     @Override
     public void initialize(String uuid, CallContext context)
     throws StateException
@@ -194,9 +243,39 @@
 
 
     /**
-     * @see de.intevation.gnv.transition.OutputTransition#out(java.lang.String,
-     *      java.util.Collection, java.io.OutputStream, java.lang.String,
-     *      de.intevation.artifacts.CallMeta)
+     * This out target has following modes:<br>
+     * <ol>
+     *  <li>chart: Creates a chart displaying the data corresponding to the
+     * current parameterization. A chart has following export modes:<br>
+     *      <ol>
+     *          <li>img: Image representation of a chart.</li>
+     *          <li>pdf: PDF representation of a chart.</li>
+     *          <li>svg: SVG representation of a chart.</li>
+     *      </ol>
+     * All selected parameters are drawn into a single chart.<br>
+     *  </li>
+     *  <li>histogram: Creates a histogram displaying the data corresponding to
+     * the current parameterization. A histogram has following export modes:<br>
+     *      <ol>
+     *          <li>img: Image representation of a histogram.</li>
+     *          <li>pdf: PDF representation of a histogram.</li>
+     *          <li>svg: SVG representation of a histogram.</li>
+     *      </ol>
+     * A single histogram is created for each selected parameter.<br>
+     *  </li>
+     *  <li>statistic: Creates a statistic with important figures.</li>
+     *  <li>csv: Creates a csv file.</li>
+     *  <li>odv: Creates a odv file.</li>
+     * </ol>
+     *
+     * @param format Document which contains some export specific information.
+     * @param inputData Contains some meta information to adjust the export
+     * (e.g. width and height of a chart).
+     * @param outputStream The output stream used to return the export.
+     * @param uuid The UUID of the current artifact.
+     * @param callContext The CallContext object.
+     * @throws StateException if an error occured while creating the export
+     * object.
      */
     public void out(
         Document              format,
@@ -437,6 +516,13 @@
     }
 
 
+    /**
+     * Retrieves the export format (e.g. png, gif, jpeg).
+     *
+     * @param mime Export format specified by the incoming  request.
+     * @return <i>mime</i> if it is supported - otherwise the first format in
+     * {@link #IMG_EXPORT_FORMAT}.
+     */
     protected String getExportFormat(String mime) {
         for(int i = 0; i < IMG_EXPORT_FORMAT.length; i++) {
             if (mime.trim().toUpperCase().indexOf(IMG_EXPORT_FORMAT[i]) > 0)
@@ -448,6 +534,14 @@
     }
 
 
+    /**
+     * Returns a collection containing all selected KeyValueDescibeData objects
+     * of <i>parameters</i>.
+     *
+     * @param parameters A collection with KeyValueDescibeData objects.
+     * @return a collection cleaned from unselected objects.
+     * @deprecated
+     */
     protected Collection getCleanedParameters(Collection parameters) {
         Iterator iter        = parameters.iterator();
         Collection parameter = new Vector(parameters);
@@ -461,11 +555,28 @@
     }
 
 
+    /**
+     * Calls {@link #getCleanedParameters(java.util.Collection)} with the
+     * collection returned by {@link #getParameters(java.lang.String)}.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @return a cleaned collection.
+     */
     protected Collection getCleanedParameters(String uuid) {
         return getCleanedParameters(getParameters(uuid));
     }
 
 
+    /**
+     * Create a csv file representing the data corresponding to the current
+     * parameterization.
+     *
+     * @param out The output stream used to export the csv file.
+     * @param results The data used for csv file creation.
+     * @throws UnsupportedEncodingException if the encoding is not supported.
+     * @throws IOException if an error occured while writing to output stream.
+     * @throws StateException if an error occured while creating the csv file.
+     */
     protected void createCSV(OutputStream out, Collection<Result> results)
     throws UnsupportedEncodingException, IOException, StateException
     {
@@ -507,7 +618,14 @@
 
 
     /**
-     * TODO Result is not used at the moment. Change result with correct data.
+     * Create an odv file representing the data corresponding to the current
+     * parameterization.
+     * 
+     * @param outputStream The output stream used to export the odv file.
+     * @param result The data used for odv file creation.
+     * @param uuid The UUID of the current artifact.
+     * @throws IOException if an error occured while writing to output stream.
+     * @throws StateException if an error occured while creating the odv file.
      */
     protected void createODV(OutputStream outputStream,
                              Collection result,
@@ -524,31 +642,43 @@
     }
 
     /**
-     * @return
+     * Returns the statistic generator.
+     *
+     * @return the statistic generator.
      */
     protected Statistics getStatisticsGenerator() {
         Statistics s = new TimeseriesStatistics();
         return s;
     }
 
+
+    /**
+     * Writes the statistic into an xml document.
+     *
+     * @param statistic Statistic to be written to xml document.
+     * @return the xml document containing the statistic.
+     */
     protected Document writeStatistics2XML( Collection<StatisticSet> statistic) {
         ArtifactXMLUtilities xmlUtilities = new ArtifactXMLUtilities();
         Document doc = XMLUtils.newDocument();
         if (statistic != null) {
-            Node statisticResults = xmlUtilities.createArtifactElement(doc,
+            @SuppressWarnings("static-access")
+            Node statisticResults = ArtifactXMLUtilities.createArtifactElement(doc,
                     "statistics");
             doc.appendChild(statisticResults);
             Iterator<StatisticSet> it = statistic.iterator();
             while (it.hasNext()) {
                 StatisticSet set = it.next();
-                Element setElement = xmlUtilities.createArtifactElement(doc,
+                @SuppressWarnings("static-access")
+                Element setElement = ArtifactXMLUtilities.createArtifactElement(doc,
                                                                        "statistic");
                 setElement.setAttribute("name", set.getName());
 
                 Iterator<Statistic> sit = set.getStatistics().iterator();
                 while (sit.hasNext()){
                     Statistic s = sit.next();
-                    Element result = xmlUtilities.createArtifactElement(doc,
+                    @SuppressWarnings("static-access")
+                    Element result = ArtifactXMLUtilities.createArtifactElement(doc,
                     "statistic-value");
                     result.setAttribute("name", s.getKey());
                     result.setAttribute("value", s.getStringValue());
@@ -562,6 +692,12 @@
     }
 
 
+    /**
+     * Returns the name of the selected feature.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @return the name of the selectef feature.
+     */
     protected String getSelectedFeatureName(String uuid) {
         Collection values = getCollection(featureValuesName, uuid);
 
@@ -580,14 +716,26 @@
 
 
     /**
-     * @param outputStream
-     * @param parameters
-     * @param measurements
-     * @param timeSeriesName
-     * @param chartStyle
-     * @param chartLables
-     * @throws IOException
-     * @throws TechnicalChartException
+     * Creates a chart and writes it to <i>outputStream</i>.
+     *
+     * @param outputStream The stream used to write the chart to.
+     * @param parameters A collection with parameters.
+     * @param measurements A collection with measurements.
+     * @param dates A collection with dates.
+     * @param chartLables The labels used to decorate the chart.
+     * @param context The CallContext.
+     * @param uuid The UUID of the current artifact.
+     * @param exportFormat The format the chart used to be exported as.
+     * @param locale The Locale to specify the language.
+     * @param width The width of the chart.
+     * @param height The height of the chart.
+     * @param linesVisible A boolean property to determine the visibility of
+     * lines connecting two datapoins.
+     * @param shapesVisible A boolean property to determine the visibility of
+     * datapoints.
+     * @param callContext The CallContext object.
+     * @throws IOException if an error occured while writing to output stream.
+     * @throws TechnicalChartException if an error occured while chart creation.
      */
     protected void createChart(
         OutputStream outputStream,
@@ -642,6 +790,25 @@
     }
 
 
+    /**
+     * Creates a chart and writes it as pdf to <i>outputStream</i>.
+     *
+     * @param outputStream The stream used to write the chart to.
+     * @param parameters A collection with parameters.
+     * @param measurements A collection with measurements.
+     * @param dates A collection with dates.
+     * @param chartLables The labels used to decorate the chart.
+     * @param uuid The UUID of the current artifact.
+     * @param exportFormat The format the chart used to be exported as.
+     * @param landscape A boolean property to determine the alignment of the
+     * chart.
+     * @param linesVisible A boolean property to determine the visibility of
+     * lines connecting two datapoins.
+     * @param shapesVisible A boolean property to determine the visibility of
+     * datapoints.
+     * @param locale The Locale to specify the language.
+     * @param context The CallContext object.
+     */
     protected void createPDF(
         OutputStream outputStream,
         Collection   parameters,
@@ -685,6 +852,24 @@
     }
 
 
+    /**
+     * Creates a chart and writes it as svg to <i>outputStream</i>.
+     *
+     * @param outputStream The stream used to write the chart to.
+     * @param parameters A collection with parameters.
+     * @param measurements A collection with measurements.
+     * @param dates A collection with dates.
+     * @param chartLables The labels used to decorate the chart.
+     * @param uuid The UUID of the current artifact.
+     * @param locale The Locale to specify the language.
+     * @param width The width of the chart.
+     * @param height The height of the chart.
+     * @param linesVisible A boolean property to determine the visibility of
+     * lines connecting two datapoins.
+     * @param shapesVisible A boolean property to determine the visibility of
+     * datapoints.
+     * @param callContext The CallContext object.
+     */
     protected void createSVG(
         OutputStream outputStream,
         Collection   parameters,
@@ -729,6 +914,26 @@
     }
 
 
+    /**
+     * This method creates a chart and returns it. In normal case, this is the
+     * only method to be overriden by subclasses to create other types of
+     * charts.
+     *
+     * @param chartLables Labels used to decorate the chart.
+     * @param theme The theme used to adjust the look of the chart.
+     * @param parameters A collection with parameters this chart contains.
+     * @param measurements A collection with measurement this chart contains.
+     * @param dates A collection with dates this chart contains.
+     * @param result The data collection used to be displayed in this chart.
+     * @param locale The Locale used to determine the language.
+     * @param uuid The uuid of the current artifact.
+     * @param linesVisible A boolean property to determine the visibility of
+     * lines connecting two points in a chart (not used in this chart type).
+     * @param shapesVisible A boolean property to determine the visiblity of
+     * datapoints in this chart (not used in this chart type).
+     * @param callContext The CallContext object.
+     * @return a timeseries chart.
+     */
     protected Chart getChart(
         ChartLabels  chartLables,
         ChartTheme   theme,
@@ -775,6 +980,13 @@
         return chart;
     }
 
+
+    /**
+     * Fetches the ChartTheme from <i>callContext</i> and returns it.
+     *
+     * @param callContext CallContext objects storing a chart theme.
+     * @return a chart theme.
+     */
     protected ChartTheme createStyle(CallContext callContext) {
         log.debug("Fetch chart theme from global context");
 
@@ -787,6 +999,14 @@
         return theme;
     }
 
+    /**
+     * Creates a ChartLabels object storing different labels used to decorate a
+     * chart.
+     *
+     * @param locale The Locale object to adjust the language of labels.
+     * @param uuid The UUID of the current artifact.
+     * @return the chart labels.
+     */
     protected ChartLabels createChartLabels(Locale locale, String uuid) {
         return new ChartLabels(
             createChartTitle(locale, uuid),
@@ -800,17 +1020,39 @@
     }
 
 
+    /**
+     * Creates and returns the chart title.
+     *
+     * @param locale The Locale used to adjust the language of the title.
+     * @param uuid The UUID of the current artifact.
+     * @return the name of the selected fis.
+     */
     protected String createChartTitle(Locale locale, String uuid) {
         return getFisName(locale);
 
     }
 
 
+    /**
+     * Creates and returns the subtitle of a chart.
+     *
+     * @param locale The Locale used to adjust the language of the subtitle.
+     * @param uuid The UUID of the current artifact.
+     * @return the selected feature.
+     */
     protected String createChartSubtitle(Locale locale, String uuid) {
         return getSelectedFeatureName(uuid);
     }
 
 
+    /**
+     * Creates and returns labels to decorate histograms.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @param context The CallContext object.
+     * @param data An array storing strings.
+     * @return A ChartLabels object with the 1st string in <i>data</i> as title.
+     */
     protected ChartLabels createHistogramLabels(
         String uuid, CallContext context, Object[] data)
     {
@@ -818,6 +1060,12 @@
     }
 
 
+    /**
+     * Returns the selected fis name.
+     *
+     * @param locale The Locale object used to adjust the language.
+     * @return the name of the fis.
+     */
     protected String getFisName(Locale locale) {
         String    returnValue = "";
         InputData input       = inputData.get("fisname");
@@ -835,6 +1083,14 @@
     }
 
 
+    /**
+     * Returns the name of the selected object in the collection specified by
+     * <i>key</i>.
+     *
+     * @param uuid The UUID of the current artifat.
+     * @param key A key to specify a collection.
+     * @return the name of the selected item.
+     */
     protected String getSelectedInputDataName(String uuid, String key) {
         Collection values = getCollection(key, uuid);
 
@@ -853,13 +1109,32 @@
     }
 
 
+    /**
+     * Returns a collection of selected parameters.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @return selected parameters.
+     */
     protected Collection<KeyValueDescibeData> getParameters(String uuid) {
         return this.getCollection(parameterValuesName, uuid);
     }
 
+    /**
+     * Returns a collection of selected measurements.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @return selected measurements.
+     */
     protected Collection<KeyValueDescibeData> getMeasurements(String uuid) {
         return this.getCollection(measuremenValueName, uuid);
     }
+
+    /**
+     * Returns a collection of selected dates.
+     *
+     * @param uuid The UUID of the current artifact.
+     * @return selected dates.
+     */
     protected Collection<KeyValueDescibeData> getDates(String uuid) {
         return this.getCollection(dateValueName,uuid);
     }
@@ -921,9 +1196,15 @@
         }
     }
 
+
     /**
-     * @param collectionName
-     * @return
+     * Creates a <code>NamedArrayList</code> storing some <code>
+     * KeyValueDescibeData</code> objects found in the input data with the key
+     * <i>collectionName</i>.
+     *
+     * @param collectionName String to specify the input data.
+     * @param uuid The UUID of the current artifact.
+     * @return a collection with values from input data.
      */
     protected Collection<KeyValueDescibeData> getCollection(
         String collectionName,