DOC: more code docs for the Job class

src/main/java/org/caosdb/server/database/proto/Rule.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.database.proto;
-//
-//import java.io.Serializable;
-//import org.caosdb.server.jobs.core.JobFailureSeverity;
-/
-//public class Rule implements Serializable {
-//
-//  private static final long serialVersionUID = 1122097540596265945L;
-//
-//  public int domain = 0;
-//  public int entity = 0;
-//  public String job = null;
-//  public String transaction = null;
-//  public JobFailureSeverity severity = null;
-//}

src/main/java/org/caosdb/server/jobs/Job.java

@@ -162,22 +162,37 @@ public abstract class Job {
   }
 
   /**
-   * This assumes that the parent has either an id (persistent or temporary) or a name.
+   * Check if an entity ('child') is a direct or indirect child of another
+   * entity ('targetParent').
    *
-   * @param child
-   * @param parent
-   * @return
+   * This assumes that the parent has either an id (persistent or temporary) or
+   * a name.
+   *
+   * If the targetParent is not in the set of parents of the child, this method
+   * iterates through the direct parents of the child.
+   *
+   * If the both entities are part of this transaction, they are resolved within
+   * this transaction. Otherwise they are fetched from the database backend or
+   * the whole evaluation takes place in the backend (if both have persistent
+   * ids and are not part of this transaction).
+   *
+   * Also, if both entities have the same id or name, the return value is true.
+   *
+   * @param child the child entity
+   * @param targetParent the parent entity
+   * @return true iff targetParent is a direct or indirect parent of the child
+   * or when the ids or names match.
    * @throws Message
    */
-  protected final boolean isSubType(final EntityInterface child, final EntityInterface parent)
+  protected final boolean isSubType(final EntityInterface child, final EntityInterface targetParent)
       throws EntityWasNotUniqueException {
-    if (parent.hasId()) {
-      if (parent.getId().equals(child.getId())) {
+    if (targetParent.hasId()) {
+      if (targetParent.getId().equals(child.getId())) {
         return true;
       }
 
-    } else if (parent.hasName()) {
-      if (parent.getName().equals(child.getName())) {
+    } else if (targetParent.hasName()) {
+      if (targetParent.getName().equals(child.getName())) {
         return true;
       }
     }
@@ -198,15 +213,15 @@ public abstract class Job {
       }
 
       if (resolvedDirectParent != null) {
-        if (isSubType(resolvedDirectParent, parent)) {
+        if (isSubType(resolvedDirectParent, targetParent)) {
           return true;
         }
       } else if (directParent.hasId()) {
-        if (isValidSubType(directParent.getId(), parent.getId())) {
+        if (isValidSubType(directParent.getId(), targetParent.getId())) {
           return true;
         }
       } else if (directParent.hasName()) {
-        if (isValidSubType(resolve(directParent).getId(), parent.getId())) {
+        if (isValidSubType(resolve(directParent).getId(), targetParent.getId())) {
           return true;
         }
       }
@@ -538,6 +553,15 @@ public abstract class Job {
     return this.stage;
   }
 
+  /**
+   * Resolve an entity (which might only be specified by it's name or id) to
+   * it's full representation (with properties, parents and all).
+   *
+   * @param entity the entity to be resolved.
+   * @return the resolved entity.
+   * @throws EntityWasNotUniqueException if the resolution failed due to
+   * ambuiguity of the name.
+   */
   protected EntityInterface resolve(final EntityInterface entity)
       throws EntityWasNotUniqueException {
     EntityInterface resolvedParent = null;