Make stripQuotes default behavior

Author: RohanNagar

CHANGELOG.md

@@ -4,12 +4,24 @@
 
 ### Breaking Changes
 
-- The `jmail.normalize.strip.quotes` JVM system property no longer does anything.
-  Use `NormalizationOptionsBuilder#stripQuotes()` instead.
+- By default, `Email#normalized` now lowercases the email address **and** removes any extraneous quotes in the local-part of the address.
+  To revert this behavior so that it behaves the same as v1, use the following:
+  
+  ```
+  myEmailObject.normalized(
+    NormalizationOptions.builder()
+      .keepQuotes()
+      .adjustCase(CaseOption.NO_CHANGE)
+      .build());
+  ```
+
+
+- The `jmail.normalize.strip.quotes` JVM system property no longer does anything. Quotes are stripped by default now.
+  If you need to disable quote stripping, use `NormalizationOptionsBuilder#keepQuotes()`.
 
 
 - Removed `Email#normalized(boolean)` method which allowed for a normalized email with stripped quotes.
-  Use `myEmail.normalized(NormalizationOptions.builder().stripQuotes().build())` instead.
+  Quotes are stripped by default now. If you need to disable quote stripping, use `NormalizationOptionsBuilder#keepQuotes()`.
 
 
 - `FailureReason` was switched from an enum to a class in order to support custom failure reasons, so you cannot
@@ -18,12 +30,14 @@
 
 - `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`.
+  they ended the email address with a comment. This `FailureReason` was potentially misleading, for example if you
+  enabled `requireTopLevelDomain()` on your `EmailValidator`. Note that the `MISSING_TOP_LEVEL_DOMAIN` failure reason
+  is now used properly: if you use the rule `requireTopLevelDomain()`, any address that is missing the TLD will give
+  that failure reason.
 
 
 - 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`
+  `disallowIpDomain()` or `requireValidMXRecord()`) no longer return a generic `FailureReason.FAILED_CUSTOM_VALIDATION`
   in the `EmailValidationResult`. Instead, it returns a more specific `FailureReason` depending on the rule. 
 
 ### FailureReason Improvements
@@ -33,7 +47,17 @@
 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.
+`requireValidMXRecord()`) now return more specific and useful reasons (such as `CONTAINS_IP_DOMAIN` or
+`INVALID_MX_RECORD`).
+
+```
+EmailValidator validator = JMail.strictValidator()
+  .requireOnlyTopLevelDomains(TopLevelDomain.DOT_COM);
+  
+EmailValidationResult result = validator.validate("[email protected]");
+
+assertEquals(FailureReason.INVALID_TOP_LEVEL_DOMAIN, result.getFailureReason());
+```
 
 #### Option to provide FailureReason for custom rules
 
@@ -43,6 +67,17 @@ to your `EmailValidator`. Use the new `withRule(Predicate<Email>, FailureReason)
 of your custom rules. If no failure reason is supplied, then the rule will default to the
 `FailureReason.FAILED_CUSTOM_VALIDATION` reason.
 
+```
+FailureReason nonGmailFailure = new FailureReason("NON_GMAIL_ADDRESS");
+
+EmailValidator validator = JMail.strictValidator()
+  .withRule(e -> e.domain.startsWith("gmail"), nonGmailFailure);
+  
+EmailValidationResult result = validator.validate("[email protected]");
+
+assertEquals(nonGmailFailure, result.getFailureReason());
+```
+
 ### Email Address Normalization Improvements
 
 #### New Normalization Methods

src/main/java/com/sanctionco/jmail/normalization/NormalizationOptionsBuilder.java

