#246: Keep track of whether the user manually provided an executor service and if not, shut it down together with the connection pool to prevent a JVM shutdown from being blocked.

Author: bbottema

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

@@ -112,7 +112,9 @@ public interface Mailer {
 	 * 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
 	 * to deallocate them as well.
 	 * <p>
-	 * In order to shut down the whole connection pool (in case of clustering), each individual {@link Mailer} instance should be shutdown.
+	 * <strong>Note:</strong> In order to shut down the whole connection pool (in case of clustering), each individual {@link Mailer} instance should be shutdown.
+	 * <p>
+	 * <strong>Note:</strong> This does *not* shut down the executor service if it was provided by the user.
 	 * <p>
 	 * <strong>Note:</strong> this is only works in combination with the {@value org.simplejavamail.internal.modules.BatchModule#NAME}.
 	 */

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

@@ -243,6 +243,10 @@ public interface MailerGenericBuilder<T extends MailerGenericBuilder<?>> {
 	 * <strong>Note:</strong> What makes it NonJvm is that the default keepAliveTime is set to the lowest non-zero value (so 1), so that
 	 * any threads will die off as soon as possible, as not to block the JVM from shutting down.
 	 * <p>
+	 * <p>
+	 * <strong>Note:</strong> Simple Java Mail will <strong>not</strong> shut down the provided executor service, even if the connection pool is being shut down.
+	 * <em>This will block the JVM from shutting down</em>. The user is responsible for managing the provided executor's life cycle.
+	 * <p>
 	 * <strong>Note:</strong> this only works in combination with the {@value org.simplejavamail.internal.modules.BatchModule#NAME}.
 	 *
 	 * @param executorService A custom executor service (ThreadPoolExecutor), replacing the {@code NonJvmBlockingThreadPoolExecutor}.

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

@@ -109,6 +109,12 @@ public interface OperationalConfig {
 	@NotNull
 	ExecutorService getExecutorService();
 
+	/**
+	 * Indicates whether the executor service was provided by the user or internally. Used to known if Simple Java Mail should shut down the executor
+	 * when the connection pool is shut down.
+	 */
+	boolean executorServiceIsUserProvided();
+
 	/**
 	 * @see MailerGenericBuilder#withCustomMailer(CustomMailer)
 	 */

modules/simple-java-mail/src/main/java/org/simplejavamail/mailer/internal/InternalMailerBuilder.java

@@ -0,0 +1,11 @@
+package org.simplejavamail.mailer.internal;
+
+import org.simplejavamail.api.mailer.MailerGenericBuilder;
+
+/**
+ * This interface is only there to improve readability there where internal builder API is used.
+ */
+@SuppressWarnings("UnusedReturnValue")
+public interface InternalMailerBuilder<T extends MailerGenericBuilder<?>> extends MailerGenericBuilder<T> {
+	boolean isExecutorServiceUserProvided();
+}

modules/simple-java-mail/src/main/java/org/simplejavamail/mailer/internal/MailerGenericBuilderImpl.java

@@ -39,7 +39,7 @@
  * @see MailerGenericBuilder
  */
 @SuppressWarnings({"UnusedReturnValue", "unchecked"})
-abstract class MailerGenericBuilderImpl<T extends MailerGenericBuilderImpl<?>> implements MailerGenericBuilder<T> {
+abstract class MailerGenericBuilderImpl<T extends MailerGenericBuilderImpl<?>> implements InternalMailerBuilder<T> {
 
 	/**
 	 * @see MailerGenericBuilder#async()
@@ -95,6 +95,11 @@ abstract class MailerGenericBuilderImpl<T extends MailerGenericBuilderImpl<?>> i
 	@NotNull
 	private ExecutorService executorService;
 
+	/**
+	 * @see InternalMailerBuilder#isExecutorServiceUserProvided()
+	 */
+	private boolean executorServiceIsUserProvided = false;
+
 	/**
 	 * @see MailerGenericBuilder#withThreadPoolSize(Integer)
 	 */
@@ -266,6 +271,7 @@ OperationalConfig buildOperationalConfig() {
 				isTrustAllSSLHost(),
 				isVerifyingServerIdentity(),
 				getExecutorService(),
+				isExecutorServiceUserProvided(),
 				getCustomMailer());
 	}
 
@@ -376,6 +382,7 @@ public T withEmailAddressCriteria(@NotNull final EnumSet<EmailAddressCriteria> e
 	@Override
 	public T withExecutorService(@NotNull final ExecutorService executorService) {
 		this.executorService = executorService;
+		this.executorServiceIsUserProvided = true;
 		return (T) this;
 	}
 
@@ -569,6 +576,7 @@ public T resetEmailAddressCriteria() {
 	@Override
 	public T resetExecutorService() {
 		this.executorService = determineDefaultExecutorService();
+		this.executorServiceIsUserProvided = false;
 		return (T) this;
 	}
 
@@ -773,6 +781,14 @@ public ExecutorService getExecutorService() {
 		return executorService;
 	}
 
+	/**
+	 * @see InternalMailerBuilder#isExecutorServiceUserProvided()
+	 */
+	@Override
+	public boolean isExecutorServiceUserProvided() {
+		return executorServiceIsUserProvided;
+	}
+
 	/**
 	 * @see MailerGenericBuilder#getThreadPoolSize()
 	 */

modules/simple-java-mail/src/main/java/org/simplejavamail/mailer/internal/MailerImpl.java

@@ -337,6 +337,9 @@ public boolean validate(@NotNull final Email email)
 	 */
 	@Override
 	public Future<?> shutdownConnectionPool() {
+		if (!operationalConfig.executorServiceIsUserProvided()) {
+			operationalConfig.getExecutorService().shutdown();
+		}
 		return ModuleLoader.loadBatchModule().shutdownConnectionPools(session);
 	}
 

modules/simple-java-mail/src/main/java/org/simplejavamail/mailer/internal/OperationalConfigImpl.java

@@ -107,6 +107,11 @@ class OperationalConfigImpl implements OperationalConfig {
 	@NotNull
 	private final ExecutorService executorService;
 
+	/**
+	 * @see InternalMailerBuilder#isExecutorServiceUserProvided()
+	 */
+	private final boolean executorServiceIsUserProvided;
+
 	/**
 	 * @see org.simplejavamail.api.mailer.MailerGenericBuilder#withCustomMailer(CustomMailer)
 	 */
@@ -130,6 +135,7 @@ class OperationalConfigImpl implements OperationalConfig {
 			final boolean trustAllSSLHost,
 			final boolean verifyingServerIdentity,
 			@NotNull final ExecutorService executorService,
+			final boolean executorServiceIsUserProvided,
 			@Nullable final CustomMailer customMailer) {
 		this.async = async; // can be overridden when calling {@code mailer.send(async = true)}
 		this.properties = properties;
@@ -148,6 +154,7 @@ class OperationalConfigImpl implements OperationalConfig {
 		this.trustAllSSLHost = trustAllSSLHost;
 		this.verifyingServerIdentity = verifyingServerIdentity;
 		this.executorService = executorService;
+		this.executorServiceIsUserProvided = executorServiceIsUserProvided;
 		this.customMailer = customMailer;
 	}
 
@@ -297,18 +304,35 @@ public Properties getProperties() {
 		return properties;
 	}
 
+	/**
+	 * @see OperationalConfig#getClusterKey()
+	 */
 	@NotNull
 	@Override
 	public UUID getClusterKey() {
 		return clusterKey;
 	}
 
+	/**
+	 * @see OperationalConfig#getExecutorService()
+	 */
 	@NotNull
 	@Override
 	public ExecutorService getExecutorService() {
 		return executorService;
 	}
 
+	/**
+	 * @see OperationalConfig#executorServiceIsUserProvided()
+	 */
+	@Override
+	public boolean executorServiceIsUserProvided() {
+		return executorServiceIsUserProvided;
+	}
+
+	/**
+	 * @see OperationalConfig#getCustomMailer()
+	 */
 	@Nullable
 	@Override
 	public CustomMailer getCustomMailer() {