# HG changeset patch
# User Sascha L. Teichmann <sascha.teichmann@intevation.de>
# Date 1269785765 0
# Node ID 73d0ebae81d7d954735dc90998f3f95f5d5c621f
# Parent  730ff077a58c36a1d1935731d1d6dcf1278a61ff
Last bunch of javadoc


artifacts/trunk@848 c6561f87-3c4e-4783-a992-168aeb5c3f6f

diff -r 730ff077a58c -r 73d0ebae81d7 ChangeLog
--- a/ChangeLog	Sun Mar 28 10:01:03 2010 +0000
+++ b/ChangeLog	Sun Mar 28 14:16:05 2010 +0000
@@ -1,16 +1,24 @@
 2010-03-28	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
 
-    * artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/Config.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java,
-      artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java:
-      More javadoc, some code formatting.
+	* artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java,
+	  TODO:
+	  Last bunch of javadoc. Possible TODO: check for typos and cross reference problems
+	  but the main work should be done with this commit.
+
+2010-03-28	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
+
+	* artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactContextFactory.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifact.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DBConnection.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/Config.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultCallMeta.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DefaultArtifactFactory.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/rest/FactoriesResource.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/rest/CreateResource.java,
+	  artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java:
+	  More javadoc, some code formatting.
 
 2010-03-26	Sascha L. Teichmann	<sascha.teichmann@intevation.de>
 
diff -r 730ff077a58c -r 73d0ebae81d7 TODO
--- a/TODO	Sun Mar 28 10:01:03 2010 +0000
+++ b/TODO	Sun Mar 28 14:16:05 2010 +0000
@@ -1,3 +1,2 @@
 TODO:
 	* Document the XML of the configuration file.
-    * Adjust JavaDoc.
diff -r 730ff077a58c -r 73d0ebae81d7 artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java	Sun Mar 28 10:01:03 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/ArtifactDatabaseImpl.java	Sun Mar 28 14:16:05 2010 +0000
@@ -34,6 +34,10 @@
 import org.w3c.dom.Element;
 
 /**
+ * The core implementation of artifact database. This layer exposes
+ * the needed methods to the artifact runtime system which e.g. may
+ * expose them via REST. The concrete persistent representation of the
+ * artifacts is handled by the {@link Backend backend}.
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class ArtifactDatabaseImpl
@@ -42,59 +46,144 @@
     private static Logger logger =
         Logger.getLogger(ArtifactDatabaseImpl.class);
 
+    /**
+     * Error message issued if a requested artifact factory
+     * is not registered to this database.
+     */
     public static final String NO_SUCH_FACTORY =
         "No such factory";
 
+    /**
+     * Error message issued if a requested artifact is not found
+     * in this database.
+     */
     public static final String NO_SUCH_ARTIFACT =
         "No such artifact";
 
+    /**
+     * Error message issued if one tries to remove a requested artifact
+     * from the list of artifacts running in background which is
+     * not in this list.
+     */
     public static final String NOT_IN_BACKGROUND =
         "Not in background";
 
+    /**
+     * Error message issued if an artifact wants to translate itself
+     * into a none valid persistent state.
+     */
     public static final String INVALID_CALL_STATE =
         "Invalid after call state";
 
+    /**
+     * Error message issued if the creation of an artifact failed.
+     */
     public static final String CREATION_FAILED =
         "Creation of artifact failed";
 
+    /**
+     * Error message if an severe internal error occurred.
+     */
     public static final String INTERNAL_ERROR =
         "Creation of artifact failed";
 
+    /**
+     * Error message issued if a requested service is not
+     * offered by this database.
+     */
     public static final String NO_SUCH_SERVICE =
         "No such service";
 
+    /**
+     * Default digest hash to be used while im-/exporting artifacts.
+     */
     public static final String DIGEST_ALGORITHM =
         "SHA-1";
 
+    /**
+     * XPath to get the checksum from an XML representation of
+     * an exported artifact.
+     */
     public static final String XPATH_IMPORT_CHECKSUM =
         "/art:action/art:data/@checksum";
 
+    /**
+     * XPath to get the name of the factory which should be
+     * used to revive an antrifact that is going to be imported.
+     */
     public static final String XPATH_IMPORT_FACTORY =
         "/art:action/art:data/@factory";
 
+    /**
+     * XPath to get the base64 encoded data of an artifact
+     * that is going to be imported.
+     */
     public static final String XPATH_IMPORT_DATA =
         "/art:action/art:data/text()";
 