@@ -9,7 +9,7 @@
  */
 public class NormalizationOptionsBuilder {
   CaseOption caseOption = CaseOption.LOWERCASE;
-  boolean stripQuotes = false;
+  boolean stripQuotes = true;
   boolean removeDots = false;
   boolean removeSubAddress = false;
   String subAddressSeparator = "+";
@@ -20,14 +20,14 @@ public class NormalizationOptionsBuilder {
   }
 
   /**
-   * <p>Strip all unnecessary quotes contained in the local-part of the email address.</p>
-   *
-   * <p>The default normalization behavior does <strong>not</strong> strip quotes.</p>
+   * By default, normalization strips all unnecessary quotes contained in the local-part
+   * of the email address. This method will tell normalization to <strong>keep</strong> those
+   * extraneous quotes.
    *
    * @return this
    */
-  public NormalizationOptionsBuilder stripQuotes() {
-    this.stripQuotes = true;
+  public NormalizationOptionsBuilder keepQuotes() {
+    this.stripQuotes = false;
     return this;
   }
 

src/test/java/com/sanctionco/jmail/EmailTest.java

@@ -21,6 +21,7 @@
 class EmailTest {
   private static final NormalizationOptions MINIMAL_NORMALIZATION = NormalizationOptions
       .builder()
+      .keepQuotes()
       .adjustCase(CaseOption.NO_CHANGE)
       .build();
 
@@ -61,11 +62,11 @@ void ensureNormalizedIsCorrectForLongComment() {
   @ParameterizedTest(name = "{0}")
   @MethodSource("provideValidForStripQuotes")
   void ensureNormalizedStripsQuotes(String address, String expected) {
+    // Strip quotes is default
     assertThat(Email.of(address))
           .isPresent().get()
           .returns(expected, email -> email.normalized(NormalizationOptions.builder()
               .adjustCase(CaseOption.NO_CHANGE)
-              .stripQuotes()
               .build()));
 
     // Check that nothing happens when stripQuotes is false
@@ -178,7 +179,6 @@ void ensureNormalizedStripsQuotesForAllValidAddresses(String address) {
             validated.normalized(MINIMAL_NORMALIZATION),
             email -> email.normalized(NormalizationOptions.builder()
                 .adjustCase(CaseOption.NO_CHANGE)
-                .stripQuotes()
                 .build()));
   }
 
@@ -212,7 +212,6 @@ void ensureNormalizedDoesNotStripQuotesIfInvalid(String address) {
         .isPresent().get()
         .returns(address, email -> email.normalized(NormalizationOptions.builder()
             .adjustCase(CaseOption.NO_CHANGE)
-            .stripQuotes()
             .build()));
   }
 

src/test/java/com/sanctionco/jmail/EmailValidatorTest.java

@@ -276,6 +276,13 @@ void invalidatesCorrectlyWithCustomStringFailureReason(String email) {
           JMail.validator().withRule(e -> e.domain().startsWith("test"), "MY_REASON"),
           email,
           failureReason);
+
+      EmailValidator validator = JMail.strictValidator()
+          .requireOnlyTopLevelDomains(TopLevelDomain.DOT_COM);
+
+      EmailValidationResult result = validator.validate("[email protected]");
+
+      result.getFailureReason().equals(FailureReason.INVALID_TOP_LEVEL_DOMAIN);
     }
 
     @ParameterizedTest(name = "{0}")

src/test/java/com/sanctionco/jmail/normalization/NormalizationOptionsBuilderTest.java

@@ -11,7 +11,7 @@ class NormalizationOptionsBuilderTest {
   @Test
   void ensureDefaults() {
     assertThat(NormalizationOptions.builder().build())
-        .returns(false, NormalizationOptions::shouldStripQuotes)
+        .returns(true, NormalizationOptions::shouldStripQuotes)
         .returns(CaseOption.LOWERCASE, NormalizationOptions::getCaseOption)
         .returns(false, NormalizationOptions::shouldRemoveDots)
         .returns(false, NormalizationOptions::shouldRemoveSubAddress)
@@ -25,13 +25,13 @@ void ensureValuesAreProperlySet() {
     NormalizationOptions options = NormalizationOptions.builder()
         .removeDots()
         .removeSubAddress("-")
-        .stripQuotes()
+        .keepQuotes()
         .adjustCase(CaseOption.UPPERCASE)
         .performUnicodeNormalization(Normalizer.Form.NFC)
         .build();
 
     assertThat(options)
-        .returns(true, NormalizationOptions::shouldStripQuotes)
+        .returns(false, NormalizationOptions::shouldStripQuotes)
         .returns(CaseOption.UPPERCASE, NormalizationOptions::getCaseOption)
         .returns(true, NormalizationOptions::shouldRemoveDots)
         .returns(true, NormalizationOptions::shouldRemoveSubAddress)