v2 FailureReason

Author: RohanNagar

CHANGELOG.md

@@ -2,11 +2,44 @@
 
 ## 2.0.0 (Upcoming)
 
-### Email Address Normalization Improvements
+### Breaking Changes
+
+- The `jmail.normalize.strip.quotes` JVM system property no longer does anything.
+  Use `NormalizationOptionsBuilder#stripQuotes()` instead.
+
+
+- `FailureReason` was switched from an enum to a class in order to support custom failure reasons, so you cannot
+  use it in a `switch` statement.
+
+
+- `FailureReason.MISSING_TOP_LEVEL_DOMAIN` was changed to `FailureReason.MISSING_FINAL_DOMAIN_PART`.
+  `MISSING_TOP_LEVEL_DOMAIN` was previously used for email addresses that failed validation because
+  they ended the email address with a comment. This `FailureReason` was potentially misleading, for example
+  enabling `requireTopLevelDomain()` on your `EmailValidator`.
+
 
-#### Breaking changes
+- Email addresses that fail validation due to additional rules added to the `EmailValidator` (such as
+  `disallowIpDomain()` or `requireValidMXRecord()`) no longer returns a generic `FailureReason.FAILED_CUSTOM_VALIDATION`
+  in the `EmailValidationResult`. Instead, it returns a more specific `FailureReason` depending on the rule. 
 
-- The `jmail.normalize.strip.quotes` JVM system property no longer does anything. Use `NormalizationOptionsBuilder#stripQuotes()` instead.
+### FailureReason Improvements
+
+#### Changes to the FailureReason supplied for additional rules
+
+The `FailureReason` returned in the `EmailValidationResult` is useful to understand why a specific
+email address failed validation. In v2.0.0, the `FailureReason` returned for email addresses that failed
+one of the additional validation rules added to your `EmailValidator` (such as `disallowIpDomain()` or
+`requireValidMXRecord()`) now return more specific and useful reasons.
+
+#### Option to provide FailureReason for custom rules
+
+Additionally, you can specify your own `FailureReason` for any custom validation rules that you add
+to your `EmailValidator`. Use the new `withRule(Predicate<Email>, FailureReason)` or
+`withRules(Map<Predicate<Email>, FailureReason>)` methods to specify the failure reason for each
+of your custom rules. If no failure reason is supplied, then the rule will default to the
+`FailureReason.FAILED_CUSTOM_VALIDATION` reason.
+
+### Email Address Normalization Improvements
 
 #### New Normalization Methods
 

src/main/java/com/sanctionco/jmail/EmailValidator.java

@@ -3,9 +3,9 @@
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
-import java.util.HashSet;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.Optional;
-import java.util.Set;
 import java.util.StringJoiner;
 import java.util.function.Predicate;
 import java.util.stream.Collectors;
