Merge changes I44bed941,I06b719ab,I02f02cb9

* changes:
  Add JavaDoc to all public methods of GroupCollector
  Fix nits in DelegateRefDatabase
  Implement getTipsWithSha1 in Delegate- and PermissionAwareRefDb

java/com/google/gerrit/server/git/DelegateRefDatabase.java

@@ -17,6 +17,9 @@ package com.google.gerrit.server.git;
 import java.io.IOException;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import org.eclipse.jgit.annotations.NonNull;
+import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.Ref;
 import org.eclipse.jgit.lib.RefDatabase;
 import org.eclipse.jgit.lib.RefRename;
@@ -24,7 +27,8 @@ import org.eclipse.jgit.lib.RefUpdate;
 import org.eclipse.jgit.lib.Repository;
 
 /**
- * Wrapper around {@link RefDatabase} that delegates all calls to the wrapped {@link RefDatabase}.
+ * Wrapper around {@link RefDatabase} that delegates all calls to the wrapped {@link Repository}'s
+ * {@link RefDatabase}.
  */
 public class DelegateRefDatabase extends RefDatabase {
 
@@ -41,7 +45,7 @@ public class DelegateRefDatabase extends RefDatabase {
 
   @Override
   public void close() {
-    delegate.close();
+    delegate.getRefDatabase().close();
   }
 
   @Override
@@ -70,6 +74,12 @@ public class DelegateRefDatabase extends RefDatabase {
     return delegate.getRefDatabase().getRefs(prefix);
   }
 
+  @Override
+  @NonNull
+  public Set<Ref> getTipsWithSha1(ObjectId id) throws IOException {
+    return delegate.getRefDatabase().getTipsWithSha1(id);
+  }
+
   @Override
   public List<Ref> getAdditionalRefs() throws IOException {
     return delegate.getRefDatabase().getAdditionalRefs();

java/com/google/gerrit/server/git/GroupCollector.java

@@ -100,6 +100,11 @@ public class GroupCollector {
 
   private boolean done;
 
+  /**
+   * Returns a new {@link GroupCollector} instance.
+   *
+   * @see GroupCollector for what this class does.
+   */
   public static GroupCollector create(
       ReceivePackRefCache receivePackRefCache,
       PatchSetUtil psUtil,
@@ -115,6 +120,15 @@ public class GroupCollector {
         });
   }
 
+  /**
+   * Returns a new {@link GroupCollector} instance.
+   *
+   * <p>Used in production code by using {@link ChangeNotes.Factory} to get a group SHA1 (40 bytes
+   * string representation) from a {@link PatchSet.Id}. Unit tests use this method directly by
+   * passing their own lookup function.
+   *
+   * @see GroupCollector for what this class does.
+   */
   @VisibleForTesting
   GroupCollector(ReceivePackRefCache receivePackRefCache, Lookup groupLookup) {
     this.receivePackRefCache = receivePackRefCache;
@@ -123,6 +137,13 @@ public class GroupCollector {
     groupAliases = MultimapBuilder.hashKeys().hashSetValues().build();
   }
 
+  /**
+   * Process the given {@link RevCommit}. Callers must call {@link #visit(RevCommit)} on all commits
+   * between the current branch tip and the tip of a push, in reverse topo order (parents before
+   * children). Once all commits have been visited, call {@link #getGroups()} for the result.
+   *
+   * @see GroupCollector for what this class does.
+   */
   public void visit(RevCommit c) throws IOException {
     checkState(!done, "visit() called after getGroups()");
     Set<RevCommit> interestingParents = getInterestingParents(c);
@@ -183,6 +204,9 @@ public class GroupCollector {
     }
   }
 
+  /**
+   * Returns the groups that got collected from visiting commits using {@link #visit(RevCommit)}.
+   */
   public SortedSetMultimap<ObjectId, String> getGroups() throws IOException {
     done = true;
     SortedSetMultimap<ObjectId, String> result =

java/com/google/gerrit/server/git/PermissionAwareReadOnlyRefDatabase.java

@@ -26,10 +26,13 @@ import com.google.inject.Inject;
 import java.io.IOException;
 import java.util.Collections;
 import java.util.HashMap;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import org.eclipse.jgit.annotations.NonNull;
 import org.eclipse.jgit.annotations.Nullable;
+import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.Ref;
 import org.eclipse.jgit.lib.RefRename;
 import org.eclipse.jgit.lib.RefUpdate;
@@ -156,4 +159,17 @@ public class PermissionAwareReadOnlyRefDatabase extends DelegateRefDatabase {
     }
     return null;
   }
+
+  @Override
+  @NonNull
+  public Set<Ref> getTipsWithSha1(ObjectId id) throws IOException {
+    Set<Ref> unfiltered = super.getTipsWithSha1(id);
+    Set<Ref> result = new HashSet<>(unfiltered.size());
+    for (Ref ref : unfiltered) {
+      if (exactRef(ref.getName()) != null) {
+        result.add(ref);
+      }
+    }
+    return result;
+  }
 }