DOC: more source docs and some class renames

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

-/*
- * ** header v3.0 This file is a part of the CaosDB Project.
- *
- * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
- * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
- *
- * 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.backend.transaction;
-
-import java.util.HashMap;
-import org.caosdb.datetime.UTCDateTime;
-import org.caosdb.server.database.exceptions.TransactionException;
-import org.caosdb.server.database.proto.VersionHistoryItem;
-import org.caosdb.server.entity.EntityInterface;
-import org.caosdb.server.entity.Version;
-
-public class RetrieveTransactionHistory extends RetrieveVersionHistory {
-
-  public RetrieveTransactionHistory(EntityInterface e) {
-    super(e);
-  }
-
-  @Override
-  protected void process(HashMap<String, VersionHistoryItem> map) throws TransactionException {
-    super.process(map);
-    if (!map.isEmpty()) getEntity().setVersion(getHistory());
-  }
-
-  @Override
-  protected Version getVersion(String id) {
-    Version v = new Version(id);
-    VersionHistoryItem i = getHistoryItems().get(v.getId());
-    if (i != null) {
-      v.setDate(UTCDateTime.UTCSeconds(i.seconds, i.nanos));
-      v.setUsername(i.username);
-      v.setRealm(i.realm);
-    }
-    return v;
-  }
-
-  private Version getHistory() {
-    Version v = getVersion(getEntity().getVersion().getId());
-    v.setSuccessors(getSuccessors(v.getId(), true));
-    v.setPredecessors(getPredecessors(v.getId(), true));
-    v.setHead(v.getSuccessors().isEmpty());
-    v.setCompleteHistory(true);
-    return v;
-  }
-}

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

 /*
- * ** header v3.0
- * This file is a part of the CaosDB Project.
+ * ** header v3.0 This file is a part of the CaosDB Project.
  *
  * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
  * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
  *
- * 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 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.
+ * 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/>.
+ * 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.backend.transaction;
 
 import java.util.HashMap;
-import java.util.LinkedList;
-import java.util.List;
-import org.apache.commons.jcs.access.behavior.ICacheAccess;
-import org.caosdb.server.caching.Cache;
-import org.caosdb.server.database.CacheableBackendTransaction;
-import org.caosdb.server.database.backend.interfaces.RetrieveVersionHistoryImpl;
+import org.caosdb.datetime.UTCDateTime;
 import org.caosdb.server.database.exceptions.TransactionException;
 import org.caosdb.server.database.proto.VersionHistoryItem;
 import org.caosdb.server.entity.EntityInterface;
 import org.caosdb.server.entity.Version;
 
-public abstract class RetrieveVersionHistory
-    extends CacheableBackendTransaction<Integer, HashMap<String, VersionHistoryItem>> {
-
-  private static final ICacheAccess<Integer, HashMap<String, VersionHistoryItem>> cache =
-      Cache.getCache("BACKEND_RetrieveVersionHistory");
-  private EntityInterface entity;
-
-  /** A map of all history items which belong to this entity. The keys are the version ids. */
-  private HashMap<String, VersionHistoryItem> historyItems;
-
-  public static void removeCached(Integer entityId) {
-    cache.remove(entityId);
-  }
+public class RetrieveVersionHistory extends VersionTransaction {
 
   public RetrieveVersionHistory(EntityInterface e) {
-    super(cache);
-    this.entity = e;
+    super(e);
   }
 
-  @Override
-  public HashMap<String, VersionHistoryItem> executeNoCache() throws TransactionException {
-    RetrieveVersionHistoryImpl impl = getImplementation(RetrieveVersionHistoryImpl.class);
-    return impl.execute(getKey());
-  }
-
-  /** After this method call, the version map is available to the object. */
   @Override
   protected void process(HashMap<String, VersionHistoryItem> map) throws TransactionException {
-    this.historyItems = map;
+    super.process(map);
+    if (!map.isEmpty()) getEntity().setVersion(getHistory());
   }
 
   @Override
-  protected Integer getKey() {
-    return entity.getId();
-  }
-
-  public HashMap<String, VersionHistoryItem> getHistoryItems() {
-    return this.historyItems;
-  }
-
-  public EntityInterface getEntity() {
-    return this.entity;
-  }
-
-  /** Return a list of direct predecessors which have their direct predecessors attached */
-  protected List<Version> getPredecessors(String id, boolean transitive) {
-    LinkedList<Version> result = new LinkedList<>();
-    if (getHistoryItems().containsKey(id) && getHistoryItems().get(id).parents != null)
-      for (String p : getHistoryItems().get(id).parents) {
-        Version predecessor = getVersion(p);
-        if (transitive) {
-          predecessor.setPredecessors(getPredecessors(p, transitive));
-        }
-        result.add(predecessor);
-      }
-    return result;
+  protected Version getVersion(String id) {
+    Version v = new Version(id);
+    VersionHistoryItem i = getHistoryItems().get(v.getId());
+    if (i != null) {
+      v.setDate(UTCDateTime.UTCSeconds(i.seconds, i.nanos));
+      v.setUsername(i.username);
+      v.setRealm(i.realm);
+    }
+    return v;
   }
 
-  protected abstract Version getVersion(String version);
-
-  /** Return a list of direct successors which have their direct successors attached */
-  protected List<Version> getSuccessors(String id, boolean transitive) {
-    LinkedList<Version> result = new LinkedList<>();
-
-    outer:
-    for (VersionHistoryItem i : getHistoryItems().values()) {
-      if (i.parents != null)
-        for (String p : i.parents) {
-          if (id.equals(p)) {
-            Version successor = getVersion(i.id);
-            result.add(successor);
-            if (transitive) {
-              successor.setSuccessors(getSuccessors(i.id, transitive));
-            }
-            continue outer;
-          }
-        }
-    }
-    return result;
+  private Version getHistory() {
+    Version v = getVersion(getEntity().getVersion().getId());
+    v.setSuccessors(getSuccessors(v.getId(), true));
+    v.setPredecessors(getPredecessors(v.getId(), true));
+    v.setHead(v.getSuccessors().isEmpty());
+    v.setCompleteHistory(true);
+    return v;
   }
 }

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

@@ -28,7 +28,7 @@ import org.caosdb.server.database.proto.VersionHistoryItem;
 import org.caosdb.server.entity.EntityInterface;
 import org.caosdb.server.entity.Version;
 
-public class RetrieveVersionInfo extends RetrieveVersionHistory {
+public class RetrieveVersionInfo extends VersionTransaction {
 
   public RetrieveVersionInfo(EntityInterface e) {
     super(e);

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

@@ -54,7 +54,7 @@ public class UpdateEntity extends BackendTransaction {
 
         execute(new InsertEntityProperties(e));
 
-        RetrieveVersionHistory.removeCached(e.getId());
+        VersionTransaction.removeCached(e.getId());
         execute(new RetrieveVersionInfo(e));
       }
     }

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

+/*
+ * ** header v3.0
+ * This file is a part of the CaosDB Project.
+ *
+ * Copyright (C) 2020 IndiScale GmbH <info@indiscale.com>
+ * Copyright (C) 2020 Timm Fitschen <t.fitschen@indiscale.com>
+ *
+ * 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.backend.transaction;
+
+import java.util.HashMap;
+import java.util.LinkedList;
+import java.util.List;
+import org.apache.commons.jcs.access.behavior.ICacheAccess;
+import org.caosdb.server.caching.Cache;
+import org.caosdb.server.database.CacheableBackendTransaction;
+import org.caosdb.server.database.backend.interfaces.RetrieveVersionHistoryImpl;
+import org.caosdb.server.database.exceptions.TransactionException;
+import org.caosdb.server.database.proto.VersionHistoryItem;
+import org.caosdb.server.entity.EntityInterface;
+import org.caosdb.server.entity.Version;
+
+public abstract class VersionTransaction
+    extends CacheableBackendTransaction<Integer, HashMap<String, VersionHistoryItem>> {
+
+  private static final ICacheAccess<Integer, HashMap<String, VersionHistoryItem>> cache =
+      Cache.getCache("BACKEND_RetrieveVersionHistory");
+  private EntityInterface entity;
+
+  /** A map of all history items which belong to this entity. The keys are the version ids. */
+  private HashMap<String, VersionHistoryItem> historyItems;
+
+  public static void removeCached(Integer entityId) {
+    cache.remove(entityId);
+  }
+
+  public VersionTransaction(EntityInterface e) {
+    super(cache);
+    this.entity = e;
+  }
+
+  @Override
+  public HashMap<String, VersionHistoryItem> executeNoCache() throws TransactionException {
+    RetrieveVersionHistoryImpl impl = getImplementation(RetrieveVersionHistoryImpl.class);
+    return impl.execute(getKey());
+  }
+
+  /** After this method call, the version map is available to the object. */
+  @Override
+  protected void process(HashMap<String, VersionHistoryItem> map) throws TransactionException {
+    this.historyItems = map;
+  }
+
+  @Override
+  protected Integer getKey() {
+    return entity.getId();
+  }
+
+  public HashMap<String, VersionHistoryItem> getHistoryItems() {
+    return this.historyItems;
+  }
+
+  public EntityInterface getEntity() {
+    return this.entity;
+  }
+
+  /** Return a list of direct predecessors which have their direct predecessors attached */
+  protected List<Version> getPredecessors(String id, boolean transitive) {
+    LinkedList<Version> result = new LinkedList<>();
+    if (getHistoryItems().containsKey(id) && getHistoryItems().get(id).parents != null)
+      for (String p : getHistoryItems().get(id).parents) {
+        Version predecessor = getVersion(p);
+        if (transitive) {
+          predecessor.setPredecessors(getPredecessors(p, transitive));
+        }
+        result.add(predecessor);
+      }
+    return result;
+  }
+
+  protected abstract Version getVersion(String version);
+
+  /** Return a list of direct successors which have their direct successors attached */
+  protected List<Version> getSuccessors(String id, boolean transitive) {
+    LinkedList<Version> result = new LinkedList<>();
+
+    outer:
+    for (VersionHistoryItem i : getHistoryItems().values()) {
+      if (i.parents != null)
+        for (String p : i.parents) {
+          if (id.equals(p)) {
+            Version successor = getVersion(i.id);
+            result.add(successor);
+            if (transitive) {
+              successor.setSuccessors(getSuccessors(i.id, transitive));
+            }
+            continue outer;
+          }
+        }
+    }
+    return result;
+  }
+}

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

@@ -23,7 +23,6 @@
 package org.caosdb.server.jobs.core;
 
 import org.apache.shiro.authz.AuthorizationException;
-import org.caosdb.server.database.backend.transaction.RetrieveTransactionHistory;
 import org.caosdb.server.database.backend.transaction.RetrieveVersionHistory;
 import org.caosdb.server.entity.EntityInterface;
 import org.caosdb.server.jobs.FlagJob;
@@ -33,6 +32,12 @@ import org.caosdb.server.permissions.EntityPermission;
 import org.caosdb.server.utils.EntityStatus;
 import org.caosdb.server.utils.ServerMessages;
 
+/**
+ * Retrieves the complete version history of each entity and appends it to the
+ * entity.
+ * 
+ * @author Timm Fitschen (t.fitschen@indiscale.com)
+ */
 @JobAnnotation(time = JobExecutionTime.POST_TRANSACTION, flag = "H")
 public class History extends FlagJob {
 
@@ -43,7 +48,7 @@ public class History extends FlagJob {
         if (entity.getId() != null && entity.getId() > 0) {
           try {
             entity.checkPermission(EntityPermission.RETRIEVE_HISTORY);
-            final RetrieveVersionHistory t = new RetrieveTransactionHistory(entity);
+            final RetrieveVersionHistory t = new RetrieveVersionHistory(entity);
             execute(t);
           } catch (final AuthorizationException e) {
             entity.setEntityStatus(EntityStatus.UNQUALIFIED);