--- a/gnv-artifacts/src/main/java/de/intevation/gnv/state/OutputStateBase.java	Wed Mar 31 13:48:07 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/state/OutputStateBase.java	Thu Apr 01 09:15:36 2010 +0000
@@ -44,6 +44,10 @@
 import org.w3c.dom.NodeList;
 
 /**
+ * This is the default implementation of <code>OutputState</code>. Artifacts
+ * having reached this state or a subclass of this state are able to produce
+ * some output (e.g. chart, histograms, statistic, etc).
+ *
  * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
  * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  *
@@ -52,15 +56,27 @@
 extends               StateBase
 implements            OutputState
 {
+    /**
+     *
+     */
     public static final String XPATH_OUTPUT_MODE =
         "/art:action/art:out/@name";
 
+    /**
+     *
+     */
     public static final String XPATH_EXPORT_MODE =
         "/art:action/art:out/art:export/@name";
 
+    /**
+     *
+     */
     public static final String XPATH_MIME_TYPE   =
         "/art:action/art:out/art:mime-type/@value";
 
+    /**
+     *
+     */
     public static final String XPATH_EXPORTS =
         "exportModes/export";
 
@@ -79,6 +95,9 @@
      */
     protected Collection<OutputMode> outputModes = null;
 
+    /**
+     *
+     */
     protected String queryODVID = null;
 
     /**
@@ -89,7 +108,8 @@
     }
 
     /**
-     * @see de.intevation.gnv.state.OutputState#getOutputModes()
+     * 
+     * @return
      */
     public Collection<OutputMode> getOutputModes() {
         log.debug("OutputStateBase.getOutputModes");
@@ -97,7 +117,7 @@
     }
 
     /**
-     * @see de.intevation.gnv.state.StateBase#setup(org.w3c.dom.Node)
+     * @param configuration
      */
     @Override
     public void setup(Node configuration) {
@@ -166,7 +186,9 @@
     }
 
     /**
-     * @see de.intevation.gnv.state.StateBase#advance()
+     * @param uuid 
+     * @param context
+     * @throws StateException
      */
     @Override
     public void advance(String uuid, CallContext context)
@@ -174,12 +196,29 @@
     {
     }
 
+    /**
+     *
+     * @param uuid
+     * @param context
+     * @throws StateException
+     */
     @Override
     public void initialize(String uuid, CallContext context)
     throws StateException
     {
     }
 
+    /**
+     * This method needs to be defined by concrete subclasses. Nothing is done
+     * here.
+     *
+     * @param format
+     * @param inputData
+     * @param outputStream
+     * @param uuid
+     * @param callMeta
+     * @throws StateException
+     */
     public void out(
         Document              format,
         Collection<InputData> inputData,
@@ -192,6 +231,13 @@
     }
 
     /**
+     * This method needs to be defined by concrete subclasses. Nothing is done
+     * here.
+     * 
+     * @param outputMode
+     * @param inputData
+     * @param outputStream 
+     * @throws StateException
      * @see de.intevation.gnv.state.OutputState#out(java.lang.String,
      *      java.util.Collection, java.io.OutputStream)
      */
@@ -200,7 +246,15 @@
     }
 
     /**
-     * @return
+     * Returns the data used to create charts. If a cache is configured, try to
+     * fetch the data from cache. The database is queried if the data is not in
+     * cache yet, or if no cache is configured. If the cache is configured, but
+     * the data is not in cache yet, put it into cache for a faster access
+     * in a later time.
+     * 
+     * @param uuid The uuid of an artifact.
+     * @param callContext The CallContext.
+     * @return the chart data.
      */
     protected Object getChartResult(String uuid, CallContext callContext) {
         log.debug("OutputStateBase.getChartResult");
@@ -233,6 +287,16 @@
         }
     }
 
+    /**
+     * This method should no longer be used, because it is not good to put a
+     * chart into cache. Parameter changes done by the user wouldn't be detected
+     * proper.
+     *
+     * @param uuid
+     * @param callContext
+     * @return
+     * @deprecated 
+     */
     protected Object getChartFromCache(String uuid, CallContext callContext) {
         log.debug("Fetch chart [" + uuid + "] from cache");
         CacheFactory cacheFactory = CacheFactory.getInstance();
@@ -247,6 +311,12 @@
         return null;
     }
 
+    /**
+     * Retrieves the data used to create an ODV export.
+     *
+     * @param uuid
+     * @return odv data.
+     */
     protected Collection<Result> getODVResult(String uuid) {
         log.debug("OutputStateBase.getODVResult");
         // TODO add Caching? I think it's not nessessary
@@ -260,8 +330,10 @@
     }
 
     /**
-     * @param returnValue
-     * @return
+     * Retrieve data from database with help of queryID.
+     *
+     * @param queryID A query id defined in sql statements properties file.
+     * @return some data.
      */
     protected Collection<Result> getData(String queryID) {
         log.debug("OutputStateBase.getData");
@@ -282,6 +354,11 @@
         return returnValue;
     }
 
