[mail] add actions with optional headers

bundles/org.smarthomej.binding.mail/README.md

@@ -2,6 +2,9 @@
 
 The Mail binding provides support for sending mails from rules.
 
+***Deprecation warning:*** The action methods `sendMail(...)` and `sendHtmlMail(...)` for sending mails with attachments are deprecated.
+Use `sendMailWithAttachment/sendMailWithAttachments` (or respective methods for HTML mails, see below).
+
 ## Supported Things
 
 There are three things: `smtp`, `imap` and `pop3` which represents respective servers.
@@ -119,17 +122,21 @@ Six different actions available:
 * `boolean success = sendMail(String recipient, String subject, String text)`
 * `boolean success = sendMailWithAttachment(String recipient, String subject, String text, String URL)`
 * `boolean success = sendMailWithAttachments(String recipient, String subject, String text, List<String> URL)`
+* `boolean success = sendComplexMail(String recipient, String subject, String text, List<String> URL, Map<String, String> headers)` 
 * `boolean success = sendHtmlMail(String recipient, String subject, String htmlContent)`
 * `boolean success = sendHtmlMailWithAttachment(String recipient, String subject, String htmlContent, String URL)`
 * `boolean success = sendHtmlMailWithAttachments(String recipient, String subject, String htmlContent, List<String> URL)`
+* `boolean success = sendHtmlMailWithAttachments(String recipient, String subject, String htmlContent, List<String> URL, Map<String, String> headers)`
 
-The `sendMail(...)` actions send a plain text mail (with attachments if supplied).
-The `sendHtmlMail(...)` actions send an HTML mail (with attachments if supplied).
+The `sendMail...(...)` actions send a plain text mail.
+The `sendHtmlMail...(...)` actions send an HTML mail.
 
-Both functions return a boolean as the result of the operation.
+All methods return a boolean as the result of the operation.
 
 `recipient` can be a single address (`mail@example.com`) or a list of addresses, concatenated by a comma (`mail@example.com, mail2@example.com`).
 
+The `sendComplexMail` and `sendComplexHtmlMail` methods allow `null` values for all parameters except the `recipient`.
+
 Since there is a separate rule action instance for each `smtp` thing, this needs to be retrieved through `getActions(scope, thingUID)`.
 The first parameter always has to be `mail` and the second is the full Thing UID of the SMTP server that should be used.
 Once this action instance is retrieved, you can invoke the action method on it.
