--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java	Fri Mar 26 16:16:32 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/DatabaseCleaner.java	Fri Mar 26 17:59:50 2010 +0000
@@ -15,46 +15,111 @@
 import java.util.List;
 
 /**
+ * The database cleaner runs in background. It sleep for a configurable
+ * while and when it wakes up it removes outdated artifacts from the
+ * database. Outdated means that the the last access to the artifact
+ * is longer aga then the time to live of this artifact.<br>
+ * Before the artifact is finally removed from the system it is
+ * revived one last time an the #endOfLife() method of the artifact
+ * is called.<br>
+ * The artifact implementations may e.g. use this to remove some extrenal
+ * resources form the system.
+ *
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class DatabaseCleaner
 extends      Thread
 {
+    /**
+     * Implementors of this interface are able to create a
+     * living artifact from a given byte array.
+     */
     public interface ArtifactReviver {
 
+        /**
+         * Called to revive an artifact from a given byte array.
+         * @param factoryName The name of the factory which
+         * created this artifact.
+         * @param bytes The bytes of the serialized artifact.
+         * @return The revived artfiact.
+         */
         Artifact reviveArtifact(String factoryName, byte [] bytes);
 
     } // interface ArtifactReviver
 
     private static Logger logger = Logger.getLogger(DatabaseCleaner.class);
 
+    /**
+     * Number of artifacts to be loaded at once. Used to
+     * mitigate the problem of a massive denial of service
+     * if too many artifacts have died since last cleanup.
+     */
     public static final int MAX_ROWS = 50;
 
+    /**
+     * The SQL statement to select the outdated artifacts.
+     */
     public static final String SQL_OUTDATED =
         SQL.get("artifacts.outdated");
 
+    /**
+     * The SQL statement to delete some artifacts from the database.
+     */
     public static final String SQL_DELETE =
         SQL.get("artifacts.delete");
 
+    /**
+     * XPath to figure out how long the cleaner should sleep between
+     * cleanups. This is stored in the global configuration.
+     */
     public static final String SLEEP_XPATH =
         "/artifact-database/cleaner/sleep-time/text()";
 
+    /**
+     * Default nap time between cleanups: 5 minutes.
+     */
     public static final long SLEEP_DEFAULT =
         5 * 60 * 1000L; // 5 minutes
 
+    /**
+     * The configured nap time.
+     */
     protected long sleepTime;
 
+    /**
+     * Internal locking mechanism to prevent some race conditions.
+     */
     protected Object sleepLock = new Object();
 
+    /**
+     * A reference to the global context.
+     */
     protected Object context;
 
+    /**
+     * A specialized Id filter which only delete some artifacts.
+     * This is used to prevent deletion of living artifacts.
+     */
     protected Id.Filter filter;
 
+    /**
+     * The reviver used to bring the dead artifact on last
+     * time back to live to call endOfLife() on them.
+     */
     protected ArtifactReviver reviver;
 
+    /**
+     * Default constructor.
+     */
     public DatabaseCleaner() {
     }
 
+    /**
+     * Constructor to create a cleaner with a given global context
+     * and an given reviver.
+     * @param context The global context of the artifact database
+     * @param reviver The reviver to awake artifact one last time.
+     */
     public DatabaseCleaner(Object context, ArtifactReviver reviver) {
         setDaemon(true);
         sleepTime = getSleepTime();
@@ -62,16 +127,32 @@
         this.reviver = reviver;
     }
 
+    /**
+     * Sets the filter that prevents deletion of living artifacts.
+     * Living artifacts are artifacts which are currently active
+     * inside the artifact database. Deleting them in this state
+     * would create severe internal problems.
+     * @param filter
+     */
     public void setFilter(Id.Filter filter) {
         this.filter = filter;
     }
 
+    /**
+     * External hook to tell the cleaner to wake up before its
+     * regular nap time is over. This is the case when the artifact
+     * database finds an artifact which is already outdated.
+     */
     public void wakeup() {
         synchronized (sleepLock) {
             sleepLock.notify();
         }
     }
 
+    /**
+     * Fetches the sleep time from the global configuration.
+     * @return the time to sleep between database cleanups in ms.
+     */
     protected static long getSleepTime() {
         String sleepTimeString = Config.getStringXPath(SLEEP_XPATH);
 
@@ -202,6 +283,11 @@
         logger.info("artifacts removed: " + removedArtifacts);
     }
 
+    /**
+     * The main code of the cleaner. It sleeps for the configured
+     * nap time, cleans up the database, sleeps again and so on.
+     */
+    @Override
     public void run() {
         logger.info("sleep time: " + sleepTime + "ms");
         for (;;) {
@@ -224,4 +310,4 @@
         } // for (;;)
     }
 }
-// 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 :