+    /**
+     * This method removes the data used for creating charts from cache.
+     *
+     * @param uuid
+     */
     protected void removeChartResult(String uuid) {
         log.debug("OutputStateBase.getChartResult");
         if (CacheFactory.getInstance().isInitialized()) {
@@ -294,6 +371,12 @@
         }
     }
 
+    /**
+     * This method should no longer be used. It removes a chart from cache.
+     *
+     * @param uuid
+     * @deprecated 
+     */
     protected void removeChart(String uuid) {
         log.debug("OutputStateBase.removeChart from cache");
 
@@ -306,6 +389,12 @@
         }
     }
 
+    /**
+     * This is an internal method used while database query.
+     *
+     * @param chart
+     * @param uuid
+     */
     protected void purifyChart(Object chart, String uuid) {
         log.debug("Prufify chart [" + uuid + "]");
         CacheFactory cacheFactory = CacheFactory.getInstance();
@@ -316,6 +405,15 @@
     }
 
 
+    /**
+     * Use this method to feed a state with new data.
+     *
+     * @param context
+     * @param inputData
+     * @param uuid
+     * @return
+     * @throws StateException
+     */
     @Override
     public Document feed(
         CallContext           context,
@@ -329,9 +427,17 @@
     }
 
     /**
-     * @see de.intevation.gnv.state.StateBase#putInputData(java.util.Collection, java.lang.String)
+     * This method is used to put new data into a next state. The difference
+     * between this method and feed is, that this method should be used to
+     * transfer some old input data required by this state. New data need to be
+     * inserted via feed!
+     *
+     * @param inputData
+     * @param uuid
+     * @throws StateException
      */
     @Override
+    @SuppressWarnings({"static-access", "static-access", "static-access", "static-access"})
     public void putInputData(Collection<InputData> inputData,
                              String uuid)
                                          throws StateException {
@@ -352,13 +458,14 @@
                                 inputData.size());
                     }
 
-                    boolean valid = iv.isInputValid(tmpItem.getValue(),
+                    @SuppressWarnings("static-access")
+                    boolean valid = InputValidator.isInputValid(tmpItem.getValue(),
                             inputValue.getType());
                     if (valid) {
                         if (tmpItem.getName().equals(MINVALUEFIELDNAME)){
                             String minValue = tmpItem.getValue();
                             String maxValue = getInputValue4ID(inputData, MAXVALUEFIELDNAME);
-                            valid = iv.isInputValid(maxValue,inputValue.getType());
+                            valid = InputValidator.isInputValid(maxValue,inputValue.getType());
                             if (!valid){
                                 String errMsg = "Wrong input for " + tmpItem.getValue()
                                                 + " is not an " + inputValue.getType()
@@ -367,7 +474,7 @@
                                 throw new StateException(errMsg);
                             }
 
-                            valid = iv.isInputValid(minValue,
+                            valid = InputValidator.isInputValid(minValue,
                                     maxValue,
                                     inputValue.getType());
                             if (!valid){
@@ -378,7 +485,7 @@
                         }else if (tmpItem.getName().equals(MAXVALUEFIELDNAME)){
                             String minValue = getInputValue4ID(inputData, MINVALUEFIELDNAME);
                             String maxValue = tmpItem.getValue();
-                            valid = iv.isInputValid(minValue,inputValue.getType());
+                            valid = InputValidator.isInputValid(minValue,inputValue.getType());
                             if (!valid){
                                 String errMsg = "Wrong input for " + tmpItem.getValue()
                                                 + " is not an " + inputValue.getType()
@@ -387,7 +494,7 @@
                                 throw new StateException(errMsg);
                             }
 
-                            valid = iv.isInputValid(minValue,
+                            valid = InputValidator.isInputValid(minValue,
                                                     maxValue,
                                                     inputValue.getType());
                             if (!valid){
@@ -428,12 +535,32 @@
         }
     }
 
-    public void out(String outputMode, Collection<InputData> inputData,
-                    OutputStream outputStream, String uuid, CallMeta callMeta)
-                                                                              throws StateException {
-    }
+    /**
+     *
+     * @param outputMode
+     * @param inputData
+     * @param outputStream
+     * @param uuid
+     * @param callMeta
+     * @throws StateException
+     */
+    public void out(
+        String                outputMode,
+        Collection<InputData> inputData,
+        OutputStream          outputStream,
+        String                uuid,
+        CallMeta              callMeta)
+    throws StateException { }
 
 
+    /**
+     * Retrieves a message from resource bundle specified by locale.
+     *
+     * @param locale Locale to use.
+     * @param key The key of the message.
+     * @param value The default value.
+     * @return The value.
+     */
     protected String getMessage(Locale locale, String key, String value) {
         return RessourceFactory.getInstance().getRessource(
             locale,
@@ -442,4 +569,4 @@
         );
     }
 }
-// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8:
+// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 :