--- a/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactBase.java	Wed Mar 31 08:01:56 2010 +0000
+++ b/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactBase.java	Wed Mar 31 09:09:05 2010 +0000
@@ -55,6 +55,9 @@
 import org.w3c.dom.NodeList;
 
 /**
+ * This is the major gnv artifact and handles the requests specified in
+ * {@link de.intevation.artifactdatabase.Artifact}.
+ * 
  * @author <a href="mailto:tim.englich@intevation.de">Tim Englich</a>
  * @author <a href="mailto:ingo.weinzierl@intevation.de">Ingo Weinzierl</a>
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
@@ -83,18 +86,39 @@
                                                               + XPATH_IDENTIFIER_REPLACE
                                                               + "']";
 
+    /**
+     *
+     */
     public static final String XPATH_STATIC_NODE = "/art:result/art:ui/art:static";
 
+    /**
+     *
+     */
     public static final String XPATH_INPUT_DATA = "/art:action/art:data/art:input";
 
+    /**
+     *
+     */
     public static final String XPATH_INCLUDE_UI = "/art:action/art:include-ui";
 
+    /**
+     *
+     */
     public static final String XPATH_TARGET_NAME = "/art:action/art:target/@name";
 
+    /**
+     *
+     */
     public static final String XPATH_OUTPUT_NAME = "/art:action/art:out/@name";
 
+    /**
+     *
+     */
     public static final String XPATH_OUTPUT_PARAMS = "/art:action/art:out/art:params/art:input";
 
+    /**
+     *
+     */
     public static final String INITIAL_STATE = "product";
 
     /**
@@ -137,6 +161,15 @@
     }
 
 
+    /**
+     * This method handles request for changing the current state of an
+     * artifact. It is possible to step forward, backward, or to the initial
+     * state for choosing a fis.
+     * 
+     * @param target
+     * @param context
+     * @return
+     */
     @Override
     public Document advance(Document target, CallContext context) {
         log.debug("GNVArtifactBase.advance()");
@@ -268,6 +301,14 @@
     }
 
 
+    /**
+     *
+     * @param document
+     * @param nodeName
+     * @param state
+     * @param msg
+     * @return
+     */
     protected Document createReport(
         Document document,
         String   nodeName,
@@ -292,6 +333,12 @@
     }
 
 
