Merge "Add missing JavaDoc to validators package"
diff --git a/java/com/google/gerrit/server/git/validators/AccountValidator.java b/java/com/google/gerrit/server/git/validators/AccountValidator.java
index c6af49c..4755f5f 100644
--- a/java/com/google/gerrit/server/git/validators/AccountValidator.java
+++ b/java/com/google/gerrit/server/git/validators/AccountValidator.java
@@ -36,6 +36,11 @@
import org.eclipse.jgit.lib.Repository;
import org.eclipse.jgit.revwalk.RevWalk;
+/**
+ * Validator that is used to ensure that new commits on any ref in {@code refs/users} are conforming
+ * to the NoteDb format for accounts. Used when a user pushes to one of the refs in {@code
+ * refs/users} manually.
+ */
public class AccountValidator {
private final Provider<IdentifiedUser> self;
@@ -52,6 +57,10 @@
this.emailValidator = emailValidator;
}
+ /**
+ * Returns a list of validation messages. An empty list means that there were no issues found. If
+ * the list is non-empty, the commit will be rejected.
+ */
public List<String> validate(
Account.Id accountId,
Repository allUsersRepo,
diff --git a/java/com/google/gerrit/server/git/validators/CommitValidationException.java b/java/com/google/gerrit/server/git/validators/CommitValidationException.java
index bffe382..4dd2951 100644
--- a/java/com/google/gerrit/server/git/validators/CommitValidationException.java
+++ b/java/com/google/gerrit/server/git/validators/CommitValidationException.java
@@ -18,6 +18,11 @@
import com.google.gerrit.server.validators.ValidationException;
import java.util.List;
+/**
+ * Exception thrown when a Git commit fails validations. Gerrit supports a wide range of validations
+ * (for example it validates any commits pushed to NoteDb refs for format compliance or allows to
+ * enforce commit message lengths to not exceed a certain length).
+ */
public class CommitValidationException extends ValidationException {
private static final long serialVersionUID = 1L;
private final ImmutableList<CommitValidationMessage> messages;
@@ -42,11 +47,12 @@
this.messages = ImmutableList.of();
}
+ /** Returns all validation messages individually. */
public ImmutableList<CommitValidationMessage> getMessages() {
return messages;
}
- /** @return the reason string along with all validation messages. */
+ /** Returns all validation as a single, formatted string. */
public String getFullMessage() {
StringBuilder sb = new StringBuilder(getMessage());
if (!messages.isEmpty()) {
diff --git a/java/com/google/gerrit/server/git/validators/MergeValidators.java b/java/com/google/gerrit/server/git/validators/MergeValidators.java
index 9caef4f..8abe5c6 100644
--- a/java/com/google/gerrit/server/git/validators/MergeValidators.java
+++ b/java/com/google/gerrit/server/git/validators/MergeValidators.java
@@ -52,6 +52,15 @@
import org.eclipse.jgit.lib.Repository;
import org.eclipse.jgit.revwalk.RevWalk;
+/**
+ * Collection of validators that run inside Gerrit before a change is submitted. The main purpose is
+ * to ensure that NoteDb data is mutated in a controlled way.
+ *
+ * <p>The difference between this and {@link OnSubmitValidators} is that this validates the original
+ * commit. Depending on the {@link com.google.gerrit.server.submit.SubmitStrategy} that the project
+ * chooses, the resulting commit in the repo might differ from this original commit. In case you
+ * want to validate the resulting commit, use {@link OnSubmitValidators}
+ */
public class MergeValidators {
private static final FluentLogger logger = FluentLogger.forEnclosingClass();
@@ -76,6 +85,10 @@
this.groupValidatorFactory = groupValidatorFactory;
}
+ /**
+ * Runs all validators and throws a {@link MergeValidationException} for the first validator that
+ * failed. Only the first violation is propagated and processing is stopped thereafter.
+ */
public void validatePreMerge(
Repository repo,
CodeReviewCommit commit,
@@ -96,6 +109,7 @@
}
}
+ /** Validator for any commits to {@code refs/meta/config}. */
public static class ProjectConfigValidator implements MergeValidationListener {
private static final String INVALID_CONFIG =
"Change contains an invalid project configuration.";
@@ -237,7 +251,7 @@
}
}
- /** Execute merge validation plug-ins */
+ /** Validator that calls to plugins that provide additional validators. */
public static class PluginMergeValidationListener implements MergeValidationListener {
private final PluginSetContext<MergeValidationListener> mergeValidationListeners;
@@ -318,6 +332,7 @@
}
}
+ /** Validator to ensure that group refs are not mutated. */
public static class GroupMergeValidator implements MergeValidationListener {
public interface Factory {
GroupMergeValidator create();
diff --git a/java/com/google/gerrit/server/git/validators/RefOperationValidationException.java b/java/com/google/gerrit/server/git/validators/RefOperationValidationException.java
index d27cc38..9fbca00 100644
--- a/java/com/google/gerrit/server/git/validators/RefOperationValidationException.java
+++ b/java/com/google/gerrit/server/git/validators/RefOperationValidationException.java
@@ -19,6 +19,10 @@
import com.google.common.collect.ImmutableList;
import com.google.gerrit.server.validators.ValidationException;
+/**
+ * Exception to be thrown when the validation of a ref operation fails and should be aborted.
+ * Examples of a ref operations include creating or updating refs.
+ */
public class RefOperationValidationException extends ValidationException {
private static final long serialVersionUID = 1L;
private final ImmutableList<ValidationMessage> messages;
diff --git a/java/com/google/gerrit/server/git/validators/RefOperationValidators.java b/java/com/google/gerrit/server/git/validators/RefOperationValidators.java
index 3d1eeef..f3d8f4a 100644
--- a/java/com/google/gerrit/server/git/validators/RefOperationValidators.java
+++ b/java/com/google/gerrit/server/git/validators/RefOperationValidators.java
@@ -36,6 +36,12 @@
import org.eclipse.jgit.lib.RefUpdate;
import org.eclipse.jgit.transport.ReceiveCommand;
+/**
+ * Collection of validation listeners that are called before a ref update is performed with the
+ * command to be run. This is called from the git push path as well as Gerrit's handlers for
+ * creating or deleting refs. Calls out to {@link RefOperationValidationListener} provided by
+ * plugins.
+ */
public class RefOperationValidators {
private static final FluentLogger logger = FluentLogger.forEnclosingClass();
@@ -70,6 +76,11 @@
event.user = user;
}
+ /**
+ * Returns informational validation messages and throws a {@link RefOperationValidationException}
+ * when the first validator fails. Will not process any more validators after the first failure
+ * was encountered.
+ */
public List<ValidationMessage> validateForRefOperation() throws RefOperationValidationException {
List<ValidationMessage> messages = new ArrayList<>();
boolean withException = false;
diff --git a/java/com/google/gerrit/server/git/validators/UploadValidationException.java b/java/com/google/gerrit/server/git/validators/UploadValidationException.java
index be264b6..da2fb98 100644
--- a/java/com/google/gerrit/server/git/validators/UploadValidationException.java
+++ b/java/com/google/gerrit/server/git/validators/UploadValidationException.java
@@ -16,6 +16,7 @@
import org.eclipse.jgit.transport.ServiceMayNotContinueException;
+/** Exception to be thrown when an {@link UploadValidationListener} fails. */
public class UploadValidationException extends ServiceMayNotContinueException {
private static final long serialVersionUID = 1L;
diff --git a/java/com/google/gerrit/server/git/validators/UploadValidators.java b/java/com/google/gerrit/server/git/validators/UploadValidators.java
index 6847a28..60360a2 100644
--- a/java/com/google/gerrit/server/git/validators/UploadValidators.java
+++ b/java/com/google/gerrit/server/git/validators/UploadValidators.java
@@ -26,6 +26,7 @@
import org.eclipse.jgit.transport.ServiceMayNotContinueException;
import org.eclipse.jgit.transport.UploadPack;
+/** Collection of validators to run before Gerrit sends pack data to a client. */
public class UploadValidators implements PreUploadHook {
private final PluginSetContext<UploadValidationListener> uploadValidationListeners;
diff --git a/java/com/google/gerrit/server/git/validators/ValidationMessage.java b/java/com/google/gerrit/server/git/validators/ValidationMessage.java
index db59492..faf29fe 100644
--- a/java/com/google/gerrit/server/git/validators/ValidationMessage.java
+++ b/java/com/google/gerrit/server/git/validators/ValidationMessage.java
@@ -14,6 +14,10 @@
package com.google.gerrit.server.git.validators;
+/**
+ * Message used as result of a validation that run during a git operation (for example {@code git
+ * push}. Intended to be shown to users.
+ */
public class ValidationMessage {
public enum Type {
ERROR("ERROR: "),
@@ -35,24 +39,34 @@
private final String message;
private final Type type;
+ /** @see ValidationMessage */
public ValidationMessage(String message, Type type) {
this.message = message;
this.type = type;
}
+ // TODO: Remove and move callers to ValidationMessage(String message, Type type)
public ValidationMessage(String message, boolean isError) {
this.message = message;
this.type = (isError ? Type.ERROR : Type.OTHER);
}
+ /** Returns the message to be shown to the user. */
public String getMessage() {
return message;
}
+ /**
+ * Returns the {@link Type}. Used to as prefix for the message in the git CLI and to color
+ * messages.
+ */
public Type getType() {
return type;
}
+ /**
+ * Returns {@true} if this message is an error. Used to decide if the operation should be aborted.
+ */
public boolean isError() {
return type == Type.ERROR;
}
diff --git a/java/com/google/gerrit/server/validators/ValidationException.java b/java/com/google/gerrit/server/validators/ValidationException.java
index 53ded1f..9562e88 100644
--- a/java/com/google/gerrit/server/validators/ValidationException.java
+++ b/java/com/google/gerrit/server/validators/ValidationException.java
@@ -14,6 +14,11 @@
package com.google.gerrit.server.validators;
+/**
+ * Exception to be thrown either directly or subclassed indicating that we failed to validate a Git
+ * operation. Failures range from internal checks for NoteDb format and consistency to
+ * plugin-provided checks.
+ */
public class ValidationException extends Exception {
private static final long serialVersionUID = 1L;
