DOC: for Query.Select and RetrieveFullEntityTransaction.

src/main/java/org/caosdb/server/database/backend/transaction/RetrieveFullEntityTransaction.java

@@ -113,14 +113,10 @@ public class RetrieveFullEntityTransaction extends BackendTransaction {
       }
       if (needParents(selections)) {
         execute(new RetrieveParents(e));
-      } else {
-        // do nothing
       }
 
       if (needProperties(selections)) {
         execute(new RetrieveProperties(e));
-      } else {
-        // do nothing
       }
 
       // recursion! retrieveSubEntities calls retrieveFull sometimes, but with reduced selectors.
@@ -130,6 +126,12 @@ public class RetrieveFullEntityTransaction extends BackendTransaction {
     }
   }
 
+  /**
+   * Return true iff anything else than the id is needed for this retrieval.
+   *
+   * <p>The notorious case, where it is not necessary to retrieve the sparse entity is during
+   * `SELECT id FROM ...` queries.
+   */
   private boolean needMoreThanId(List<Selection> selections) {
     if (selections == null || selections.isEmpty()) {
       return true;
@@ -139,6 +141,12 @@ public class RetrieveFullEntityTransaction extends BackendTransaction {
     return true;
   }
 
+  /**
+   * Return true iff the properties need to be retrieved.
+   *
+   * <p>It is not necessary during `SELECT parent, name, version, ...` queries where no actual
+   * properties are being selected.
+   */
   private boolean needProperties(List<Selection> selections) {
     if (selections == null || selections.isEmpty()) {
       return true;
@@ -150,7 +158,11 @@ public class RetrieveFullEntityTransaction extends BackendTransaction {
     }
     return false;
   }
-
+  /**
+   * Return true iff the parents need to be retrieved.
+   *
+   * <p>It is not necessary during `SELECT` queries that do not select the parent.
+   */
   private boolean needParents(List<Selection> selections) {
     if (selections == null || selections.isEmpty()) {
       return true;

src/main/java/org/caosdb/server/jobs/core/RetrieveIdOnlyFlag.java

-/*
- * ** header v3.0
- * This file is a part of the CaosDB Project.
- *
- * Copyright (C) 2018 Research Group Biomedical Physics,
- * Max-Planck-Institute for Dynamics and Self-Organization Göttingen
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as
- * published by the Free Software Foundation, either version 3 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Affero General Public License for more details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program. If not, see <https://www.gnu.org/licenses/>.
- *
- * ** end header
- */
-package org.caosdb.server.jobs.core;
-
-import org.caosdb.server.entity.EntityInterface;
-import org.caosdb.server.jobs.FlagJob;
-import org.caosdb.server.jobs.JobAnnotation;
-import org.caosdb.server.jobs.TransactionStage;
-import org.caosdb.server.utils.EntityStatus;
-
-@JobAnnotation(flag = "IdOnly", stage = TransactionStage.PRE_TRANSACTION)
-public class RetrieveIdOnlyFlag extends FlagJob {
-
-  @Override
-  protected void job(final String value) {
-    if (value == null || value.equalsIgnoreCase("true")) {
-      for (final EntityInterface e : getContainer()) {
-        // do not retrieve this entity
-        e.setEntityStatus(EntityStatus.IGNORE);
-      }
-    }
-  }
-}

src/main/java/org/caosdb/server/query/Query.java

@@ -77,6 +77,12 @@ public class Query implements QueryInterface, ToElementable, TransactionInterfac
   public static class Selection {
     private final String selector;
     private Selection subselection = null;
+
+    /**
+     * These magic non-properties are those which are in the results of a {@link
+     * RetrieveSparseEntity} transaction which is why they do not need to be retrieved with a {@link
+     * RetrieveEntityProperties} transaction.
+     */
     static final Set<String> MAGIC_NON_PROPERTIES =
         new HashSet<>(
             Arrays.asList(
@@ -119,14 +125,25 @@ public class Query implements QueryInterface, ToElementable, TransactionInterfac
       return ret;
     }
 
+    /**
+     * Return true iff this selector selects the parent of an entity. If not, the retrieval in
+     * {@link RetrieveFullEntityTransaction} might be optimized by not retrieving the parents at
+     * all.
+     */
     public boolean isParent() {
       return this.selector.equalsIgnoreCase("parent");
     }
 
+    /**
+     * Return true iff this selector selects anything that is most likely a property. If not, the
+     * retrieval in {@link RetrieveFullEntityTransaction} might be optimized by not retrieving the
+     * properties at all.
+     */
     public boolean isProperty() {
       return !MAGIC_NON_PROPERTIES.contains(this.selector.toLowerCase());
     }
 
+    /** Return true iff this selector selects the id of an entity. */
     public boolean isId() {
       return this.selector.equalsIgnoreCase("id");
     }