Merge "Add missing JavaDoc to validators package"

java/com/google/gerrit/server/git/validators/AccountValidator.java

@@ -36,6 +36,11 @@ import org.eclipse.jgit.lib.ObjectId;
 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 @@ public class AccountValidator {
     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,

java/com/google/gerrit/server/git/validators/CommitValidationException.java

@@ -18,6 +18,11 @@ import com.google.common.collect.ImmutableList;
 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 @@ public class CommitValidationException extends ValidationException {
     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()) {

java/com/google/gerrit/server/git/validators/MergeValidators.java

@@ -52,6 +52,15 @@ import org.eclipse.jgit.lib.Config;
 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 @@ public class MergeValidators {
     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 @@ public class MergeValidators {
     }
   }
 
+  /** 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 @@ public class MergeValidators {
     }
   }
 
-  /** 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 @@ public class MergeValidators {
     }
   }
 
+  /** Validator to ensure that group refs are not mutated. */
   public static class GroupMergeValidator implements MergeValidationListener {
     public interface Factory {
       GroupMergeValidator create();

java/com/google/gerrit/server/git/validators/RefOperationValidationException.java

@@ -19,6 +19,10 @@ import static java.util.stream.Collectors.joining;
 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;

java/com/google/gerrit/server/git/validators/RefOperationValidators.java

@@ -36,6 +36,12 @@ import java.util.List;
 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 @@ public class RefOperationValidators {
     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;

java/com/google/gerrit/server/git/validators/UploadValidationException.java

@@ -16,6 +16,7 @@ package com.google.gerrit.server.git.validators;
 
 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;

java/com/google/gerrit/server/git/validators/UploadValidators.java

@@ -26,6 +26,7 @@ import org.eclipse.jgit.transport.PreUploadHook;
 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;

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 @@ public class ValidationMessage {
   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;
   }

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;