dive4elements/gnv-client: gnv-artifacts/src/main/java/de/intevation/gnv/state/timeseries/TimeSeriesOutputState.java comparison

comparison gnv-artifacts/src/main/java/de/intevation/gnv/state/timeseries/TimeSeriesOutputState.java @ 804:9058c08eac3a

Added more Javadoc in some classes of state.profile. gnv-artifacts/trunk@886 c6561f87-3c4e-4783-a992-168aeb5c3f6f

author	Ingo Weinzierl <ingo.weinzierl@intevation.de>
date	Thu, 08 Apr 2010 10:10:04 +0000
parents	5dd94448538d
children	bb7afd783321

comparison

equal deleted inserted replaced

-:feae2f9d6c6f
+:9058c08eac3a
 * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
 * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
 */
 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"
 };
 /**
 private static Logger log = Logger
 .getLogger(TimeSeriesOutputState.class);
 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";
 protected String parameterValuesName = "parameterid";
 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",
 "GROUP1",
 "GROUP2",
 "GROUP3"
 };
+/**
+* Column labels used in csv exports.
+*/
 public static final String [] TIMESERIES_TIMESERIES_CSV_COLUMN_LABEL = {
 "Date/Time",
 "Value",
 "ParameterID",
 "MeasurementID",
 "TimeseriesID"
 };
+/**
+* Array used to specify the column in csv exports on meshes.
+*/
 public static final String [] TIMESERIES_MESH_CSV_COLUMN_LABEL = {
 "Date/Time",
 "Value",
 "ParameterID",
 "FeatureID",
 "MeshID"
 };
+/**
+* Array used to specify the columns in odv exports.
+*/
 public static final String [] TIMESERIES_ODV_PROFILE_NAMES = {
 "CRUISE",
 "STATION",
 "TYPE",
 "TIMEVALUE",
 "DEPTH",
 "QF"
 };
+/**
+* Column labels used in odv exports.
+*/
 public static final String [] ODV_COLUMN_HEADER = {
 "Cruise",
 "Station",
 "Type",
 "yyyy-mm-dd hh:mm",
 "Bot. Depth [m]",
 "Depth [m]",
 "QF"
 };
 /**
 * Profile for exporting data to odv
 */
 public static final Profile TIMESERIES_ODV_PROFILE =
 new DefaultProfile(
 public TimeSeriesOutputState() {
 super();
 }
+/**
+* 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
 {
 getChartResult(uuid, context);
 }
 /**
-* @see de.intevation.gnv.transition.OutputTransition#out(java.lang.String,
+* This out target has following modes:<br>
-*      java.util.Collection, java.io.OutputStream, java.lang.String,
+* <ol>
-*      de.intevation.artifacts.CallMeta)
+*  <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,
 Collection<InputData> inputData,
 OutputStream          outputStream,
 throw new StateException(e);
 }
 }
+/**
+* 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)
 return IMG_EXPORT_FORMAT[i];
 }
 // no format found relating to mimeType, default export as PNG
 return IMG_EXPORT_FORMAT[0];
 }
+/**
+* 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);
 while (iter.hasNext()) {
 KeyValueDescibeData data = (KeyValueDescibeData)iter.next();
 return parameter;
 }
+/**
+* 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
 {
 Iterator iter = results.iterator();
 Result   res  = iter.hasNext() ? (Result) iter.next() : null;
 export.create(profile, out, results);
 }
 /**
-* 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,
 String uuid)
 throws IOException, StateException {
 log.error("#################### RESULT == NULL #################");
 export.create(TIMESERIES_ODV_PROFILE, outputStream, result);
 }
 /**
-* @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());
 setElement.appendChild(result);
 }
 }
 return doc;
 }
+/**
+* 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);
 if (values != null) {
 Iterator it = values.iterator();
 return "";
 }
 /**
-* @param outputStream
+* Creates a chart and writes it to <i>outputStream</i>.
-* @param parameters
+*
-* @param measurements
+* @param outputStream The stream used to write the chart to.
-* @param timeSeriesName
+* @param parameters A collection with parameters.
-* @param chartStyle
+* @param measurements A collection with measurements.
-* @param chartLables
+* @param dates A collection with dates.
-* @throws IOException
+* @param chartLables The labels used to decorate the chart.
-* @throws TechnicalChartException
+* @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,
 Collection   parameters,
 Collection   measurements,
 height
 );
 }
+/**
+* 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,
 Collection   measurements,
 Collection   dates,
 50F, 50F, 50F, 50F
 );
 }
+/**
+* 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,
 Collection   measurements,
 Collection   dates,
 log.debug("svg export finished.");
 }
+/**
+* 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,
 Collection   parameters,
 Collection   measurements,
 }
 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");
 GNVArtifactContext context =
 (GNVArtifactContext) callContext.globalContext();
 GNVArtifactContext.CHART_TEMPLATE_KEY);
 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),
 createChartSubtitle(locale, uuid),
 RessourceFactory.getInstance().getRessource(
 )
 );
 }
+/**
+* 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)
 {
 return new ChartLabels((String) data[0], "", "");
 }
+/**
+* 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");
 if (input != null) {
 }
 return returnValue;
 }
+/**
+* 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);
 if (values != null) {
 Iterator it = values.iterator();
 }
 return null;
 }
+/**
+* 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);
 }
 @Override
 }
 }
 }
 }
-/**
-* @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,
 String uuid)
 {

Mercurial > dive4elements > gnv-client

comparison gnv-artifacts/src/main/java/de/intevation/gnv/state/timeseries/TimeSeriesOutputState.java @ 804:9058c08eac3a