--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java	Fri Mar 26 11:40:28 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/rest/ArtifactResource.java	Fri Mar 26 15:05:11 2010 +0000
@@ -26,6 +26,13 @@
 import de.intevation.artifactdatabase.XMLUtils;
 
 /**
+ * Resource to expose the core artifact methods
+ * (describe, feed and advance) via REST.
+ *
+ * <ul>
+ * <li>describe() is modelled via GET.</li>
+ * <li>advance() and feed() are modelled via POST.</li>
+ * </ul>
  * @author <a href="mailto:sascha.teichmann@intevation">Sascha L. Teichmann</a>
  */
 public class ArtifactResource
@@ -33,19 +40,47 @@
 {
     private static Logger logger = Logger.getLogger(ArtifactResource.class);
 
+    /**
+     * XPath to figure out the type of action (feed, advance) via the
+     * incoming POST request.
+     */
     public static final String XPATH_ACTION = "/art:action/art:type/@name";
 
+    /**
+     * server URL where to reach the resource.
+     */
     public static final String PATH = "/artifact/{uuid}";
 
+    /**
+     * Error message if no action was given.
+     */
     public static final String NO_ACTION_MESSAGE      = "no action given";
+
+    /**
+     * Error message if a unknown action was given.
+     */
     public static final String NO_SUCH_ACTION_MESSAGE = "no such action";
 
+    /**
+     * Error message if the requested artifact was not found in
+     * the artifact database.
+     */
     public static final String NO_ARTIFACT_FOUND = "Artifact not found";
 
+    /**
+     * Action name 'advance'.
+     */
     public static final String ADVANCE  = "advance";
+    /**
+     * Action name 'feed'.
+     */
     public static final String FEED     = "feed";
+    /**
+     * Action name 'describe'.
+     */
     public static final String DESCRIBE = "describe";
 
+    @Override
     protected Representation innerGet()
     throws                   ResourceException
     {
@@ -74,6 +109,17 @@
         }
     }
 
+    /**
+     * Method to figure out which POST action (feed or advance) was
+     * triggered and perform this operation on the artifact specified
+     * by 'identifier' and found in the artifact database 'db'
+     * @param identifier The identifier of the artifact.
+     * @param action The action to be performed.
+     * @param source The input document to further parameterize the
+     * operation.
+     * @param db The artifact database where to find the artifact.
+     * @return
+     */
     protected Representation dispatch(
         String           identifier,
         String           action,
@@ -107,6 +153,7 @@
         return new DomRepresentation(MediaType.APPLICATION_XML, out);
     }
 
+    @Override
     protected Representation innerPost(Representation requestRepr) {
 
         Document inputDocument = null;
@@ -144,4 +191,4 @@
         return dispatch(identifier, action, inputDocument, db);
     }
 }
-// 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 :