From ef44357ef674e7209c7df91d1e0b58656cd04af4 Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Thu, 17 Jun 2021 13:23:05 +0200
Subject: [PATCH] DOC: more code docs for the Job class

---
 .../caosdb/server/database/proto/Rule.java    | 37 --------------
 src/main/java/org/caosdb/server/jobs/Job.java | 48 ++++++++++++++-----
 2 files changed, 36 insertions(+), 49 deletions(-)
 delete mode 100644 src/main/java/org/caosdb/server/database/proto/Rule.java

diff --git a/src/main/java/org/caosdb/server/database/proto/Rule.java b/src/main/java/org/caosdb/server/database/proto/Rule.java
deleted file mode 100644
index cf0a8995..00000000
--- a/src/main/java/org/caosdb/server/database/proto/Rule.java
+++ /dev/null
@@ -1,37 +0,0 @@
-///*
-// * ** 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;
-//}
diff --git a/src/main/java/org/caosdb/server/jobs/Job.java b/src/main/java/org/caosdb/server/jobs/Job.java
index 6617d2aa..a5cfa755 100644
--- a/src/main/java/org/caosdb/server/jobs/Job.java
+++ b/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;
-- 
GitLab