--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/flys-artifacts/doc/datacage.txt	Wed Jun 06 10:02:54 2012 +0000
@@ -0,0 +1,24 @@
+The datacages behaviour is defined in the file conf/meta-data.xml .
+
+The datacage serves two purposes.
+It handles automatic 'recommendations', which are instructions
+sent by the client to add newly created artifacts to the collection.
+From a user perspective, these artifacts mainly represent curves or data
+points in the resulting diagrams.
+The second task is to let the user add already existing artifacts (i.e.
+previous calculations) or new artifacts with access to related data.
+
+Irrelevant of the type of elements (recommendations or user picked data) the
+datacage can iterate over possible artifacts by accessing its own database.
+Thus, to create a list of matching entries, database queries are used.
+
+In meta-data.xml, database queries are defined as <dc:statement> elements,
+for example
+                <dc:statement>
+                  SELECT id          AS prot_id,
+                         description AS prot_description
+                  FROM wsts WHERE kind = 1 AND river_id = ${river_id}
+                </dc:statement>
+
+As can be seen from the example, the datacage configuration file can maintain
+its own stack of variables (${river_id} in above example).