Document some NoteDb classes
Change-Id: Ide43fb883da7e6ae388b7c33731f3f49b9106971
diff --git a/java/com/google/gerrit/server/notedb/AbstractChangeNotes.java b/java/com/google/gerrit/server/notedb/AbstractChangeNotes.java
index 0acf20e..9a1ba35 100644
--- a/java/com/google/gerrit/server/notedb/AbstractChangeNotes.java
+++ b/java/com/google/gerrit/server/notedb/AbstractChangeNotes.java
@@ -76,6 +76,7 @@
}
}
+ /** An {@link AutoCloseable} for parsing a single commit into ChangeNotesCommits. */
public static class LoadHandle implements AutoCloseable {
private final Repository repo;
private final ObjectId id;
diff --git a/java/com/google/gerrit/server/notedb/ChangeDraftUpdate.java b/java/com/google/gerrit/server/notedb/ChangeDraftUpdate.java
index 971b537..1c0f298 100644
--- a/java/com/google/gerrit/server/notedb/ChangeDraftUpdate.java
+++ b/java/com/google/gerrit/server/notedb/ChangeDraftUpdate.java
@@ -206,6 +206,7 @@
cache.get(k.commitId()).deleteComment(k.key());
}
+ // keyed by commit ID.
Map<ObjectId, RevisionNoteBuilder> builders = cache.getBuilders();
boolean touchedAnyRevs = false;
boolean hasComments = false;
diff --git a/java/com/google/gerrit/server/notedb/ChangeNotesCommit.java b/java/com/google/gerrit/server/notedb/ChangeNotesCommit.java
index 78f6afc..71cb8c9 100644
--- a/java/com/google/gerrit/server/notedb/ChangeNotesCommit.java
+++ b/java/com/google/gerrit/server/notedb/ChangeNotesCommit.java
@@ -43,6 +43,8 @@
* </ul>
*/
public class ChangeNotesCommit extends RevCommit {
+
+ /** A {@link RevWalk} producing {@link ChangeNotesCommit}s. */
public static ChangeNotesRevWalk newRevWalk(Repository repo) {
return new ChangeNotesRevWalk(repo);
}
@@ -62,6 +64,7 @@
};
}
+ /** A {@link RevWalk} that creates {@link ChangeNotesCommit}s rather than {@link RevCommit}s */
public static class ChangeNotesRevWalk extends RevWalk {
private ChangeNotesRevWalk(Repository repo) {
super(repo);
diff --git a/java/com/google/gerrit/server/notedb/ChangeRevisionNote.java b/java/com/google/gerrit/server/notedb/ChangeRevisionNote.java
index b6443f1..4e52093 100644
--- a/java/com/google/gerrit/server/notedb/ChangeRevisionNote.java
+++ b/java/com/google/gerrit/server/notedb/ChangeRevisionNote.java
@@ -28,6 +28,7 @@
import org.eclipse.jgit.lib.ObjectReader;
import org.eclipse.jgit.util.MutableInteger;
+/** Implements the parsing of comment data, handling JSON decoding and push certificates. */
class ChangeRevisionNote extends RevisionNote<Comment> {
private final ChangeNoteJson noteJson;
private final Comment.Status status;
diff --git a/java/com/google/gerrit/server/notedb/RevisionNote.java b/java/com/google/gerrit/server/notedb/RevisionNote.java
index ff649a9..cd11e1b 100644
--- a/java/com/google/gerrit/server/notedb/RevisionNote.java
+++ b/java/com/google/gerrit/server/notedb/RevisionNote.java
@@ -26,6 +26,10 @@
import org.eclipse.jgit.lib.ObjectReader;
import org.eclipse.jgit.util.MutableInteger;
+/**
+ * Data stored in a note, parsed on demand. The data type to parse into is a generic list of type T.
+ * The source of the data is a array of raw bytes
+ */
@UsedAt(UsedAt.Project.PLUGIN_CHECKS)
public abstract class RevisionNote<T> {
static final int MAX_NOTE_SZ = 25 << 20;
@@ -64,6 +68,7 @@
return entities;
}
+ /** Reads the raw data, and delegates parsing to the {@link #parse(byte[], int)} method. */
public void parse() throws IOException, ConfigInvalidException {
raw = reader.open(noteId, OBJ_BLOB).getCachedBytes(MAX_NOTE_SZ);
MutableInteger p = new MutableInteger();
diff --git a/java/com/google/gerrit/server/notedb/RevisionNoteBuilder.java b/java/com/google/gerrit/server/notedb/RevisionNoteBuilder.java
index e63737c..81273dc 100644
--- a/java/com/google/gerrit/server/notedb/RevisionNoteBuilder.java
+++ b/java/com/google/gerrit/server/notedb/RevisionNoteBuilder.java
@@ -36,6 +36,7 @@
import org.eclipse.jgit.lib.ObjectId;
class RevisionNoteBuilder {
+ /** Construct a new RevisionNoteMap, seeding it with an existing (immutable) RevisionNoteMap */
static class Cache {
private final RevisionNoteMap<? extends RevisionNote<? extends Comment>> revisionNoteMap;
private final Map<ObjectId, RevisionNoteBuilder> builders;
diff --git a/java/com/google/gerrit/server/notedb/RevisionNoteMap.java b/java/com/google/gerrit/server/notedb/RevisionNoteMap.java
index 3e1bad1..cf16073 100644
--- a/java/com/google/gerrit/server/notedb/RevisionNoteMap.java
+++ b/java/com/google/gerrit/server/notedb/RevisionNoteMap.java
@@ -25,8 +25,16 @@
import org.eclipse.jgit.notes.Note;
import org.eclipse.jgit.notes.NoteMap;
+/**
+ * A utility class that parses a NoteMap into commit => comment list data.
+ *
+ * @param <T> the RevisionNote for the comment type.
+ */
class RevisionNoteMap<T extends RevisionNote<? extends Comment>> {
+ // CommitID => blob ID
final NoteMap noteMap;
+
+ // CommitID => parsed data, immutable map.
final ImmutableMap<ObjectId, T> revisionNotes;
static RevisionNoteMap<ChangeRevisionNote> parse(
@@ -36,6 +44,7 @@
for (Note note : noteMap) {
ChangeRevisionNote rn = new ChangeRevisionNote(noteJson, reader, note.getData(), status);
rn.parse();
+
result.put(note.copy(), rn);
}
return new RevisionNoteMap<>(noteMap, ImmutableMap.copyOf(result));
diff --git a/java/com/google/gerrit/server/notedb/RobotCommentsRevisionNote.java b/java/com/google/gerrit/server/notedb/RobotCommentsRevisionNote.java
index 97a8ad4..fc4c9fd 100644
--- a/java/com/google/gerrit/server/notedb/RobotCommentsRevisionNote.java
+++ b/java/com/google/gerrit/server/notedb/RobotCommentsRevisionNote.java
@@ -26,6 +26,7 @@
import org.eclipse.jgit.lib.ObjectId;
import org.eclipse.jgit.lib.ObjectReader;
+/** Like {@link RevisionNote} but for robot comments. */
public class RobotCommentsRevisionNote extends RevisionNote<RobotComment> {
private final ChangeNoteJson noteUtil;