+    /**
+     * Error message issued if the checksum of an
+     * artifact to be imported has an invalid syntax.
+     */
     public static final String INVALID_CHECKSUM =
         "Invalid checksum";
 
+    /**
+     * Error message issued the checksum validation
+     * of an artifact to be imported fails.
+     */
     public static final String CHECKSUM_MISMATCH =
         "Mismatching checksum";
 
+    /**
+     * Error message issued if an artifact to be imported
+     * does not have any data.
+     */
     public static final String NO_DATA =
         "No data";
 
+    /**
+     * Error message issued if the deserialization of
+     * an artifact to be imported fails.
+     */
     public static final String INVALID_ARTIFACT =
         "Invalid artifact";
 
+    /**
+     * Inner class that implements the call context handed
+     * to the methods calls describe(), feed(), etc. of the artifact.
+     */
     public class CallContextImpl
     implements   CallContext
     {
+        /**
+         * The persistence wrapper around the living artifact
+         */
         protected PersistentArtifact artifact;
+        /**
+         * The action to be performed after the artifact calls
+         * desribe(), feed(), etc. return.
+         */
         protected int                action;
+        /**
+         * The meta information of the concrete call
+         * (preferred languages et. al.)
+         */
         protected CallMeta           callMeta;
+        /**
+         * Map to act like a clipboard when nesting calls
+         * like a proxy artifact.
+         */
         protected HashMap            customValues;
 
+        /**
+         * Constructor to create a call context with a given
+         * persistent artifact, a default action and meta informations.
+         * @param artifact The persistent wrapper around a living artifact.
+         * @param action   The action to be performed after the concrete
+         * artifact call has returned.
+         * @param callMeta The meta information for this call context.
+         */
         public CallContextImpl(
             PersistentArtifact artifact,
             int                action,
@@ -135,6 +224,10 @@
             return artifact.getTTL();
         }
 
+        /**
+         * Dispatches and executes the persistence action after
+         * the return of the concrete artifact call.
+         */
         public void postCall() {
             switch (action) {
                 case NOTHING:
@@ -169,16 +262,40 @@
         }
     } // class CallContextImpl
 
+    /**
+     * This inner class allows the deferral of writing the output
+     * of the artifact's out() call.
+     */
     public class DeferredOutputImpl
     implements   DeferredOutput
     {
+        /**
+         * The persistence wrapper around a living artifact.
+         */
         protected PersistentArtifact artifact;
+        /**
+         * The input document for the artifact's out() call.
+         */
         protected Document           format;
+        /**
+         * The meta information of the artifact's out() call.
+         */
         protected CallMeta           callMeta;
 
+        /**
+         * Default constructor.
+         */
         public DeferredOutputImpl() {
         }
 
+        /**
+         * Constructor to create a deferred execution unit for
+         * the artifact's out() call given an artifact, an input document
+         * an the meta information.
+         * @param artifact The persistence wrapper around a living artifact.
+         * @param format   The input document for the artifact's out() call.
+         * @param callMeta The meta information of the artifact's out() call.
+         */
         public DeferredOutputImpl(
             PersistentArtifact artifact,
             Document           format,
@@ -203,26 +320,70 @@
         }
     } // class DeferredOutputImpl
 
+    /**
+     * List of name/description pairs needed for
+     * {@link #artifactFactoryNamesAndDescriptions() }.
+     */
     protected String [][] factoryNamesAndDescription;
+    /**
+     * Map to access artifact factories by there name.
+     */
     protected HashMap     name2factory;
 
+    /**
+     * List of name/description pairs needed for
+     * {@link #serviceNamesAndDescriptions() }.
+     */
     protected String [][] serviceNamesAndDescription;
+    /**
+     * Map to access services by there name.
+     */
     protected HashMap     name2service;
 
+    /**
+     * Reference to the storage backend.
+     */
     protected Backend     backend;
+    /**
+     * Reference of the global context of the artifact runtime system.
+     */
     protected Object      context;
 
+    /**
+     * The signing secret to be used for ex-/importing artifacts.
+     */
     protected byte []     exportSecret;
 
+    /**
+     * A set of ids of artifact which currently running in background.
+     * This artifacts should not be removed from the database by the
+     * database cleaner.
+     */
     protected HashSet     backgroundIds;
 
+    /**
+     * Default constructor.
+     */
     public ArtifactDatabaseImpl() {
     }
 
+    /**
+     * Constructor to create a artifact database with the given
+     * bootstrap parameters like artifact- and service factories et. al.
+     * Created this way the artifact database has no backend.
+     * @param bootstrap The parameters to start this artifact database.
+     */
     public ArtifactDatabaseImpl(FactoryBootstrap bootstrap) {
         this(bootstrap, null);
     }
 
+    /**
+     * Constructor to create a artifact database with the a given
+     * backend and
+     * bootstrap parameters like artifact- and service factories et. al.
+     * @param bootstrap The parameters to start this artifact database.
+     * @param backend   The storage backend.
+     */
     public ArtifactDatabaseImpl(FactoryBootstrap bootstrap, Backend backend) {
 
         backgroundIds = new HashSet();
@@ -236,6 +397,11 @@
         wireWithBackend(backend);
     }
 
+    /**
+     * Used to extract the artifact factories from the bootstrap
+     * parameters and building the internal lookup tables.
+     * @param bootstrap The bootstrap parameters.
+     */
     protected void setupArtifactFactories(FactoryBootstrap bootstrap) {
         name2factory  = new HashMap();
 
@@ -256,6 +422,12 @@
         }
     }
 
