--- a/artifacts/src/main/java/de/intevation/artifacts/CallContext.java	Sun Feb 21 23:05:32 2010 +0000
+++ b/artifacts/src/main/java/de/intevation/artifacts/CallContext.java	Thu Mar 11 10:53:59 2010 +0000
@@ -1,26 +1,87 @@
 package de.intevation.artifacts;
 
+/**
+ * Instances of this interface are given to feed(), advance(), describe()
+ * and out() to enable the artifact to communicate with the runtime system.
+ * @author <a href="mailto:sascha.teichmann@intevation.de">Sascha L. Teichmann</a>
+ */
 public interface CallContext
 {
+    /**
+     * Constant to signal that nothing should be done
+     * with the artifact after method return.
+     */
     int NOTHING    = 0;
+    /**
+     * Constant to signal that the database timestamp
+     * should be updated after method return.
+     */
     int TOUCH      = 1;
+    /**
+     * Constant to signal that the artifact should be stored
+     * after method return.
+     */
     int STORE      = 2;
+    /**
+     * Constant to signal that the artifact fork a backgroud thread
+     * and should be hold in memory till it signals that it has
+     * finished its operation.
+     */
     int BACKGROUND = 3;
     // int DELETE     = 4;
     // int FOREVER    = 5;
 
+    /**
+     * This method may be called from feed(), describe(), advance()
+     * and out to signal what should happend with artefact after
+     * the current method call returns.
+     * @param action Valid values are NOTHING, TOUCH, STORE, BACKGROUND.
+     */
     void afterCall(int action);
 
+    /**
+     * When send to background with a afterCall(BACKGROUND) this
+     * method is to be called from the background thread to signal
+     * that the background operation has ended.
+     * @param action Same semantics as in afterCall.
+     */
     void afterBackground(int action);
 
+    /**
+     * Access to the global context of the runtime system.
+     * @return The global context.
+     */
     Object globalContext();
 
+    /**
+     * Access to the artifact database itself.
+     * @return The database.
+     */
     ArtifactDatabase getDatabase();
 
+    /**
+     * The meta data of the current call. Used to transport
+     * language preferences of the callee e.g.
+     * @return The meta information of this call.
+     */
     CallMeta getMeta();
     
+    /**
+     * Each call context has a clipboard.
+     * getContextValue is used to fetch data from this board.
+     * @param key Key of the requested item.
+     * @return The value stored for the secified value, null if
+     *         no item with this key exists.
+     */
     Object getContextValue(Object key);
 
+    /**
+     * Each call context has a clipboard.
+     * putContextValue is used to store a key/value pair onto this board.
+     * @param key   The key of the pair
+     * @param value The value of the pair.
+     * @return The formerly stored value under the given key.
+     */
     Object putContextValue(Object key, Object value);
 }
 // vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: