new mail filter to decide mail sending per instance

src/main/java/net/sargue/mailgun/Configuration.java

@@ -25,6 +25,7 @@ public class Configuration {
     private MultivaluedMap<String,String> defaultParameters = new MultivaluedHashMap<>();
 
     private MailRequestCallbackFactory mailRequestCallbackFactory = null;
+    private MailSendFilter mailSendFilter = defaultFilter;
     private List<Converter<?>> converters =
         Collections.synchronizedList(new ArrayList<Converter<?>>());
 
@@ -36,6 +37,13 @@ public String toString(Object value) {
             }
         };
 
+    private static final MailSendFilter defaultFilter = new MailSendFilter() {
+        @Override
+        public boolean filter(Mail mail) {
+            return true;
+        }
+    };
+
     private static final class Converter<T> {
         private Class<T> classOfConverter;
         private ContentConverter<? super T> contentConverter;
@@ -72,12 +80,15 @@ public Configuration(String domain, String apiKey, String from) {
      * Creates a copy of this configuration.
      *
      * @return a copy of this configuration
+     * @deprecated it's not clear what a 'copy' is so this method will be removed
      */
     public Configuration copy() {
         Configuration copy = new Configuration();
         copy.apiUrl = apiUrl;
         copy.domain = domain;
         copy.apiKey = apiKey;
+        copy.mailRequestCallbackFactory = mailRequestCallbackFactory;
+        copy.mailSendFilter = mailSendFilter;
         //noinspection Convert2Diamond
         copy.defaultParameters = new MultivaluedHashMap<String,String>(defaultParameters);
         copy.converters.addAll(converters);
@@ -203,6 +214,21 @@ public Configuration unregisterMailRequestCallbackFactory() {
         return this;
     }
 
+    /**
+     * Registers a filter to decide if a mail should be sent or not.
+     *
+     * This filter acts upon invokation of the different send methods in the
+     * {@link Mail} class preventing the actual request to Mailgun if the
+     * filter returns false.
+     *
+     * @param mailSendFilter the filter to apply to all messages
+     * @return this configuration
+     */
+    public Configuration registerMailSendFilter(MailSendFilter mailSendFilter) {
+        this.mailSendFilter = mailSendFilter;
+        return this;
+    }
+
     /**
      * Returns the configured Mailgun domain.
      *
@@ -260,6 +286,15 @@ public MailRequestCallbackFactory mailRequestCallbackFactory() {
         return mailRequestCallbackFactory;
     }
 
+    /**
+     * Retrieves this configuration's filter.
+     *
+     * @return this configuration's filter
+     */
+    public MailSendFilter mailSendFilter() {
+        return mailSendFilter;
+    }
+
     /**
      * Registers a converter.
      *

src/main/java/net/sargue/mailgun/Mail.java

@@ -63,9 +63,11 @@ public static MailBuilder using(Configuration configuration) {
      * <strong>blocking</strong> method so it will return upon request
      * completion.
      *
-     * @return the response from the Mailgun service
+     * @return the response from the Mailgun service or null if the message
+     *         is not sent (filtered by {@link MailSendFilter}
      */
     public Response send() {
+        if (!configuration.mailSendFilter().filter(this)) return null;
         prepareSend();
         return new Response(request().post(entity()));
     }
@@ -80,6 +82,7 @@ public Response send() {
      * @param callback the callback to be invoked upon completion or failure
      */
     public void sendAsync(final MailRequestCallback callback) {
+        if (!configuration.mailSendFilter().filter(this)) return;
         prepareSend();
         request()
                 .async()
@@ -105,6 +108,7 @@ public void failed(Throwable throwable) {
      * {@link #sendAsync(MailRequestCallback)} instead.
      */
     public void sendAsync() {
+        if (!configuration.mailSendFilter().filter(this)) return;
         MailRequestCallbackFactory factory = configuration.mailRequestCallbackFactory();
         if (factory == null) {
             prepareSend();

src/main/java/net/sargue/mailgun/MailSendFilter.java

@@ -0,0 +1,21 @@
+package net.sargue.mailgun;
+
+/**
+ * A filter to decide if a mail should be sent or not.
+ *
+ * This filter acts upon invokation of the different send methods in the
+ * {@link Mail} class preventing the actual request to Mailgun if the
+ * filter returns false.
+ *
+ * One implementation of this filter can be registered on a {@link Configuration}.
+ */
+public interface MailSendFilter {
+
+    /**
+     * Decide if this mail should be sent.
+     *
+     * @param mail the mail to check
+     * @return true if the process of sending the email should continue
+     */
+    boolean filter(Mail mail);
+}

src/test/java/net/sargue/mailgun/test/BasicTests.java

@@ -471,4 +471,26 @@ public void responsePayloadTest() {
 
         assertEquals(responseMessage, response.responseMessage());
     }
+
+    @Test
+    public void testFilteredSend() {
+        final AtomicBoolean filterExecuted = new AtomicBoolean(false);
+
+        Configuration configuration = new Configuration()
+            .registerMailSendFilter(new MailSendFilter() {
+                @Override
+                public boolean filter(Mail mail) {
+                    filterExecuted.set(true);
+                    return false;
+                }
+            });
+
+        Response response = MailBuilder
+            .using(configuration)
+            .build()
+            .send();
+
+        assertNull(response);
+        assertTrue(filterExecuted.get());
+    }
 }

src/test/java/net/sargue/mailgun/test/ConfigurationTests.java

@@ -130,4 +130,25 @@ public MailRequestCallback create(Mail mail) {
 
         assertNull(configuration.mailRequestCallbackFactory());
     }
+
+    @Test
+    public void testDefaultFilter() {
+        Configuration configuration = new Configuration();
+
+        assertTrue(configuration.mailSendFilter().filter(null));
+    }
+
+    @Test
+    public void testRegisterFilter() {
+        MailSendFilter filter = new MailSendFilter() {
+            @Override
+            public boolean filter(Mail mail) {
+                return false;
+            }
+        };
+        Configuration configuration = new Configuration()
+            .registerMailSendFilter(filter);
+
+        assertSame(filter, configuration.mailSendFilter());
+    }
 }