WIP. Completely moved defaults/overrides to Mailer level in EmailGovernanceImpl. Added option to Email to completely ignore defaults/overrides when sending emails (or resolving it manually using a EmailGovernance instance). Added builder api to build email as normal but also to build an email resolving defaults/overrides right away. Added temporary type EmailWithDefaultsAndOverridesApplied to make sure during this refactoring at which point we internally completed the email (this will be removed again). Moved some non-user Email api to new sub class InternalEmail

Author: bbottema

modules/cli-module/src/main/java/org/simplejavamail/internal/clisupport/CliCommandLineConsumerResultHandler.java

@@ -50,7 +50,7 @@ private static void processCliTestConnection(List<CliReceivedOptionData> receive
 	private static void processCliValidate(List<CliReceivedOptionData> receivedOptions) {
 		final EmailPopulatingBuilder emailBuilder = invokeBuilderApi(receivedOptions, CliBuilderApiType.EMAIL, new EmailStartingBuilderImpl());
 		final MailerGenericBuilder<?> mailerBuilder = invokeBuilderApi(receivedOptions, CliBuilderApiType.MAILER, new MailerRegularBuilderImpl());
-		mailerBuilder.buildMailer().validate(emailBuilder.buildEmail());
+		mailerBuilder.buildMailer().validate(emailBuilder.buildEmailCompletedWithDefaultsAndOverrides());
 	}
 
 	@SuppressWarnings("unchecked")

modules/core-module/src/main/java/org/simplejavamail/api/email/ContentTransferEncoding.java

@@ -40,4 +40,8 @@ public static ContentTransferEncoding byEncoder(@NotNull final String encoder) {
 	public String toString() {
 		return encoder;
 	}
-}
+
+	public static ContentTransferEncoding getDefault() {
+		return QUOTED_PRINTABLE;
+	}
+}

modules/core-module/src/main/java/org/simplejavamail/api/email/Email.java

