DOC: code docs for JobConfig

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

@@ -162,26 +162,23 @@ public abstract class Job {
   }
 
   /**
-   * Check if an entity ('child') is a direct or indirect child of another
-   * entity ('targetParent').
+   * Check if an entity ('child') is a direct or indirect child of another entity ('targetParent').
    *
-   * This assumes that the parent has either an id (persistent or temporary) or
-   * a name.
+   * <p>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.
+   * <p>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).
+   * <p>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.
+   * <p>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.
+   * @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 targetParent)
@@ -554,13 +551,12 @@ public abstract class Job {
   }
 
   /**
-   * Resolve an entity (which might only be specified by it's name or id) to
-   * it's full representation (with properties, parents and all).
+   * 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.
+   * @throws EntityWasNotUniqueException if the resolution failed due to ambuiguity of the name.
    */
   protected EntityInterface resolve(final EntityInterface entity)
       throws EntityWasNotUniqueException {

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

@@ -20,6 +20,24 @@ import org.caosdb.server.jobs.core.JobFailureSeverity;
 import org.caosdb.server.transaction.Transaction;
 import org.caosdb.server.utils.ConfigurationException;
 
+/**
+ * Configuration of the jobs which have to run during all entity transactions with "job rules".
+ *
+ * <p>A job rule contains of a quintuple (domain, entity, transaction type, job name, job failure
+ * severity).
+ *
+ * <p>The domain and the entities define for which entities the job (of the given name) should be
+ * loaded. The transaction type (e.g. Insert, Update, Delete) defines the transaction where this
+ * rule applies. The job failure severity sets the related property of a job.
+ *
+ * <p>The configuration is being read from a config file {@link
+ * ServerProperties#KEY_JOB_RULES_CONFIG}
+ *
+ * <p>This class works as a singleton, most of the time. It is possible to instanciate it otherwise,
+ * though.
+ *
+ * @author Timm Fitschen <t.fitschen@indiscale.com>
+ */
 public class JobConfig {
 
   private static JobConfig instance;
@@ -34,6 +52,10 @@ public class JobConfig {
     }
   }
 
+  /**
+   * The keys of these rules consist of the domain, entity and transaction. The value is a pair (job
+   * name, job failure severity).
+   */
   private final Map<String, List<Object[]>> rules;
 
   public JobConfig() throws FileNotFoundException, IOException {
@@ -44,6 +66,14 @@ public class JobConfig {
     this.rules = getRulesFromCSV(config);
   }
 
+  /**
+   * Read the rules from the CSV file.
+   *
+   * @param file
+   * @return A map with all the rules.
+   * @throws FileNotFoundException
+   * @throws IOException
+   */
   private Map<String, List<Object[]>> getRulesFromCSV(final File file)
       throws FileNotFoundException, IOException {
     try (final BufferedReader reader = new BufferedReader(new FileReader(file))) {
@@ -65,6 +95,7 @@ public class JobConfig {
     }
   }
 
+  /** Generate a unique key (for class-internal use only). */
   private String getKey(final Integer domain, final Integer entity, final String transaction) {
     final StringBuilder sb = new StringBuilder();
     sb.append("<");
@@ -77,6 +108,12 @@ public class JobConfig {
     return sb.toString();
   }
 
+  /**
+   * Read a rule from the csv-row and put it into the 'result' map
+   *
+   * @param result map with all the rules.
+   * @param row represents a single rule as a comma-separated quintuple.
+   */
   private void addRule(final Map<String, List<Object[]>> result, final String[] row) {
     if (row.length != 5) {
       throw new ConfigurationException(
@@ -99,6 +136,16 @@ public class JobConfig {
     }
   }
 
+  /**
+   * Factory method for the instanciation and configuration of a job for a specific entity.
+   *
+   * @param domain the domain of the rule
+   * @param entity the entity of the rule (this might be a particular datatype or a role, like
+   *     "RecordType")
+   * @param target the entity for which the job will run.
+   * @param transaction the transaction for which the job will run.
+   * @return A fresh job instance
+   */
   public List<Job> getConfiguredJobs(
       final Integer domain,
       final Integer entity,