Enable mail MTA/SMTP configuration using MicroProfile Config

doc/release-notes/7424-mailsession.md

@@ -0,0 +1,8 @@
+## New way to configure mail transfer agent
+
+With this release, we deprecate the usage of `asadmin create-javamail-resource` to configure your MTA.
+Instead, we provide the ability to configure your SMTP mail host using JVM options with the flexibility of MicroProfile Config.
+
+At this point, no action is required if you want to keep your current configuration.
+Warnings will show in your server logs to inform and remind you about the deprecation.
+A future major release of Dataverse may remove this way of configuration.

doc/sphinx-guides/source/container/app-image.rst

@@ -134,19 +134,6 @@ In addition, the application image provides the following tunables:
 
         1. Simply pick a JVM option from the list and replace any ``.`` with ``_``.
         2. Replace any ``-`` in the option name with ``__``.
-    * - ``DATAVERSE_MAIL_HOST``
-      - ``smtp``
-      - String
-      - A hostname (w/o port!) where to reach a Mail MTA on port 25.
-    * - ``DATAVERSE_MAIL_USER``
-      - ``dataversenotify``
-      - String
-      - A username to use with the Mail MTA
-    * - ``DATAVERSE_MAIL_FROM``
-      - ``dataverse@localhost``
-      - Mail address
-      - The "From" field for all outbound mail. Make sure to set :ref:`systemEmail` to the same value or no mail will
-        be sent.
 
 
 Note that the script ``init_2_configure.sh`` will apply a few very important defaults to enable quick usage

modules/dataverse-parent/pom.xml

@@ -168,10 +168,10 @@
         <gdcc.xoai.version>5.2.0</gdcc.xoai.version>
 
         <!-- Testing dependencies -->
-        <testcontainers.version>1.19.0</testcontainers.version>
-        <smallrye-mpconfig.version>2.10.1</smallrye-mpconfig.version>
+        <testcontainers.version>1.19.1</testcontainers.version>
+        <smallrye-mpconfig.version>3.4.1</smallrye-mpconfig.version>
         <junit.jupiter.version>5.10.0</junit.jupiter.version>
-        <mockito.version>5.4.0</mockito.version>
+        <mockito.version>5.6.0</mockito.version>
         <maven-jacoco-plugin.version>0.8.10</maven-jacoco-plugin.version>
 
         <checkstyle.version>9.3</checkstyle.version>

pom.xml

@@ -51,6 +51,17 @@
                 <artifactId>abdera-i18n</artifactId>
                 <version>1.1.3</version>
             </dependency>
+            <dependency>
+                <groupId>org.apache.abdera</groupId>
+                <artifactId>abdera-parser</artifactId>
+                <version>1.1.3</version>
+                <exclusions>
+                    <exclusion>
+                        <groupId>org.apache.geronimo.specs</groupId>
+                        <artifactId>geronimo-javamail_1.4_spec</artifactId>
+                    </exclusion>
+                </exclusions>
+            </dependency>
         </dependencies>
     </dependencyManagement>
     <!-- Declare any DIRECT dependencies here.
@@ -677,6 +688,7 @@
                     <include>**/firstNames/*.*</include>
                     <include>**/*.xsl</include>
                     <include>**/services/*</include>
+                    <include>**/*.map</include>
                 </includes>
             </resource>
             <resource>

src/main/docker/scripts/init_2_configure.sh

@@ -31,10 +31,6 @@ echo "# Dataverse postboot configuration for Payara" > "${DV_POSTBOOT}"
 #       EE 8 code annotations or at least glassfish-resources.xml
 # NOTE: postboot commands is not multi-line capable, thus spaghetti needed.
 
-# JavaMail
-echo "INFO: Defining JavaMail."
-echo "create-javamail-resource --mailhost=${DATAVERSE_MAIL_HOST:-smtp} --mailuser=${DATAVERSE_MAIL_USER:-dataversenotify} --fromaddress=${DATAVERSE_MAIL_FROM:-dataverse@localhost} mail/notifyMailSession" >> "${DV_POSTBOOT}"
-
 # 3. Domain based configuration options
 # Set Dataverse environment variables
 echo "INFO: Defining system properties for Dataverse configuration options."

