DOC: docs for new code

src/main/java/caosdb/server/CaosDBServer.java

@@ -635,7 +635,6 @@ public class CaosDBServer extends Application {
     protectedRouter.attach("/scripting", ScriptingResource.class);
     protectedRouter.attach("/Entities/names", EntityNamesResource.class);
     protectedRouter.attach("/Entity/names", EntityNamesResource.class);
-
     protectedRouter.attach("/Entities", EntityResource.class);
     protectedRouter.attach("/Entities/", EntityResource.class);
     protectedRouter.attach("/Entities/{specifier}", EntityResource.class);

src/main/java/caosdb/server/database/BackendTransaction.java

@@ -146,6 +146,12 @@ public abstract class BackendTransaction implements Undoable {
     this.addMeasurement(this, t2 - t1);
   }
 
+  /**
+   * Intialiaze the adapters to the database backend.
+   *
+   * <p>Currently this is hard-coded to the MySQL-Backend but the architecture of this class is
+   * designed to make it easy in the future to choose other implementations (i.e. other back-ends)
+   */
   public static void init() {
     if (impl.isEmpty()) {
       setImpl(GetAllNamesImpl.class, MySQLGetAllNames.class);

src/main/java/caosdb/server/database/DatabaseUtils.java

@@ -186,6 +186,14 @@ public class DatabaseUtils {
     return ret;
   }
 
+  /**
+   * Helper function for parsing MySQL results.
+   *
+   * <p>This function creates SparseEntities and parses only the name, the role and the acl of an
+   * entity.
+   *
+   * <p>Never returns null.
+   */
   public static SparseEntity parseNameRoleACL(ResultSet rs) throws SQLException {
     final SparseEntity ret = new SparseEntity();
     ret.role = bytes2UTF8(rs.getBytes("EntityRole"));
@@ -194,6 +202,14 @@ public class DatabaseUtils {
     return ret;
   }
 
+  /**
+   * Helper function for parsing MySQL results.
+   *
+   * <p>This function creates SparseEntities and parses all fields which belong to a SparseEntity:
+   * id, name, role, acl, description, datatype, and the file properties.
+   *
+   * <p>Never returns null.
+   */
   public static SparseEntity parseEntityResultSet(final ResultSet rs) throws SQLException {
     SparseEntity ret = parseNameRoleACL(rs);
     ret.id = rs.getInt("EntityID");

src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java

@@ -11,6 +11,7 @@ import java.sql.SQLException;
 import java.util.ArrayList;
 import java.util.List;
 
+/** Retrieve name, role and acl of all entities from the MySQL backend. */
 public class MySQLGetAllNames extends MySQLTransaction implements GetAllNamesImpl {
 
   public MySQLGetAllNames(Access access) {

src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveSparseEntity.java

@@ -31,6 +31,11 @@ import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
 
+/**
+ * Retrieve a single SparseEntity by id.
+ *
+ * <p>A SparseEntity contains only id, name, role, acl, datatype and the file properties.
+ */
 public class MySQLRetrieveSparseEntity extends MySQLTransaction
     implements RetrieveSparseEntityImpl {
 

src/main/java/caosdb/server/database/backend/interfaces/GetAllNamesImpl.java

@@ -3,6 +3,11 @@ package caosdb.server.database.backend.interfaces;
 import caosdb.server.database.proto.SparseEntity;
 import java.util.List;
 
+/**
+ * Interface for the retrieval of all known names from the backend.
+ *
+ * <p>The returned list contains SparseEntities which have only their name, role and acl defined.
+ */
 public interface GetAllNamesImpl extends BackendTransactionImpl {
 
   List<SparseEntity> execute();

src/main/java/caosdb/server/entity/EntityInterface.java

@@ -171,8 +171,10 @@ public interface EntityInterface
 
   public abstract void checkPermission(Permission permission);
 
+  /** Return true iff the current thread's subject has a permission. */
   public abstract boolean hasPermission(Permission permission);
 
+  /** Return true iff the given subject has a permission. */
   public abstract boolean hasPermission(Subject subject, Permission permission);
 
   public abstract boolean hasEntityACL();

src/main/java/caosdb/server/jobs/core/RetriveAllNames.java

@@ -8,6 +8,13 @@ import caosdb.server.jobs.JobExecutionTime;
 import caosdb.server.permissions.EntityPermission;
 import caosdb.server.utils.EntityStatus;
 
+/**
+ * A jobs which retrieves all known names for which the requesting user has the RETRIEVE_ENTITY
+ * permission.
+ *
+ * <p>The entites' status are set to VALID because the entities parents and properties do not have
+ * to be retrieved.
+ */
 @JobAnnotation(flag = "names", time = JobExecutionTime.INIT)
 public class RetriveAllNames extends FlagJob {
 

src/main/java/caosdb/server/resource/transaction/handlers/GetNamesRequestHandler.java

@@ -5,6 +5,7 @@ import caosdb.server.resource.transaction.EntityResource;
 
 public class GetNamesRequestHandler extends RequestHandler<RetrieveContainer> {
 
+  /** Adds the `names` flag to the RetrieveContainer which triggers the RetrieveAllNames job. */
   @Override
   public void handle(EntityResource t, RetrieveContainer container) throws Exception {
     container.getFlags().put("names", null);