DOC: more source docs

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

@@ -34,6 +34,14 @@ import org.caosdb.server.database.proto.VersionHistoryItem;
 import org.caosdb.server.entity.EntityInterface;
 import org.caosdb.server.entity.Version;
 
+/**
+ * Abstract base class which retrieves and caches the full, but flag version history. The
+ * implementations then use the flat version history to construct either single version information
+ * items (see {@link RetrieveVersionInfo}) or the complete history as a tree (see {@link
+ * RetrieveVersionHistory})
+ *
+ * @author Timm Fitschen (t.fitschen@indiscale.com)
+ */
 public abstract class VersionTransaction
     extends CacheableBackendTransaction<Integer, HashMap<String, VersionHistoryItem>> {
 
@@ -44,6 +52,11 @@ public abstract class VersionTransaction
   /** A map of all history items which belong to this entity. The keys are the version ids. */
   private HashMap<String, VersionHistoryItem> historyItems;
 
+  /**
+   * Invalidate a cache item. This should be called upon update of entities.
+   *
+   * @param entityId
+   */
   public static void removeCached(Integer entityId) {
     cache.remove(entityId);
   }
@@ -61,8 +74,9 @@ public abstract class VersionTransaction
 
   /** 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;
+  protected void process(HashMap<String, VersionHistoryItem> historyItems)
+      throws TransactionException {
+    this.historyItems = historyItems;
   }
 
   @Override
@@ -78,11 +92,22 @@ public abstract class VersionTransaction
     return this.entity;
   }
 
-  /** Return a list of direct predecessors which have their direct predecessors attached */
-  protected List<Version> getPredecessors(String id, boolean transitive) {
+  /**
+   * Return a list of direct predecessors. The predecessors are constructed by {@link
+   * #getVersion(String)}.
+   *
+   * <p>If transitive is true, this function is called recursively on the predecessors as well,
+   * resulting in a list of trees of predecessors, with the direct predecessors at the root(s).
+   *
+   * @param versionId
+   * @param transitive
+   * @return A list of predecessors.
+   */
+  protected List<Version> getPredecessors(String versionId, boolean transitive) {
     LinkedList<Version> result = new LinkedList<>();
-    if (getHistoryItems().containsKey(id) && getHistoryItems().get(id).parents != null)
-      for (String p : getHistoryItems().get(id).parents) {
+    if (getHistoryItems().containsKey(versionId)
+        && getHistoryItems().get(versionId).parents != null)
+      for (String p : getHistoryItems().get(versionId).parents) {
         Version predecessor = getVersion(p);
         if (transitive) {
           predecessor.setPredecessors(getPredecessors(p, transitive));
@@ -92,17 +117,34 @@ public abstract class VersionTransaction
     return result;
   }
 
-  protected abstract Version getVersion(String version);
+  /**
+   * To be implemented by the base class. The idea is, that the base class decides which information
+   * is being included into the Version instance.
+   *
+   * @param versionId - the id of the version
+   * @return
+   */
+  protected abstract Version getVersion(String versionId);
 
-  /** Return a list of direct successors which have their direct successors attached */
-  protected List<Version> getSuccessors(String id, boolean transitive) {
+  /**
+   * Return a list of direct successors. The successors are constructed by {@link
+   * #getVersion(String)}.
+   *
+   * <p>If transitive is true, this function is called recursively on the successors as well,
+   * resulting in a list of trees of successors, with the direct successors at the root(s).
+   *
+   * @param versionId
+   * @param transitive
+   * @return A list of successors.
+   */
+  protected List<Version> getSuccessors(String versionId, 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)) {
+          if (versionId.equals(p)) {
             Version successor = getVersion(i.id);
             result.add(successor);
             if (transitive) {