+    /**
+     * Step back to the previous state specified by <code>name</code>.
+     * @param current
+     * @param name
+     * @return
+     */
     protected State getPreviousState(State current, String name) {
         if (current == null) {
             return null;
@@ -320,7 +367,12 @@
         return false;
     }
 
-    public Document initialize (CallContext context) {
+    /**
+     *
+     * @param context
+     * @return
+     */
+    public Document initialize(CallContext context) {
         Document result = XMLUtils.newDocument();
         try {
             this.current.initialize(super.identifier, context);
@@ -358,6 +410,11 @@
         return result;
     }
 
+    /**
+     * Step forward to the next reachable state.
+     * @param current Current state.
+     * @return Reachable state.
+     */
     protected State getNextReachableState(State current){
         Iterator<Transition> it = this.transitions.iterator();
         String from = current.getID();
@@ -372,12 +429,22 @@
         return null;
     }
 
+    /**
+     *
+     * @param document
+     * @return
+     */
     protected String readStateName(Document document) {
         String returnValue = XMLUtils.xpathString(
             document, XPATH_TARGET_NAME, ArtifactNamespaceContext.INSTANCE);
         return returnValue;
     }
 
+    /**
+     *
+     * @param document
+     * @return
+     */
     protected Node getConfigurationFragment(Document document) {
         log.debug("GNVArtifactBase.getConfigurationFragment");
         String xpathQuery = XPATH_ARTIFACT_CONFIGURATION.replaceAll(
@@ -395,6 +462,10 @@
     }
 
     /**
+     * Insert new data included in <code>target</code> into the current state.
+     * @param target XML document which contains data.
+     * @param context CallContext
+     * @return XML document with success or error message.
      * @see de.intevation.artifactdatabase.DefaultArtifact#feed(org.w3c.dom.Document,
      *      de.intevation.artifacts.CallContext)
      */
@@ -442,6 +513,10 @@
 
 
     /**
+     * Describe the current artifact.
+     * @param data
+     * @param context
+     * @return The description of the current artifact.
      * @see de.intevation.artifactdatabase.DefaultArtifact#describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)
      */
     @Override
@@ -458,6 +533,12 @@
     }
 
     /**
+     * Initialse this artifact and insert some data if <code>data</code>
+     * contains necessary information for this artifact.
+     * @param identifier 
+     * @param context
+     * @param factory
+     * @param data
      * @see de.intevation.artifactdatabase.DefaultArtifact#setup(java.lang.String, de.intevation.artifacts.ArtifactFactory, java.lang.Object, org.w3c.dom.Document)
      */
     @Override
@@ -508,6 +589,15 @@
     }
 
 
+    /**
+     * Create the xml document returned in {@link #describe(org.w3c.dom.Document,
+     * de.intevation.artifacts.CallContext)}
+     *
+     * @param context
+     * @param uuid
+     * @param incudeUI
+     * @return
+     */
     protected Document createDescibeOutput(
         CallContext context,
         String      uuid,
@@ -534,6 +624,14 @@
         return document;
     }
 
+    /**
+     * Determine the wish to append the user interface description to the
+     * describe document.
+     * 
+     * @param document
+     * @return True, if the user interface description should be appended,
+     * otherwise false.
+     */
     protected boolean getIncludeUIFromDocument(Document document){
         String value = XMLUtils.xpathString(
             document, XPATH_INCLUDE_UI, ArtifactNamespaceContext.INSTANCE);
@@ -545,6 +643,12 @@
         return includeUI;
     }
 
+    /**
+     *
+     * @param creator
+     * @param document
+     * @return
+     */
     protected Element createRootNode(
         XMLUtils.ElementCreator creator,
         Document                document
@@ -554,6 +658,14 @@
         return rootNode;
     }
 
+    /**
+     * Append information about the current artifact (uuid, hash).
+     *
+     * @param creator
+     * @param parent
+     * @param document
+     * @param documentType
+     */
     protected void createHeader(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -573,6 +685,15 @@
         parent.appendChild(hashNode);
     }
 
+    /**
+     * Create the fis select box.
+     * 
+     * @param artCreator
+     * @param creator
+     * @param document
+     * @param context
+     * @return
+     */
     protected Element createSelectBox(
         XMLUtils.ElementCreator artCreator,
         XMLUtils.ElementCreator creator,
@@ -619,6 +740,14 @@
     }
 
 
+    /**
+     * Insert all reachable states into the describe document returned by
+     * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)}
+     *
+     * @param creator
+     * @param parent
+     * @param document
+     */
     protected void createReachableStates(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -651,6 +780,15 @@
     }
 
 
+    /**
+     * Insert states which have been visited by this artifact into the xml
+     * document returned by {@link #describe(org.w3c.dom.Document,
+     * de.intevation.artifacts.CallContext)}
+     *
+     * @param creator
+     * @param parent
+     * @param state
+     */
     protected void appendOldReachableStates(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -670,6 +808,13 @@
     }
 
 
+    /**
+     * Insert the current state into the xml document returned by
+     * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)}
+     * @param creator
+     * @param parent
+     * @param document
+     */
     protected void createCurrentState(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -681,6 +826,12 @@
         parent.appendChild(stateNode);
     }
 
+    /**
+     *
+     * @param creator
+     * @param parent
+     * @param document
+     */
     protected void createModel(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -704,6 +855,15 @@
         parent.appendChild(modelNode);
     }
 
+    /**
+     * Append the user interface description to the document returned by
+     * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)}
+     * @param creator XML element creator.
+     * @param parent New elements are appended to this node.
+     * @param document Current document.
+     * @param context CallContext
+     * @param uuid The uuid of the artifact.
+     */
     protected void createUserInterface(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -742,6 +902,13 @@
     }
 
 
+    /**
+     * Append possible output targets to the document returned by
+     * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)}
+     * @param creator Used to create xml elements.
+     * @param parent New elements are appended to this node.
+     * @param document The current document.
+     */
     protected void createOutputs(
         XMLUtils.ElementCreator creator,
         Element                 parent,
@@ -812,6 +979,12 @@
         parent.appendChild(outputsNode);
     }
 
+    /**
+     * Parse input data from feed-document.
+     * @param document Feed-document
+     * @param xPath Path to input data.
+     * @return A collection with InputData objects.
+     */
     protected Collection<InputData> parseInputData(Document document,
                                                    String xPath) {
         HashMap<String, InputData> returnValue = null;
@@ -842,6 +1015,13 @@
     }
 
     /**
+     * Call an output target (e.g. chart, wms, etc.)
+     * @param format XML document which contains some further information about
+     * the desired output.
+     * @param outputStream Stream used for writing the output.
+     * @param context CallContext
+     * @throws IOException If an error occured while writing the result to the
+     * output stream.
      * @see de.intevation.artifactdatabase.DefaultArtifact#out(org.w3c.dom.Document,
      *      java.io.OutputStream, de.intevation.artifacts.CallContext)
      */
@@ -863,6 +1043,11 @@
         }
     }
 
+    /**
+     *
+     * @param document
+     * @return
+     */
     protected static String readOutputType(Document document) {
         String value = XMLUtils.xpathString(
             document, XPATH_OUTPUT_NAME, ArtifactNamespaceContext.INSTANCE);
@@ -870,10 +1055,19 @@
     }
 
 
+    /**
+     * The the current product.
+     * @param product New product.
+     */
     public void setProduct(Product product) {
         this.product = product;
     }
 
+    /**
+     * Call endOfLife of parent class and the current state.
+     * @param globalContext
+     */
+    @Override
     public void endOfLife(Object globalContext) {
         super.endOfLife(globalContext);
 
@@ -883,6 +1077,9 @@
     }
 
     /**
+     * Retrieves a map with given InputData which have been inserted into the
+     * current artifact before the parameterization began.
+     * @return
      * @see de.intevation.gnv.artifacts.PreSettingArtifact#getPreSettings()
      */
     public Map<String, InputData> getPreSettings() {
@@ -890,6 +1087,8 @@
     }
 
     /**
+     * Set InputData which are used in later states.
+     * @param preSettings
      * @see de.intevation.gnv.artifacts.PreSettingArtifact#setPreSettings(java.util.Map)
      */
     public void setPreSettings(Map<String, InputData> preSettings) {
@@ -899,4 +1098,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 :