src/main/java/edu/harvard/iq/dataverse/MailServiceBean.java

@@ -11,6 +11,7 @@
 import edu.harvard.iq.dataverse.branding.BrandingUtil;
 import edu.harvard.iq.dataverse.confirmemail.ConfirmEmailServiceBean;
 import edu.harvard.iq.dataverse.dataset.DatasetUtil;
+import edu.harvard.iq.dataverse.settings.JvmSettings;
 import edu.harvard.iq.dataverse.settings.SettingsServiceBean;
 import edu.harvard.iq.dataverse.settings.SettingsServiceBean.Key;
 import edu.harvard.iq.dataverse.util.BundleUtil;
@@ -24,11 +25,15 @@
 import java.util.Arrays;
 import java.util.Date;
 import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
 import java.util.Set;
+import java.util.logging.Level;
 import java.util.logging.Logger;
-import jakarta.annotation.Resource;
 import jakarta.ejb.EJB;
 import jakarta.ejb.Stateless;
+import jakarta.inject.Inject;
+import jakarta.inject.Named;
 import jakarta.mail.Address;
 import jakarta.mail.Message;
 import jakarta.mail.MessagingException;
@@ -78,77 +83,133 @@ public class MailServiceBean implements java.io.Serializable {
      */
     public MailServiceBean() {
     }
+
+    /**
+     * Creates a new instance of MailServiceBean with explicit injection, as used during testing.
+     */
+    public MailServiceBean(Session session, SettingsServiceBean settingsService) {
+        this.session = session;
+        this.settingsService = settingsService;
+    }
 
-    @Resource(name = "mail/notifyMailSession")
+    @Inject
+    @Named("mail/systemSession")
     private Session session;
 
     public boolean sendSystemEmail(String to, String subject, String messageText) {
         return sendSystemEmail(to, subject, messageText, false);
     }
-
+
+    /**
+     * Send a system notification to one or multiple recipients by email.
+     * Will skip sending when {@link #getSystemAddress()} doesn't return a configured "from" address.
+     * @param to A comma separated list of one or multiple recipients' addresses. May contain a "personal name" and
+     *           the recipients address in <>. See also {@link InternetAddress}.
+     * @param subject The message's subject
+     * @param messageText The message's text
+     * @param isHtmlContent Determine if the message text is formatted using HTML or plain text.
+     * @return Status: true if sent successfully, false otherwise
+     */
     public boolean sendSystemEmail(String to, String subject, String messageText, boolean isHtmlContent) {
+        Optional<InternetAddress> optionalAddress = getSystemAddress();
+        if (optionalAddress.isEmpty()) {
+            logger.fine(() -> "Skipping sending mail to " + to + ", because no system address has been set.");
+            return false;
+        }
+        InternetAddress systemAddress = optionalAddress.get();
 
-        boolean sent = false;
-        InternetAddress systemAddress = getSystemAddress(); 
-
-        String body = messageText
-                + (isHtmlContent ? BundleUtil.getStringFromBundle("notification.email.closing.html", Arrays.asList(BrandingUtil.getSupportTeamEmailAddress(systemAddress), BrandingUtil.getSupportTeamName(systemAddress)))
-                        : BundleUtil.getStringFromBundle("notification.email.closing", Arrays.asList(BrandingUtil.getSupportTeamEmailAddress(systemAddress), BrandingUtil.getSupportTeamName(systemAddress))));
+        String body = messageText +
+            BundleUtil.getStringFromBundle(isHtmlContent ? "notification.email.closing.html" : "notification.email.closing",
+                List.of(BrandingUtil.getSupportTeamEmailAddress(systemAddress), BrandingUtil.getSupportTeamName(systemAddress)));
 
-        logger.fine("Sending email to " + to + ". Subject: <<<" + subject + ">>>. Body: " + body);
+        logger.fine(() -> "Sending email to %s. Subject: <<<%s>>>. Body: %s".formatted(to, subject, body));
         try {
+            // Since JavaMail 1.6, we have support for UTF-8 mail addresses and do not need to handle these ourselves.
+            InternetAddress[] recipients = InternetAddress.parse(to);
+
             MimeMessage msg = new MimeMessage(session);
-            if (systemAddress != null) {
-                msg.setFrom(systemAddress);
-                msg.setSentDate(new Date());
-                String[] recipientStrings = to.split(",");
-                InternetAddress[] recipients = new InternetAddress[recipientStrings.length];
-                for (int i = 0; i < recipients.length; i++) {
-                    try {
-                        recipients[i] = new InternetAddress(recipientStrings[i], "", charset);
-                    } catch (UnsupportedEncodingException ex) {
-                        logger.severe(ex.getMessage());
-                    }
-                }
-                msg.setRecipients(Message.RecipientType.TO, recipients);
-                msg.setSubject(subject, charset);
-                if (isHtmlContent) {
-                    msg.setText(body, charset, "html");
-                } else {
-                    msg.setText(body, charset);
-                }
-
-                try {
-                    Transport.send(msg, recipients);
-                    sent = true;
-                } catch (MessagingException ssfe) {
-                    logger.warning("Failed to send mail to: " + to);
-                    logger.warning("MessagingException Message: " + ssfe);
-                }
+            msg.setFrom(systemAddress);
+            msg.setSentDate(new Date());
+            msg.setRecipients(Message.RecipientType.TO, recipients);
+            msg.setSubject(subject, charset);
+            if (isHtmlContent) {
+                msg.setText(body, charset, "html");
             } else {
-                logger.fine("Skipping sending mail to " + to + ", because the \"no-reply\" address not set (" + Key.SystemEmail + " setting).");
+                msg.setText(body, charset);
             }
-        } catch (AddressException ae) {
-            logger.warning("Failed to send mail to " + to);
-            ae.printStackTrace(System.out);
-        } catch (MessagingException me) {
-            logger.warning("Failed to send mail to " + to);
-            me.printStackTrace(System.out);
+            
+            Transport.send(msg, recipients);
+            return true;
+        } catch (MessagingException ae) {
+            logger.log(Level.WARNING, "Failed to send mail to %s: %s".formatted(to, ae.getMessage()), ae);
+            logger.info("When UTF-8 characters in recipients: make sure MTA supports it and JVM option " + JvmSettings.MAIL_MTA_SUPPORT_UTF8.getScopedKey() + "=true");
         }
-        return sent;
+        return false;
     }
-
-    public InternetAddress getSystemAddress() {
-       String systemEmail = settingsService.getValueForKey(Key.SystemEmail);
-       return MailUtil.parseSystemAddress(systemEmail);
+
+    /**
+     * Lookup the system mail address ({@code InternetAddress} may contain personal and actual address).
+     * @return The system mail address or an empty {@code Optional} if not configured.
+     */
+    public Optional<InternetAddress> getSystemAddress() {
+        boolean providedByDB = false;
+        String mailAddress = JvmSettings.SYSTEM_EMAIL.lookupOptional().orElse(null);
+
+        // Try lookup of (deprecated) database setting only if not configured via MPCONFIG
+        if (mailAddress == null) {
+            mailAddress = settingsService.getValueForKey(Key.SystemEmail);
+            // Encourage people to migrate from deprecated setting
+            if (mailAddress != null) {
+                providedByDB = true;
+                logger.warning("The :SystemMail DB setting has been deprecated, please reconfigure using JVM option " + JvmSettings.SYSTEM_EMAIL.getScopedKey());
+            }
+        }
+
+        try {
+            // Parse and return.
+            return Optional.of(new InternetAddress(Objects.requireNonNull(mailAddress), true));
+        } catch (AddressException e) {
+            logger.log(Level.WARNING, "Could not parse system mail address '%s' provided by %s: "
+                .formatted(providedByDB ? "DB setting" : "JVM option", mailAddress), e);
+        } catch (NullPointerException e) {
+            // Do not pester the logs - no configuration may mean someone wants to disable mail notifications
+            logger.fine("Could not find a system mail setting in database (key :SystemEmail, deprecated) or JVM option '" + JvmSettings.SYSTEM_EMAIL.getScopedKey() + "'");
+        }
+        // We define the system email address as an optional setting, in case people do not want to enable mail
+        // notifications (like in a development context, but might be useful elsewhere, too).
+        return Optional.empty();
+    }
+
+    /**
+     * Lookup the support team mail address ({@code InternetAddress} may contain personal and actual address).
+     * Will default to return {@code #getSystemAddress} if not configured.
+     * @return Support team mail address
+     */
+    public Optional<InternetAddress> getSupportAddress() {
+        Optional<String> supportMailAddress = JvmSettings.SUPPORT_EMAIL.lookupOptional();
+        if (supportMailAddress.isPresent()) {
+            try {
+                return Optional.of(new InternetAddress(supportMailAddress.get(), true));
+            } catch (AddressException e) {
+                logger.log(Level.WARNING, "Could not parse support mail address '%s', defaulting to system address: ".formatted(supportMailAddress.get()), e);
+            }
+        }
+        return getSystemAddress();
     }
 
     //@Resource(name="mail/notifyMailSession")
     public void sendMail(String reply, String to, String cc, String subject, String messageText) {
+        Optional<InternetAddress> optionalAddress = getSystemAddress();
+        if (optionalAddress.isEmpty()) {
+            logger.fine(() -> "Skipping sending mail to " + to + ", because no system address has been set.");
+            return;
+        }
+        // Always send from system address to avoid email being blocked
+        InternetAddress fromAddress = optionalAddress.get();
+
         try {
             MimeMessage msg = new MimeMessage(session);
-            // Always send from system address to avoid email being blocked
-            InternetAddress fromAddress = getSystemAddress();
+
             try {
                 setContactDelegation(reply, fromAddress);
             } catch (UnsupportedEncodingException ex) {
@@ -505,13 +566,12 @@ public String getMessageTextBasedOnNotification(UserNotification userNotificatio
                 messageText += MessageFormat.format(pattern, paramArrayStatus);
                 return messageText;
             case CREATEACC:
-                InternetAddress systemAddress = getSystemAddress();
                 String accountCreatedMessage = BundleUtil.getStringFromBundle("notification.email.welcome", Arrays.asList(
                         BrandingUtil.getInstallationBrandName(),
                         systemConfig.getGuidesBaseUrl(),
                         systemConfig.getGuidesVersion(),
-                        BrandingUtil.getSupportTeamName(systemAddress),
-                        BrandingUtil.getSupportTeamEmailAddress(systemAddress)
+                        BrandingUtil.getSupportTeamName(getSystemAddress().orElse(null)),
+                        BrandingUtil.getSupportTeamEmailAddress(getSystemAddress().orElse(null))
                 ));
                 String optionalConfirmEmailAddon = confirmEmailService.optionalConfirmEmailAddonMsg(userNotification.getUser());
                 accountCreatedMessage += optionalConfirmEmailAddon;

src/main/java/edu/harvard/iq/dataverse/SendFeedbackDialog.java

@@ -6,7 +6,6 @@
 import edu.harvard.iq.dataverse.settings.JvmSettings;
 import edu.harvard.iq.dataverse.settings.SettingsServiceBean;
 import edu.harvard.iq.dataverse.util.BundleUtil;
-import edu.harvard.iq.dataverse.util.MailUtil;
 import edu.harvard.iq.dataverse.util.SystemConfig;
 import java.util.Optional;
 import java.util.Random;
@@ -101,8 +100,7 @@ public void initUserInput(ActionEvent ae) {
         op1 = Long.valueOf(random.nextInt(10));
         op2 = Long.valueOf(random.nextInt(10));
         userSum = null;
-        String supportEmail = JvmSettings.SUPPORT_EMAIL.lookupOptional().orElse(settingsService.getValueForKey(SettingsServiceBean.Key.SystemEmail));
-        systemAddress = MailUtil.parseSystemAddress(supportEmail);
+        systemAddress = mailService.getSupportAddress().orElse(null);
     }
 
     public Long getOp1() {

src/main/java/edu/harvard/iq/dataverse/SettingsWrapper.java

@@ -63,6 +63,9 @@ public class SettingsWrapper implements java.io.Serializable {
 
     @EJB
     MetadataBlockServiceBean mdbService;
+
+    @EJB
+    MailServiceBean mailServiceBean;
 
     private Map<String, String> settingsMap;
 
@@ -388,14 +391,14 @@ public boolean isDataFilePIDSequentialDependent(){
     }
 
     public String getSupportTeamName() {
-        String systemEmail = getValueForKey(SettingsServiceBean.Key.SystemEmail);
-        InternetAddress systemAddress = MailUtil.parseSystemAddress(systemEmail);
+        // TODO: should this be replaced with mailServiceBean.getSupportAddress() to expose a configured support team?
+        InternetAddress systemAddress = mailServiceBean.getSystemAddress().orElse(null);
         return BrandingUtil.getSupportTeamName(systemAddress);
     }
 
     public String getSupportTeamEmail() {
-        String systemEmail = getValueForKey(SettingsServiceBean.Key.SystemEmail);
-        InternetAddress systemAddress = MailUtil.parseSystemAddress(systemEmail);        
+        // TODO: should this be replaced with mailServiceBean.getSupportAddress() to expose a configured support team?
+        InternetAddress systemAddress = mailServiceBean.getSystemAddress().orElse(null);
         return BrandingUtil.getSupportTeamEmailAddress(systemAddress) != null ? BrandingUtil.getSupportTeamEmailAddress(systemAddress) : BrandingUtil.getSupportTeamName(systemAddress);
     }
 

src/main/java/edu/harvard/iq/dataverse/api/FeedbackApi.java

@@ -7,9 +7,6 @@
 import edu.harvard.iq.dataverse.branding.BrandingUtil;
 import edu.harvard.iq.dataverse.feedback.Feedback;
 import edu.harvard.iq.dataverse.feedback.FeedbackUtil;
-import edu.harvard.iq.dataverse.settings.JvmSettings;
-import edu.harvard.iq.dataverse.settings.SettingsServiceBean;
-import edu.harvard.iq.dataverse.util.MailUtil;
 
 import jakarta.ejb.EJB;
 import jakarta.json.Json;
@@ -40,7 +37,7 @@ public class FeedbackApi extends AbstractApiBean {
      * user input (e.g. to strip potentially malicious html, etc.)!!!!
      **/
     @POST
-    public Response submitFeedback(JsonObject jsonObject) throws AddressException {
+    public Response submitFeedback(JsonObject jsonObject) {
         JsonNumber jsonNumber = jsonObject.getJsonNumber("targetId");
         DvObject feedbackTarget = null;
         if (jsonNumber != null) {
@@ -51,8 +48,7 @@ public Response submitFeedback(JsonObject jsonObject) throws AddressException {
         }
         DataverseSession dataverseSession = null;
         String userMessage = jsonObject.getString("body");
-        String systemEmail = JvmSettings.SUPPORT_EMAIL.lookupOptional().orElse(settingsSvc.getValueForKey(SettingsServiceBean.Key.SystemEmail));
-        InternetAddress systemAddress = MailUtil.parseSystemAddress(systemEmail);
+        InternetAddress systemAddress = mailService.getSupportAddress().orElse(null);
         String userEmail = jsonObject.getString("fromEmail");
         String messageSubject = jsonObject.getString("subject");
         String baseUrl = systemConfig.getDataverseSiteUrl();