@@ -41,6 +41,16 @@ public class Email implements Serializable {
 
 	private static final long serialVersionUID = 1234567L;
 
+	/**
+	 * @see EmailPopulatingBuilder#ignoringDefaults(boolean)
+	 */
+	private final boolean ignoreDefaults;
+
+	/**
+	 * @see EmailPopulatingBuilder#ignoringOverrides(boolean)
+	 */
+	private final boolean ignoreOverrides;
+
 	/**
 	 * @see EmailPopulatingBuilder#dontApplyDefaultValueFor(EmailProperty...)
 	 */
@@ -54,7 +64,7 @@ public class Email implements Serializable {
 	/**
 	 * @see EmailPopulatingBuilder#fixingMessageId(String)
 	 */
-	private String id;
+	protected String id;
 
 	/**
 	 * @see EmailPopulatingBuilder#from(Recipient)
@@ -94,7 +104,7 @@ public class Email implements Serializable {
 	/**
 	 * @see EmailPopulatingBuilder#withContentTransferEncoding(ContentTransferEncoding)
 	 */
-	@NotNull
+	@Nullable
 	private final ContentTransferEncoding contentTransferEncoding;
 
 	/**
@@ -200,9 +210,9 @@ public class Email implements Serializable {
 	private final OriginalSmimeDetails originalSmimeDetails;
 
 	/**
-	 * @see Email#wasMergedWithSmimeSignedMessage()
+	 * @see "ExtendedEmail.wasMergedWithSmimeSignedMessage()"
 	 */
-	private final boolean wasMergedWithSmimeSignedMessage;
+	protected final boolean wasMergedWithSmimeSignedMessage;
 
 	/**
 	 * @see EmailPopulatingBuilder#fixingSentDate(Date)
@@ -218,6 +228,8 @@ public class Email implements Serializable {
 	public Email(@NotNull final EmailPopulatingBuilder builder) {
 		checkNonEmptyArgument(builder, "builder");
 
+		ignoreDefaults = builder.isIgnoreDefaults();
+		ignoreOverrides = builder.isIgnoreOverrides();
 		propertiesNotToApplyDefaultValueFor = builder.getPropertiesNotToApplyDefaultValueFor();
 		propertiesNotToApplyOverrideValueFor = builder.getPropertiesNotToApplyOverrideValueFor();
 		smimeSignedEmail = builder.getSmimeSignedEmail();
@@ -287,25 +299,6 @@ public Email(@NotNull final EmailPopulatingBuilder builder) {
 		this.dkimConfig = builder.getDkimConfig();
 	}
 
-	/**
-	 * @deprecated Don't use this method, refer to {@link EmailPopulatingBuilder#fixingMessageId(String)} instead. This method is used internally to
-	 * update the message id once a mail has been sent.
-	 */
-	@Deprecated
-	public void internalSetId(@NotNull final String id) {
-		this.id = id;
-	}
-
-	/**
-	 * @deprecated Don't use this method. This method is used internally when using the builder API to copy an email that
-	 * contains an S/MIME signed message. Without this method, we don't know if the copy should also be merged to match the
-	 * copied email.
-	 */
-	@Deprecated
-	public boolean wasMergedWithSmimeSignedMessage() {
-		return wasMergedWithSmimeSignedMessage;
-	}
-
 	@SuppressWarnings("SameReturnValue")
 	@Override
 	public int hashCode() {
@@ -328,7 +321,7 @@ public String toString() {
 				",\n\ttext='" + text + '\'' +
 				",\n\ttextHTML='" + textHTML + '\'' +
 				",\n\ttextCalendar='" + format("%s (method: %s)", textCalendar, calendarMethod) + '\'' +
-				",\n\tcontentTransferEncoding='" + contentTransferEncoding + '\'' +
+				",\n\tcontentTransferEncoding='" + (contentTransferEncoding != null ? contentTransferEncoding : ContentTransferEncoding.getDefault()) + '\'' +
 				",\n\tsubject='" + subject + '\'' +
 				",\n\trecipients=" + recipients);
 		if (!MiscUtil.valueNullOrEmpty(dkimConfig)) {
@@ -388,6 +381,20 @@ private String formatDate(@Nullable Date date) {
 		return sdf.format(date);
 	}
 
+	/**
+	 * @see EmailPopulatingBuilder#ignoringDefaults(boolean)
+	 */
+	public boolean isIgnoreDefaults() {
+		return ignoreDefaults;
+	}
+
+	/**
+	 * @see EmailPopulatingBuilder#ignoringOverrides(boolean)
+	 */
+	public boolean isIgnoreOverrides() {
+		return ignoreOverrides;
+	}
+
 	/**
 	 * @see EmailPopulatingBuilder#dontApplyDefaultValueFor(EmailProperty...)
 	 */
@@ -647,7 +654,7 @@ public Date getSentDate() {
 	/**
 	 * @see EmailPopulatingBuilder#withContentTransferEncoding(ContentTransferEncoding)
 	 */
-	@NotNull
+	@Nullable
 	public ContentTransferEncoding getContentTransferEncoding() {
 		return contentTransferEncoding;
 	}

modules/core-module/src/main/java/org/simplejavamail/api/email/EmailPopulatingBuilder.java

@@ -10,6 +10,8 @@
 import org.simplejavamail.api.email.config.DkimConfig;
 import org.simplejavamail.api.internal.clisupport.model.Cli;
 import org.simplejavamail.api.internal.clisupport.model.CliBuilderApiType;
+import org.simplejavamail.api.mailer.Mailer;
+import org.simplejavamail.api.mailer.config.EmailGovernance;
 import org.simplejavamail.api.mailer.config.Pkcs12Config;
 import org.simplejavamail.internal.config.EmailProperty;
 
@@ -44,11 +46,61 @@ public interface EmailPopulatingBuilder {
 	Pattern IMG_SRC_PATTERN = compile("(?<imageTagStart><[Ii][Mm][Gg]\\s*[^>]*?\\s+[Ss][Rr][Cc]\\s*=\\s*[\"'])(?<src>[^\"']+?)(?<imageSrcEnd>[\"'])");
 
 	/**
-	 * Validated DKIM values and then delegates to {@link Email#Email(EmailPopulatingBuilder)} with <code>this</code> as argument.
+	 * Validated DKIM values and then delegates to {@link Email#Email(EmailPopulatingBuilder)} with <code>this</code> as argument. This results in an Email instance with
+	 * just the values set on this builder by the user. <strong>This is the regular use case and the common way to send emails using a {@link Mailer} instance.</strong>
+	 * <p>
+	 * If you don't have a Mailer instance or you just want to call helper methods that only accept an {@link EmailWithDefaultsAndOverridesApplied}, there are two ways
+	 * to complete this Email with defaults and overrides that you may have configured as (system) properties (files):
+	 * <ol>
+	 *     <li>Construct a new {@code EmailGovernanceImpl} or use {@code EmailGovernanceImpl.NO_GOVERNANCE()}, and then use {@link EmailGovernance#produceEmailApplyingDefaultsAndOverrides(Email)}</li>
+	 *     <li>Don't use {@link #buildEmail()}, but use {@link #buildEmailCompletedWithDefaultsAndOverrides()} or {@link #buildEmailCompletedWithDefaultsAndOverrides(EmailGovernance)} instead</li>
+	 * </ol>
+	 * It depends on whether you like fine-grained control over email governance (validation, max email size, defaults, overrides, etc.) or not.
+	 *
+	 * @see #buildEmailCompletedWithDefaultsAndOverrides(EmailGovernance)
 	 */
+	@SuppressWarnings("JavadocDeclaration")
 	@Cli.ExcludeApi(reason = "This API is specifically for Java use")
 	Email buildEmail();
 
+	/**
+	 * Delegates to {@link #buildEmailCompletedWithDefaultsAndOverrides(EmailGovernance)} with an empty default email governance, which
+	 * will still apply default config (System) properties (files).
+	 */
+	@Cli.ExcludeApi(reason = "This API is specifically for Java use")
+	EmailWithDefaultsAndOverridesApplied buildEmailCompletedWithDefaultsAndOverrides();
+
+	/**
+	 * Like {@link #buildEmail()}, but returning the final email version right away. Useful if you don't use a Mailer which works with email governance,
+	 * or just want to call a helper method that only accepts {@link EmailWithDefaultsAndOverridesApplied}. For regular cases of just sending with a {@link Mailer}, this
+	 * completion stage happens automatically when converting to MimeMessage. In that case use {@link #buildEmail()} instead.
+	 * <p>
+	 * Why not always apply defaults and overrides? Because it would be a waste of resources to do so, especially when you are sending multiple emails resuing a mailer instance.
+	 * Another use case is that when using a server cluster with the batch-module (multiple mailer instances), defaults set during sending ensure that the defaults set for a
+	 * specific mailer are used. This is sometimes important if an SMTP server needs a specific sender address, or if you want to use a specific DKIM signature bound to that server.
+	 *
+	 * @param emailGovernance The email governance to use for this email. It determines which default values and overrides to apply, what the maximum
+	 *                           email size is, etc.
+	 */
+	@Cli.ExcludeApi(reason = "This API is specifically for Java use")
+	EmailWithDefaultsAndOverridesApplied buildEmailCompletedWithDefaultsAndOverrides(@NotNull EmailGovernance emailGovernance);
+
+	/**
+	 * Indicates that when the email is sent, no default values whatsoever should be applied to the email.
+	 *
+	 * @see #dontApplyDefaultValueFor(EmailProperty...)
+	 * @see org.simplejavamail.api.mailer.MailerRegularBuilder#withEmailDefaults(Email)
+	 */
+	EmailPopulatingBuilder ignoringDefaults(boolean ignoreDefaults);
+
+	/**
+	 * Indicates that when the email is sent, no override values whatsoever should be applied to the email.
+	 *
+	 * @see #dontApplyOverrideValueFor(EmailProperty...)
+	 * @see org.simplejavamail.api.mailer.MailerRegularBuilder#withEmailOverrides(Email)
+	 */
+	EmailPopulatingBuilder ignoringOverrides(boolean ignoreDefaults);
+
 	/**
 	 * Allows you to prevent a property to be configured with default values. This might be useful if you have defined defaults (either through (system) properties,
 	 * config files, or on mailer level on the {@link org.simplejavamail.api.mailer.config.EmailGovernance}), but for a specific case or under certain conditions
@@ -1536,6 +1588,16 @@ public interface EmailPopulatingBuilder {
 	 */
 	EmailPopulatingBuilder clearSMIMESignedAttachmentMergingBehavior();
 
+	/**
+	 * @see #ignoringDefaults(boolean)
+	 */
+	boolean isIgnoreDefaults();
+
+	/**
+	 * @see #ignoringOverrides(boolean)
+	 */
+	boolean isIgnoreOverrides();
+
 	/**
 	 * @see #dontApplyDefaultValueFor(EmailProperty...)
 	 */
@@ -1600,6 +1662,7 @@ public interface EmailPopulatingBuilder {
 	 * @see #withContentTransferEncoding(ContentTransferEncoding)
 	 * @see #clearContentTransferEncoding()
 	 */
+	@Nullable
 	ContentTransferEncoding getContentTransferEncoding();
 
 	/**

modules/core-module/src/main/java/org/simplejavamail/api/email/EmailStartingBuilder.java

@@ -35,17 +35,30 @@ public interface EmailStartingBuilder {
 	 */
 	String DEFAULT_QUOTING_MARKUP = "<blockquote style=\"color: gray; border-left: 1px solid #4f4f4f; padding-left: " +
 			"1cm\">%s</blockquote>";
-	
+
 	/**
 	 * Configures this builder to create an email ignoring the all defaults from (System) properties, config files or defaults email on
-	 * Mailer level in the {@link org.simplejavamail.api.mailer.config.EmailGovernance}.
+	 * Mailer level in the {@link org.simplejavamail.api.mailer.config.EmailGovernance}. You can make individual exceptions with
+	 * 	 * {@link EmailPopulatingBuilder#dontApplyDefaultValueFor(EmailProperty...)}
 	 * <br>
 	 * <strong>Note:</strong> This is irrelevant for Email instances used to set on {@link org.simplejavamail.api.mailer.config.EmailGovernance}
 	 * as defaults or overrides reference.
 	 *
 	 * @see EmailPopulatingBuilder#dontApplyDefaultValueFor(EmailProperty...)
 	 */
 	EmailStartingBuilder ignoringDefaults();
+
+	/**
+	 * Configures this builder to create an email ignoring the all overrides from (System) properties, config files or defaults email on
+	 * Mailer level in the {@link org.simplejavamail.api.mailer.config.EmailGovernance}. You can make individual exceptions with
+	 * {@link EmailPopulatingBuilder#dontApplyOverrideValueFor(EmailProperty...)}
+	 * <br>
+	 * <strong>Note:</strong> This is irrelevant for Email instances used to set on {@link org.simplejavamail.api.mailer.config.EmailGovernance}
+	 * as defaults or overrides reference.
+	 *
+	 * @see EmailPopulatingBuilder#dontApplyOverrideValueFor(EmailProperty...)
+	 */
+	EmailStartingBuilder ignoringOverrides();
 
 	/**
 	 * Most common use case for creating a new email. Starts with an empty email, populated with defaults when set through config properties (if

modules/core-module/src/main/java/org/simplejavamail/api/email/EmailWithDefaultsAndOverridesApplied.java

@@ -0,0 +1,20 @@
+package org.simplejavamail.api.email;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.experimental.Delegate;
+import org.jetbrains.annotations.NotNull;
+
+@RequiredArgsConstructor
+@Getter
+// FIXME temporary workaround to make sure we update all the calls that require a final Email, with a fcall to EmailGovernance.produceFinalEmail() first
+@SuppressFBWarnings("EQ_CHECK_FOR_OPERAND_NOT_COMPATIBLE_WI")
+public class EmailWithDefaultsAndOverridesApplied {
+    @Delegate
+    @NotNull Email delegate;
+
+    public int hashCode() {
+        return 0;
+    }
+}

modules/core-module/src/main/java/org/simplejavamail/api/email/config/DkimConfig.java

@@ -1,5 +1,6 @@
 package org.simplejavamail.api.email.config;
 
+import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.ToString;
 import org.jetbrains.annotations.Nullable;
@@ -10,7 +11,6 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.Serializable;
-import java.util.Arrays;
 import java.util.HashSet;
 import java.util.Set;
 
@@ -25,6 +25,7 @@
  */
 @ToString(exclude = "dkimPrivateKeyData")
 @Getter
+@EqualsAndHashCode
 public class DkimConfig implements Serializable {
 
 	private static final long serialVersionUID = 1234567L;

modules/core-module/src/main/java/org/simplejavamail/api/mailer/CustomMailer.java

@@ -3,7 +3,7 @@
 import jakarta.mail.Session;
 import jakarta.mail.internet.MimeMessage;
 import org.jetbrains.annotations.NotNull;
-import org.simplejavamail.api.email.Email;
+import org.simplejavamail.api.email.EmailWithDefaultsAndOverridesApplied;
 import org.simplejavamail.api.mailer.config.OperationalConfig;
 
 /**
@@ -20,5 +20,5 @@
  */
 public interface CustomMailer {
 	void testConnection(@NotNull OperationalConfig operationalConfig, @NotNull Session session);
-	void sendMessage(@NotNull OperationalConfig operationalConfig, @NotNull Session session, @NotNull Email email, @NotNull MimeMessage message);
+	void sendMessage(@NotNull OperationalConfig operationalConfig, @NotNull Session session, @NotNull EmailWithDefaultsAndOverridesApplied email, @NotNull MimeMessage message);
 }

modules/core-module/src/main/java/org/simplejavamail/api/mailer/Mailer.java

@@ -7,6 +7,7 @@
 import org.jetbrains.annotations.Nullable;
 import org.simplejavamail.MailException;
 import org.simplejavamail.api.email.Email;
+import org.simplejavamail.api.email.EmailWithDefaultsAndOverridesApplied;
 import org.simplejavamail.api.mailer.config.EmailGovernance;
 import org.simplejavamail.api.mailer.config.OperationalConfig;
 import org.simplejavamail.api.mailer.config.ProxyConfig;
@@ -62,7 +63,9 @@ public interface Mailer {
 	@NotNull CompletableFuture<Void> sendMail(Email email);
 
 	/**
-	 * Processes an {@link Email} instance into a completely configured {@link Message}.
+	 * Processes an {@link Email} instance into a completely configured {@link Message}. First, it will apply all defaults and overrides to the email
+	 * instance using {@link EmailGovernance#produceEmailApplyingDefaultsAndOverrides(Email)} . Then it will validate the email. Finally, it will process
+	 * the email into a JavaMail {@link Message} object.
 	 * <p>
 	 * Sends the JavaMail {@link Message} object using {@link Session#getTransport()}. It will call {@link Transport#connect()} assuming all
 	 * connection details have been configured in the provided {@link Session} instance and finally {@link Transport#sendMessage(Message,
@@ -83,7 +86,7 @@ public interface Mailer {
 	 * @return A {@link CompletableFuture} that is completed immediately if not <em>async</em>.
 	 * @throws MailException Can be thrown if an email isn't validating correctly, or some other problem occurs during connection, sending etc.
 	 * @see java.util.concurrent.Executors#newFixedThreadPool(int)
-	 * @see #validate(Email)
+	 * @see #validate(EmailWithDefaultsAndOverridesApplied)
 	 */
 	@NotNull CompletableFuture<Void> sendMail(Email email, @SuppressWarnings("SameParameterValue") boolean async);
 
@@ -93,10 +96,10 @@ public interface Mailer {
 	 * <p>
 	 * It also checks for illegal characters that would facilitate injection attacks:
 	 * <ul>
-	 * <li>http://www.cakesolutions.net/teamblogs/2008/05/08/email-header-injection-security</li>
-	 * <li>https://security.stackexchange.com/a/54100/110048</li>
-	 * <li>https://www.owasp.org/index.php/Testing_for_IMAP/SMTP_Injection_(OTG-INPVAL-011)</li>
-	 * <li>http://cwe.mitre.org/data/definitions/93.html</li>
+	 * <li><a href="http://www.cakesolutions.net/teamblogs/2008/05/08/email-header-injection-security">http://www.cakesolutions.net/teamblogs/2008/05/08/email-header-injection-security</a></li>
+	 * <li><a href="https://security.stackexchange.com/a/54100/110048">https://security.stackexchange.com/a/54100/110048</a></li>
+	 * <li><a href="https://www.owasp.org/index.php/Testing_for_IMAP/SMTP_Injection_(OTG-INPVAL-011)">https://www.owasp.org/index.php/Testing_for_IMAP/SMTP_Injection_(OTG-INPVAL-011)</a></li>
+	 * <li><a href="http://cwe.mitre.org/data/definitions/93.html">http://cwe.mitre.org/data/definitions/93.html</a></li>
 	 * </ul>
 	 *
 	 * @param email The email that needs to be configured correctly.
@@ -106,7 +109,7 @@ public interface Mailer {
 	 * @see com.sanctionco.jmail.EmailValidator
 	 */
 	@SuppressWarnings({"SameReturnValue" })
-	boolean validate(Email email) throws MailException;
+	boolean validate(EmailWithDefaultsAndOverridesApplied email) throws MailException;
 
 	/**
 	 * Shuts down the connection pool associated with this {@link Mailer} instance and closes remaining open connections. Waits until all connections still in use become available again