+    /**
+     * Used to extract the service factories from the bootstrap
+     * parameters, setting up the services and building the internal
+     * lookup tables.
+     * @param bootstrap The bootstrap parameters.
+     */
     protected void setupServices(FactoryBootstrap bootstrap) {
 
         name2service  = new HashMap();
@@ -282,6 +454,12 @@
 
     }
 
+    /**
+     * Wires a storage backend to this artifact database and
+     * establishes a callback to be able to revive artifacts
+     * via the serializers of this artifact factories.
+     * @param backend The backend to be wired with this artifact database.
+     */
     public void wireWithBackend(Backend backend) {
         if (backend != null) {
             this.backend = backend;
@@ -289,6 +467,13 @@
         }
     }
 
+    /**
+     * Called after an backgrounded artifact signals its
+     * will to be written back to the backend.
+     * @param artifact The persistence wrapper around
+     * the backgrounded artifact.
+     * @param action The action to be performed.
+     */
     protected void fromBackground(PersistentArtifact artifact, int action) {
         logger.warn("BACKGROUND processing is not fully implemented, yet!");
         switch (action) {
@@ -306,12 +491,25 @@
         removeIdFromBackground(artifact.getId());
     }
 
+    /**
+     * Removes an artifact's database id from the set of backgrounded
+     * artifacts. The database cleaner is now able to remove it safely
+     * from the database again.
+     * @param id The database id of the artifact.
+     */
     protected void removeIdFromBackground(int id) {
         synchronized (backgroundIds) {
             backgroundIds.remove(Integer.valueOf(id));
         }
     }
 
+    /**
+     * Adds an artifact's database id to the set of artifacts
+     * running in backgroound. To be in this set prevents the
+     * artifact to be removed from the database by the database cleaner.
+     * @param id The database id of the artifact to be protected
+     * from being removed from the database.
+     */
     protected void addIdToBackground(int id) {
         synchronized (backgroundIds) {
             backgroundIds.add(Integer.valueOf(id));
@@ -324,6 +522,7 @@
         synchronized (backgroundIds) {
             for (int i = 0; i < N; ++i) {
                 Id id = (Id)ids.get(i);
+                // only delete artifact if its not in background.
                 if (!backgroundIds.contains(Integer.valueOf(id.getId()))) {
                     out.add(id);
                 }
@@ -501,6 +700,15 @@
             exportSecret);
     }
 
+    /**
+     * Creates an exteral XML representation of an artifact.
+     * @param factoryName The name of the factory which is responsible
+     * for the serialized artifact.
+     * @param artifact The byte data of the artifact itself.
+     * @param secret   The signing secret.
+     * @return An XML document containing the external representation
+     * of the artifact.
+     */
     protected static Document createExportDocument(
         String  factoryName,
         byte [] artifact,
diff -r 730ff077a58c -r 73d0ebae81d7 artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java
--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java	Sun Mar 28 10:01:03 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/XMLUtils.java	Sun Mar 28 14:16:05 2010 +0000
@@ -216,7 +216,7 @@
     }
 
     /**
-     * Evaluates an XPath query on a given objectr and returns the result
+     * Evaluates an XPath query on a given object and returns the result
      * as a string. A given namespace context is used.
      * @param root  The object which is used as the root of the tree to
      * be searched in.