DOC: documentation and an additional check for readability of the drop off box folder added

src/main/java/caosdb/server/resource/InfoResource.java

@@ -32,8 +32,15 @@ import org.jdom2.JDOMException;
 import org.restlet.representation.Representation;
 import org.restlet.resource.Options;
 
+/**
+ * This class represents the information retrieved by the /Info GET request to CaosDB.
+ */
 public class InfoResource extends AbstractCaosDBServerResource {
 
+    /**
+     * The response to the HTTP GET request is generated here.
+     * @return The response code for OK and the resulting info XML document.
+     */
   @Override
   protected Representation httpGetInChildClass() throws Exception {
     final Document doc = new Document();
@@ -45,12 +52,19 @@ public class InfoResource extends AbstractCaosDBServerResource {
     return ok(doc);
   }
 
+    /**
+     * There is no POST request specified for the /Info resource.
+     */
   @Override
   protected Representation httpPostInChildClass(final Representation entity)
       throws ConnectionException, JDOMException {
     return null;
   }
 
+    /**
+     * TODO: Can this stub be removed?
+     */
+  @Deprecated
   @Options
   public static Representation describeResource() {
     return null;

src/main/java/caosdb/server/utils/Info.java

@@ -95,6 +95,17 @@ public class Info extends AbstractObservable implements Observer, TransactionInt
     return recordTypesCount;
   }
 
+    /**
+     * Utility function that takes an array of file objects and returns a linked list containing
+     * XML representations of all files within each contained directory.
+     * All files in the array that are directories are recursively traversed.
+     * This function is used for files within the drop off box only.
+     * 
+     * @param files An array of file objects.
+     * @return A linked list containing XML elements. The path attribute of these elements is set
+     *         to the absolute path of the filenames where the path to the drop off box is removed
+     *         at the beginning.
+     */
   private static LinkedList<Element> getFlatList(final File[] files) {
     try {
       final LinkedList<Element> ret = new LinkedList<Element>();
@@ -158,6 +169,20 @@ public class Info extends AbstractObservable implements Observer, TransactionInt
     return toElement(false);
   }
 
+    /**
+     * Generates an XML element showing the information for the /Info resource in CaosDB.
+     *
+     * @return An XML element containing:
+     *            - The number of records
+     *            - The number of properties
+     *            - The number of record types
+     *            - The number of files
+     *            - The total file size
+     *            - The number of temp files
+     *            - The path of the DropOffBox
+     *            - A tree of files in the DropOffBox
+     * TODO: The error format for missing or not readable drop off box has to be specified.
+     */
   public static Element toElement(final boolean tree) throws Exception, SQLException {
     dropOffBox = new File(FileSystem.getDropOffBox());
     final Element info = new Element("Stats");
@@ -173,14 +198,19 @@ public class Info extends AbstractObservable implements Observer, TransactionInt
     }
     final Element e = new Element("dropOffBox");
     if (dropOffBox.isDirectory()) {
-      if (tree) {
-        e.setAttribute("path", dropOffBox.getAbsolutePath());
-        e.addContent(getTree(dropOffBox.listFiles()));
-      } else {
-        e.setAttribute("path", dropOffBox.getAbsolutePath());
-        e.addContent(getFlatList(dropOffBox.listFiles()));
-      }
+        if (dropOffBox.isReadable()) {
+            if (tree) {
+                e.setAttribute("path", dropOffBox.getAbsolutePath());
+                e.addContent(getTree(dropOffBox.listFiles()));
+            } else {
+                e.setAttribute("path", dropOffBox.getAbsolutePath());
+                e.addContent(getFlatList(dropOffBox.listFiles()));
+            }
+        } else {
+            // TODO: return a message that the DropOffBox is not readable.
+        }
     } else {
+        // TODO: This function should at least return a message that the DropOffBox is diabled or not present.  
     }
     info.addContent(counts);
     info.addContent(e);