@@ -34,9 +34,9 @@ public final class EmailValidator {
       = ValidationRules::disallowIpDomain;
   private static final Predicate<Email> REQUIRE_TOP_LEVEL_DOMAIN_PREDICATE
       = ValidationRules::requireTopLevelDomain;
-  private static final Predicate<Email> DISALLOW_EXPLICIT_SOURCE_ROUTING
+  private static final Predicate<Email> DISALLOW_EXPLICIT_SOURCE_ROUTING_PREDICATE
       = ValidationRules::disallowExplicitSourceRouting;
-  private static final Predicate<Email> DISALLOW_QUOTED_IDENTIFIERS
+  private static final Predicate<Email> DISALLOW_QUOTED_IDENTIFIERS_PREDICATE
       = ValidationRules::disallowQuotedIdentifiers;
   private static final Predicate<Email> DISALLOW_RESERVED_DOMAINS_PREDICATE
       = ValidationRules::disallowReservedDomains;
@@ -47,14 +47,36 @@ public final class EmailValidator {
   private static final Predicate<Email> REQUIRE_ASCII_PREDICATE
       = ValidationRules::requireAscii;
 
-  private final Set<Predicate<Email>> validationPredicates;
+  private final Map<Predicate<Email>, FailureReason> validationPredicates;
 
-  EmailValidator(Set<Predicate<Email>> validationPredicates) {
-    this.validationPredicates = Collections.unmodifiableSet(validationPredicates);
+  EmailValidator(Map<Predicate<Email>, FailureReason> validationPredicates) {
+    this.validationPredicates = Collections.unmodifiableMap(validationPredicates);
   }
 
   EmailValidator() {
-    this(new HashSet<>());
+    this(new HashMap<>());
+  }
+
+  /**
+   * Create a new {@code EmailValidator} with all rules from the current instance and the
+   * additional provided custom validation rules.
+   *
+   * <p>Example usage:
+   *
+   * <pre>
+   * validator.withRules(Map.of(
+   *     email -> email.domain().startsWith("test"), new FailureReason("MUST_START_WITH_TEST"),
+   *     email -> email.localPart.contains("hello"), new FailureReason("MUST_CONTAIN_HELLO"));
+   * </pre>
+   *
+   * @param rules a collection of requirements that make a valid email address
+   * @return the new {@code EmailValidator} instance
+   */
+  public EmailValidator withRules(Map<Predicate<Email>, FailureReason> rules) {
+    Map<Predicate<Email>, FailureReason> ruleMap = new HashMap<>(validationPredicates);
+    ruleMap.putAll(rules);
+
+    return new EmailValidator(ruleMap);
   }
 
   /**
@@ -73,10 +95,8 @@ public final class EmailValidator {
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator withRules(Collection<Predicate<Email>> rules) {
-    Set<Predicate<Email>> ruleSet = new HashSet<>(validationPredicates);
-    ruleSet.addAll(rules);
-
-    return new EmailValidator(ruleSet);
+    return withRules(rules.stream()
+        .collect(Collectors.toMap(p -> p, p -> FailureReason.FAILED_CUSTOM_VALIDATION)));
   }
 
   /**
@@ -94,79 +114,116 @@ public EmailValidator withRules(Collection<Predicate<Email>> rules) {
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator withRule(Predicate<Email> rule) {
-    return withRules(Collections.singletonList(rule));
+    return withRules(Collections.singletonMap(rule, FailureReason.FAILED_CUSTOM_VALIDATION));
   }
 
   /**
-   * Create a new {@code EmailValidator} with all rules from the current instance and the
+   * Create a new {@code EmailValidator} with all rules from the current instance and an
+   * additional provided custom validation rule.
+   *
+   * <p>Example usage:
+   *
+   * <pre>
+   * validator.withRule(
+   *   email -> email.domain().startsWith("test"),
+   *   new FailureReason("DOES_NOT_START_WITH_TEST"));
+   * </pre>
+   *
+   * @param rule the requirement for a valid email address. This must be a {@link Predicate} that
+   *             accepts an {@link Email} object.
+   * @param failureReason the {@link FailureReason} to return in the {@link EmailValidationResult}
+   *                      if an email fails to pass this rule.
+   * @return the new {@code EmailValidator} instance
+   */
+  public EmailValidator withRule(Predicate<Email> rule, FailureReason failureReason) {
+    return withRules(Collections.singletonMap(rule, failureReason));
+  }
+
+  /**
+   * <p>Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#disallowIpDomain(Email)} rule.
-   * Email addresses that have an IP address for a domain will fail validation.
+   * Email addresses that have an IP address for a domain will fail validation with
+   * {@link FailureReason#CONTAINS_IP_DOMAIN}.
    *
    * <p>For example, {@code "sample@[1.2.3.4]"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator disallowIpDomain() {
-    return withRule(DISALLOW_IP_DOMAIN_PREDICATE);
+    return withRule(
+        DISALLOW_IP_DOMAIN_PREDICATE,
+        FailureReason.CONTAINS_IP_DOMAIN);
   }
 
   /**
-   * Create a new {@code EmailValidator} with all rules from the current instance and the
+   * <p>Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#requireTopLevelDomain(Email)} rule.
-   * Email addresses that do not have a top level domain will fail validation.
+   * Email addresses that do not have a top level domain will fail validation
+   * with {@link FailureReason#MISSING_TOP_LEVEL_DOMAIN}.
    *
    * <p>For example, {@code "sample@mailserver"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator requireTopLevelDomain() {
-    return withRule(REQUIRE_TOP_LEVEL_DOMAIN_PREDICATE);
+    return withRule(
+        REQUIRE_TOP_LEVEL_DOMAIN_PREDICATE,
+        FailureReason.MISSING_TOP_LEVEL_DOMAIN);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#disallowExplicitSourceRouting(Email)} rule.
-   * Email addresses that have explicit source routing will fail validation.
+   * Email addresses that have explicit source routing will fail validation with
+   * {@link FailureReason#CONTAINS_EXPLICIT_SOURCE_ROUTING}.
    *
    * <p>For example, {@code "@1st.relay,@2nd.relay:[email protected]"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator disallowExplicitSourceRouting() {
-    return withRule(DISALLOW_EXPLICIT_SOURCE_ROUTING);
+    return withRule(
+        DISALLOW_EXPLICIT_SOURCE_ROUTING_PREDICATE,
+        FailureReason.CONTAINS_EXPLICIT_SOURCE_ROUTING);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#disallowQuotedIdentifiers(Email)} rule.
-   * Email addresses that have quoted identifiers will fail validation.
+   * Email addresses that have quoted identifiers will fail validation with
+   * {@link FailureReason#CONTAINS_QUOTED_IDENTIFIER}.
    *
    * <p>For example, {@code "John Smith <[email protected]>"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator disallowQuotedIdentifiers() {
-    return withRule(DISALLOW_QUOTED_IDENTIFIERS);
+    return withRule(
+        DISALLOW_QUOTED_IDENTIFIERS_PREDICATE,
+        FailureReason.CONTAINS_QUOTED_IDENTIFIER);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#disallowReservedDomains(Email)} rule.
-   * Email addresses that have a reserved domain according to RFC 2606 will fail validation.
+   * Email addresses that have a reserved domain according to RFC 2606 will fail validation
+   * with {@link FailureReason#CONTAINS_RESERVED_DOMAIN}.
    *
    * <p>For example, {@code "[email protected]"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator disallowReservedDomains() {
-    return withRule(DISALLOW_RESERVED_DOMAINS_PREDICATE);
+    return withRule(
+        DISALLOW_RESERVED_DOMAINS_PREDICATE,
+        FailureReason.CONTAINS_RESERVED_DOMAIN);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
-   * {@link ValidationRules#requireOnlyTopLevelDomains(Email, Set)} rule.
+   * {@link ValidationRules#requireOnlyTopLevelDomains(Email, java.util.Set)} rule.
    * Email addresses that have top level domains other than those provided will
-   * fail validation.
+   * fail validation with {@link FailureReason#INVALID_TOP_LEVEL_DOMAIN}.
    *
    * <p>For example, if you require only {@link TopLevelDomain#DOT_COM}, the email address
    * {@code "[email protected]"} would be invalid.
@@ -175,28 +232,33 @@ public EmailValidator disallowReservedDomains() {
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator requireOnlyTopLevelDomains(TopLevelDomain... allowed) {
-    return withRule(email -> ValidationRules.requireOnlyTopLevelDomains(
-        email, Arrays.stream(allowed).collect(Collectors.toSet())));
+    return withRule(
+        email -> ValidationRules.requireOnlyTopLevelDomains(
+            email, Arrays.stream(allowed).collect(Collectors.toSet())),
+        FailureReason.INVALID_TOP_LEVEL_DOMAIN);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#disallowObsoleteWhitespace(Email)} rule.
    * Email addresses that have obsolete folding whitespace according to RFC 2822 will fail
-   * validation.
+   * validation with {@link FailureReason#CONTAINS_OBSOLETE_WHITESPACE}.
    *
    * <p>For example, {@code "1234   @   local(blah)  .com"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator disallowObsoleteWhitespace() {
-    return withRule(DISALLOW_OBSOLETE_WHITESPACE_PREDICATE);
+    return withRule(
+        DISALLOW_OBSOLETE_WHITESPACE_PREDICATE,
+        FailureReason.CONTAINS_OBSOLETE_WHITESPACE);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#requireValidMXRecord(Email)} rule.
-   * Email addresses that have a domain without a valid MX record will fail validation.
+   * Email addresses that have a domain without a valid MX record will fail validation with
+   * {@link FailureReason#INVALID_MX_RECORD}.
    *
    * <p><strong>NOTE: Adding this rule to your EmailValidator may increase
    * the amount of time it takes to validate email addresses, as the default initial timeout is
@@ -206,13 +268,16 @@ public EmailValidator disallowObsoleteWhitespace() {
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator requireValidMXRecord() {
-    return withRule(REQUIRE_VALID_MX_RECORD_PREDICATE);
+    return withRule(
+        REQUIRE_VALID_MX_RECORD_PREDICATE,
+        FailureReason.INVALID_MX_RECORD);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#requireValidMXRecord(Email, int, int)} rule.
-   * Email addresses that have a domain without a valid MX record will fail validation.
+   * Email addresses that have a domain without a valid MX record will fail validation with
+   * {@link FailureReason#INVALID_MX_RECORD}.
    *
    * <p>This method allows you to customize the timeout and retries for performing DNS lookups.
    * The initial timeout is supplied in milliseconds, and the number of retries indicate how many
@@ -224,22 +289,25 @@ public EmailValidator requireValidMXRecord() {
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator requireValidMXRecord(int initialTimeout, int numRetries) {
-    return withRule(email ->
-        ValidationRules.requireValidMXRecord(email, initialTimeout, numRetries));
+    return withRule(
+        email -> ValidationRules.requireValidMXRecord(email, initialTimeout, numRetries),
+        FailureReason.INVALID_MX_RECORD);
   }
 
   /**
    * Create a new {@code EmailValidator} with all rules from the current instance and the
    * {@link ValidationRules#requireAscii(Email)} rule.
    * Email addresses that contain characters other than those in the ASCII charset will fail
-   * validation.
+   * validation with {@link FailureReason#NON_ASCII_ADDRESS}
    *
    * <p>For example, {@code "jø[email protected]"} would be invalid.
    *
    * @return the new {@code EmailValidator} instance
    */
   public EmailValidator requireAscii() {
-    return withRule(REQUIRE_ASCII_PREDICATE);
+    return withRule(
+        REQUIRE_ASCII_PREDICATE,
+        FailureReason.NON_ASCII_ADDRESS);
   }
 
   /**
@@ -252,7 +320,7 @@ public EmailValidator requireAscii() {
    */
   public boolean isValid(String email) {
     return JMail.tryParse(email)
-        .filter(this::passesPredicates)
+        .filter(e -> !testPredicates(e).isPresent())
         .isPresent();
   }
 
@@ -298,12 +366,10 @@ public EmailValidationResult validate(String email) {
     // If failed basic validation, just return it
     if (!result.getEmail().isPresent()) return result;
 
-    // If the address fails custom validation, return failure
-    if (!passesPredicates(result.getEmail().get())) {
-      return EmailValidationResult.failure(FailureReason.FAILED_CUSTOM_VALIDATION);
-    }
-
-    return result;
+    // If the address fails custom validation, return failure, otherwise return the original result
+    return testPredicates(result.getEmail().get())
+        .map(EmailValidationResult::failure)
+        .orElse(result);
   }
 
   /**
@@ -316,7 +382,7 @@ public EmailValidationResult validate(String email) {
    *         is invalid according to all registered validation rules
    */
   public Optional<Email> tryParse(String email) {
-    return JMail.tryParse(email).filter(this::passesPredicates);
+    return JMail.tryParse(email).filter(e -> !testPredicates(e).isPresent());
   }
 
   /**
@@ -325,9 +391,11 @@ public Optional<Email> tryParse(String email) {
    * @param email the email address to test
    * @return true if it passes the predicates, false otherwise
    */
-  private boolean passesPredicates(Email email) {
-    return validationPredicates.stream()
-        .allMatch(rule -> rule.test(email));
+  private Optional<FailureReason> testPredicates(Email email) {
+    return validationPredicates.entrySet().stream()
+        .filter(entry -> !entry.getKey().test(email))
+        .findFirst()
+        .map(Map.Entry::getValue);
   }
 
   @Override