--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java	Fri Mar 26 15:05:11 2010 +0000
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/ProxyArtifact.java	Fri Mar 26 16:16:32 2010 +0000
@@ -11,32 +11,69 @@
 import java.io.OutputStream;
 
 /**
+ * The proxy artifact is a wrapper around another artifact. It simply forwards
+ * the interface calls to this underlaying artifact.
+ * The reason for using proxy artifacts is enable the workflow to exchange
+ * artifacts at any time by something else without losing the concrete
+ * artifact. From the outside it always looks like there is only one
+ * distinct artifact.<br>
+ *
+ * An inner artifact is able to replace itself by indirectly hand over
+ * the replacement via the call context to the proxy artifact.<br>
+ * To do so the proxied artifact has to call
+ * <code>callContext.getContextValue(EPLACE_PROXY, replacement);</code>. 
+ * After the current call (describe, feed, advance and out) of the proxied
+ * artifact is finished the proxy artifact replaces the former proxied artifact
+ * with the replacement.
+ * 
  * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
  */
 public class ProxyArtifact
 extends      DefaultArtifact
 {
+    /**
+     * Key to signal that the proxied artifact should be replaced.
+     */
     public static final Object REPLACE_PROXY = new Object();
 
     private static Logger logger = Logger.getLogger(ProxyArtifact.class);
 
+    /**
+     * The proxied artifact.
+     */
     protected Artifact proxied;
 
+    /**
+     * Default constructor.
+     */
     public ProxyArtifact() {
     }
 
+    /**
+     * Constructor to create a new proxy artifact around a given artifact.
+     * @param proxied The artifact to be proxied.
+     */
     public ProxyArtifact(Artifact proxied) {
         this.proxied = proxied;
     }
 
+    /**
+     * The currently proxied artifact.
+     * @return The proxied artifact.
+     */
     public Artifact getProxied() {
         return proxied;
     }
 
+    /**
+     * Explicitly set the proxied artifacts.
+     * @param proxied
+     */
     public void setProxied(Artifact proxied) {
         this.proxied = proxied;
     }
 
+    @Override
     public void setIdentifier(String identifier) {
         this.identifier = identifier;
 
@@ -44,6 +81,11 @@
             proxied.setIdentifier(identifier);
     }
 
+    /**
+     * Method to check if the current proxied artifact should be replaced
+     * by a new one coming from the call context.
+     * @param callContext
+     */
     protected void checkReplacement(CallContext callContext) {
         Object replacement = callContext.getContextValue(REPLACE_PROXY);
         if (replacement instanceof Artifact) {
@@ -51,12 +93,14 @@
         }
     }
 
+    @Override
     public String hash() {
         return proxied != null
             ? proxied.hash()
             : super.hash();
     }
 
+    @Override
     public Document describe(Document data, CallContext context) {
         try {
             return proxied != null
@@ -68,6 +112,7 @@
         }
     }
 
+    @Override
     public Document advance(Document target, CallContext context) {
         try {
             return proxied != null
@@ -79,6 +124,7 @@
         }
     }
 
+    @Override
     public Document feed(Document target, CallContext context) {
         try {
             return proxied != null
@@ -90,6 +136,7 @@
         }
     }
 
+    @Override
     public void out(
         Document     format,
         OutputStream out,
@@ -110,6 +157,7 @@
         }
     }
 
+    @Override
     public void endOfLife(Object context) {
         if (proxied != null) {
             proxied.endOfLife(context);
@@ -119,6 +167,7 @@
         }
     }
 
+    @Override
     public void cleanup(Object context) {
         if (proxied != null)
             proxied.cleanup(context);
@@ -126,4 +175,4 @@
             super.cleanup(context);
     }
 }
-// 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 :