@@ -149,9 +156,9 @@ success = mailActions.sendMail("mail1@example.com, mail2@example.com", "Test sub
 ```
 import java.util.List
 
-val List<String> attachmentUrlList = newArrayList(
+val List<String> attachmentUrlList = new ArrayList(
   "http://some.web/site/snap.jpg&param=value",
   "file:///tmp/201601011031.jpg")
 val mailActions = getActions("mail","mail:smtp:sampleserver")
-mailActions.sendHtmlMail("mail@example.com", "Test subject", "<h1>Header</h1>This is the mail content.", attachmentUrlList)
+mailActions.sendHtmlMailWithAttachments("mail@example.com", "Test subject", "<h1>Header</h1>This is the mail content.", attachmentUrlList)
 ```

bundles/org.smarthomej.binding.mail/src/main/java/org/smarthomej/binding/mail/internal/MailBuilder.java

@@ -18,7 +18,9 @@
 import java.net.URL;
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 import javax.activation.FileDataSource;
 import javax.mail.internet.AddressException;
@@ -45,6 +47,7 @@ public class MailBuilder {
     private List<InternetAddress> recipients = new ArrayList<>();
     private List<URL> attachmentURLs = new ArrayList<>();
     private List<File> attachmentFiles = new ArrayList<>();
+    private Map<String, String> headers = new HashMap<>();
     private String subject = "(no subject)";
     private String text = "";
     private String html = "";
@@ -138,6 +141,18 @@ public MailBuilder withFileAttachment(String path) {
         return this;
     }
 
+    /**
+     *
+     *
+     * @param key the key of the header
+     * @param value the value of the header
+     * @return a MailBuilder
+     */
+    public MailBuilder withHeader(String key, String value) {
+        headers.put(key, value);
+        return this;
+    }
+
     /**
      * Build the Mail
      *
@@ -194,6 +209,7 @@ public Email build() throws EmailException {
 
         mail.setTo(recipients);
         mail.setSubject(subject);
+        mail.setHeaders(headers);
 
         if (!sender.isEmpty()) {
             mail.setFrom(sender);

bundles/org.smarthomej.binding.mail/src/main/java/org/smarthomej/binding/mail/internal/action/SendMailActions.java

@@ -16,6 +16,7 @@
 import java.net.MalformedURLException;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 
 import javax.mail.internet.AddressException;
 
@@ -40,18 +41,21 @@
  */
 @ThingActionsScope(name = "mail")
 @NonNullByDefault
+@SuppressWarnings("unused")
 public class SendMailActions implements ThingActions {
 
     private final Logger logger = LoggerFactory.getLogger(SendMailActions.class);
 
     private @Nullable SMTPHandler handler;
 
+    // plain text actions
+
     @RuleAction(label = "@text/sendMessageActionLabel", description = "@text/sendMessageActionDescription")
     public @ActionOutput(name = "success", type = "java.lang.Boolean") Boolean sendMail(
             @ActionInput(name = "recipient") @Nullable String recipient,
             @ActionInput(name = "subject") @Nullable String subject,
             @ActionInput(name = "text") @Nullable String text) {
-        return sendMailWithAttachments(recipient, subject, text, List.of());
+        return sendComplexMail(recipient, subject, text, List.of(), null);
     }
 
     @RuleAction(label = "@text/sendAttachmentMessageActionLabel", description = "@text/sendAttachmentMessageActionDescription")
@@ -63,14 +67,23 @@ public class SendMailActions implements ThingActions {
         if (urlString != null) {
             urlList.add(urlString);
         }
-        return sendMailWithAttachments(recipient, subject, text, urlList);
+        return sendComplexMail(recipient, subject, text, urlList, null);
     }
 
     @RuleAction(label = "@text/sendAttachmentsMessageActionLabel", description = "@text/sendAttachmentsMessageActionDescription")
     public @ActionOutput(name = "success", type = "java.lang.Boolean") Boolean sendMailWithAttachments(
             @ActionInput(name = "recipient") @Nullable String recipient,
             @ActionInput(name = "subject") @Nullable String subject, @ActionInput(name = "text") @Nullable String text,
             @ActionInput(name = "urlList") @Nullable List<String> urlStringList) {
+        return sendComplexMail(recipient, subject, text, urlStringList, null);
+    }
+
+    @RuleAction(label = "@text/sendComplexMessageActionLabel", description = "@text/sendComplexMessageActionDescription")
+    public @ActionOutput(name = "success", type = "java.lang.Boolean") Boolean sendComplexMail(
+            @ActionInput(name = "recipient") @Nullable String recipient,
+            @ActionInput(name = "subject") @Nullable String subject, @ActionInput(name = "text") @Nullable String text,
+            @ActionInput(name = "urlList") @Nullable List<String> urlStringList,
+            @ActionInput(name = "headers") @Nullable Map<String, String> headers) {
         if (recipient == null) {
             logger.warn("Cannot send mail as recipient is missing.");
             return false;
@@ -91,6 +104,10 @@ public class SendMailActions implements ThingActions {
                 }
             }
 
+            if (headers != null) {
+                headers.forEach(builder::withHeader);
+            }
+
             final SMTPHandler handler = this.handler;
             if (handler == null) {
                 logger.info("Handler is null, cannot send mail.");
@@ -106,23 +123,42 @@ public class SendMailActions implements ThingActions {
 
     public static boolean sendMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
             @Nullable String text) {
-        return SendMailActions.sendMail(actions, recipient, subject, text, List.of());
+        return SendMailActions.sendComplexMail(actions, recipient, subject, text, List.of(), null);
     }
 
-    public static boolean sendMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
-            @Nullable String text, @Nullable String urlString) {
+    public static boolean sendMailWithAttachment(ThingActions actions, @Nullable String recipient,
+            @Nullable String subject, @Nullable String text, @Nullable String urlString) {
         List<String> urlList = new ArrayList<>();
         if (urlString != null) {
             urlList.add(urlString);
         }
-        return SendMailActions.sendMail(actions, recipient, subject, text, urlList);
+        return SendMailActions.sendComplexMail(actions, recipient, subject, text, urlList, null);
     }
 
+    @Deprecated
+    public static boolean sendMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
+            @Nullable String text, @Nullable String urlString) {
+        return SendMailActions.sendMailWithAttachment(actions, recipient, subject, text, urlString);
+    }
+
+    public static boolean sendMailWithAttachments(ThingActions actions, @Nullable String recipient,
+            @Nullable String subject, @Nullable String text, @Nullable List<String> urlStringList) {
+        return SendMailActions.sendComplexMail(actions, recipient, subject, text, urlStringList, null);
+    }
+
+    @Deprecated
     public static boolean sendMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
             @Nullable String text, @Nullable List<String> urlStringList) {
-        return ((SendMailActions) actions).sendMailWithAttachments(recipient, subject, text, urlStringList);
+        return SendMailActions.sendMailWithAttachments(actions, recipient, subject, text, urlStringList);
+    }
+
+    public static boolean sendComplexMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
+            @Nullable String text, @Nullable List<String> urlStringList, @Nullable Map<String, String> headers) {
+        return ((SendMailActions) actions).sendComplexMail(recipient, subject, text, urlStringList, headers);
     }
 
+    // HTML actions
+
     @RuleAction(label = "@text/sendHTMLMessageActionLabel", description = "@text/sendHTMLMessageActionDescription")
     public @ActionOutput(name = "success", type = "java.lang.Boolean") Boolean sendHtmlMail(
             @ActionInput(name = "recipient") @Nullable String recipient,
@@ -148,6 +184,15 @@ public static boolean sendMail(ThingActions actions, @Nullable String recipient,
             @ActionInput(name = "recipient") @Nullable String recipient,
             @ActionInput(name = "subject") @Nullable String subject, @ActionInput(name = "html") @Nullable String html,
             @ActionInput(name = "urlList") @Nullable List<String> urlStringList) {
+        return sendComplexHtmlMail(recipient, subject, html, urlStringList, null);
+    }
+
+    @RuleAction(label = "@text/sendComplexHTMLMessageActionLabel", description = "@text/sendComplexHTMLMessageActionDescription")
+    public @ActionOutput(name = "success", type = "java.lang.Boolean") Boolean sendComplexHtmlMail(
+            @ActionInput(name = "recipient") @Nullable String recipient,
+            @ActionInput(name = "subject") @Nullable String subject, @ActionInput(name = "html") @Nullable String html,
+            @ActionInput(name = "urlList") @Nullable List<String> urlStringList,
+            @ActionInput(name = "headers") @Nullable Map<String, String> headers) {
         if (recipient == null) {
             logger.warn("Cannot send mail as recipient is missing.");
             return false;
@@ -168,6 +213,10 @@ public static boolean sendMail(ThingActions actions, @Nullable String recipient,
                 }
             }
 
+            if (headers != null) {
+                headers.forEach(builder::withHeader);
+            }
+
             final SMTPHandler handler = this.handler;
             if (handler == null) {
                 logger.warn("Handler is null, cannot send mail.");
@@ -183,21 +232,39 @@ public static boolean sendMail(ThingActions actions, @Nullable String recipient,
 
     public static boolean sendHtmlMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
             @Nullable String html) {
-        return SendMailActions.sendHtmlMail(actions, recipient, subject, html, List.of());
+        return SendMailActions.sendComplexHtmlMail(actions, recipient, subject, html, List.of(), null);
     }
 
-    public static boolean sendHtmlMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
-            @Nullable String html, @Nullable String urlString) {
+    public static boolean sendHtmlMailWithAttachment(ThingActions actions, @Nullable String recipient,
+            @Nullable String subject, @Nullable String html, @Nullable String urlString) {
         List<String> urlList = new ArrayList<>();
         if (urlString != null) {
             urlList.add(urlString);
         }
-        return SendMailActions.sendHtmlMail(actions, recipient, subject, html, urlList);
+        return SendMailActions.sendComplexHtmlMail(actions, recipient, subject, html, urlList, null);
     }
 
+    @Deprecated
+    public static boolean sendHtmlMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
+            @Nullable String html, @Nullable String urlString) {
+        return SendMailActions.sendHtmlMailWithAttachment(actions, recipient, subject, html, urlString);
+    }
+
+    public static boolean sendHtmlMailWithAttachments(ThingActions actions, @Nullable String recipient,
+            @Nullable String subject, @Nullable String html, @Nullable List<String> urlStringList) {
+        return SendMailActions.sendComplexHtmlMail(actions, recipient, subject, html, urlStringList, null);
+    }
+
+    @Deprecated
     public static boolean sendHtmlMail(ThingActions actions, @Nullable String recipient, @Nullable String subject,
             @Nullable String html, @Nullable List<String> urlStringList) {
-        return ((SendMailActions) actions).sendHtmlMailWithAttachments(recipient, subject, html, urlStringList);
+        return SendMailActions.sendHtmlMailWithAttachments(actions, recipient, subject, html, urlStringList);
+    }
+
+    public static boolean sendComplexHtmlMail(ThingActions actions, @Nullable String recipient,
+            @Nullable String subject, @Nullable String html, @Nullable List<String> urlStringList,
+            @Nullable Map<String, String> headers) {
+        return ((SendMailActions) actions).sendComplexHtmlMail(recipient, subject, html, urlStringList, headers);
     }
 
     @Override

bundles/org.smarthomej.binding.mail/src/main/resources/OH-INF/i18n/mail.properties

@@ -8,11 +8,17 @@ sendAttachmentMessageActionDescription = Sends a text mail with an URL attachmen
 sendAttachmentsMessageActionLabel = send a text mail with several attachments
 sendAttachmentsMessageActionDescription = Sends a text mail with several URL attachments.
 
-sendHTMLMessageActionLabel = send a HTML mail
-sendHTMLMessageActionDescription = Sends a HTML mail.
+sendComplexMessageActionLabel = send a text mail with several attachments and/or additional headers
+sendComplexMessageActionDescription = Sends a text mail with several URL attachments and/or additional headers.
 
-sendHTMLAttachmentMessageActionLabel = send a HTML mail with attachment
-sendHTMLAttachmentMessageActionDescription = Sends a HTML mail with an URL attachment.
+sendHTMLMessageActionLabel = send an HTML mail
+sendHTMLMessageActionDescription = Sends an HTML mail.
 
-sendHTMLAttachmentsMessageActionLabel = send a HTML mail with several attachments
-sendHTMLAttachmentsMessageActionDescription = Sends a HTML mail with several URL attachments.
+sendHTMLAttachmentMessageActionLabel = send an HTML mail with attachment
+sendHTMLAttachmentMessageActionDescription = Sends an HTML mail with an URL attachment.
+
+sendHTMLAttachmentsMessageActionLabel = send an HTML mail with several attachments
+sendHTMLAttachmentsMessageActionDescription = Sends an HTML mail with several URL attachments.
+
+sendComplexHtmlMessageActionLabel = send an html mail with several attachments and/or additional headers
+sendComplexHtmlMessageActionDescription = Sends an HTML mail with several URL attachments and/or additional headers.

bundles/org.smarthomej.binding.mail/src/main/resources/OH-INF/i18n/mail_de.properties

@@ -79,6 +79,9 @@ sendAttachmentMessageActionDescription = Sendet eine E-Mail mit Anhang.
 sendAttachmentsMessageActionLabel = eine E-Mail mit mehreren Anhängen senden
 sendAttachmentsMessageActionDescription = Sendet eine E-Mail mit mehreren Anhängen.
 
+sendComplexMessageActionLabel = eine E-Mail mit mehreren Anhängen senden und/oder zusätzlichen Headern
+sendComplexMessageActionDescription = Sendet eine E-Mail mit mehreren Anhängen und/oder zusätzlichen Headern.
+
 sendHTMLMessageActionLabel = eine HTML E-Mail senden
 sendHTMLMessageActionDescription = Sendet eine HTML E-Mail.
 
@@ -87,3 +90,6 @@ sendHTMLAttachmentMessageActionDescription = Sendet eine HTML E-Mail mit Anhang.
 
 sendHTMLAttachmentsMessageActionLabel = eine HTML E-Mail mit mehreren Anhängen senden
 sendHTMLAttachmentsMessageActionDescription = Sendet eine HTML E-Mail mit mehreren Anhängen.
+
+sendComplexHtmlMessageActionLabel = eine HTML E-Mail mit mehreren Anhängen senden und/oder zusätzlichen Headern
+sendComplexHtmlMessageActionDescription = Sendet eine HTML E-Mail mit mehreren Anhängen und/oder zusätzlichen Headern.

bundles/org.smarthomej.binding.mail/src/test/java/org/smarthomej/binding/mail/MailBuilderTest.java

@@ -19,6 +19,7 @@
 
 import java.io.IOException;
 import java.net.MalformedURLException;
+import java.util.Map;
 
 import javax.mail.MessagingException;
 import javax.mail.internet.AddressException;
@@ -92,5 +93,9 @@ public void fieldsSetInMail() throws EmailException, MessagingException, IOExcep
 
         assertEquals(TEST_EMAIL, builder.build().getToAddresses().get(0).getAddress());
         assertEquals(2, builder.withRecipients(TEST_EMAIL).build().getToAddresses().size());
+
+        Map<String, String> headers = builder.withHeader(TEST_STRING, TEST_STRING).build().getHeaders();
+        assertEquals(1, headers.size());
+        assertEquals(TEST_STRING, headers.get(TEST_STRING));
     }
 }