You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2023/12/15 16:34:15 UTC

(commons-email) 02/03: Add EmailConstants.SOCKET_TIMEOUT and deprecate SOCKET_TIMEOUT_MS

This is an automated email from the ASF dual-hosted git repository.

ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-email.git

commit 6653f2de3af3ea97e2977c41007a18eeab69f1c0
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Fri Dec 15 11:30:11 2023 -0500

    Add EmailConstants.SOCKET_TIMEOUT and deprecate SOCKET_TIMEOUT_MS
    
    - Add Email.setSocketConnectionTimeout(Duration) and deprecate
    setSocketConnectionTimeout(int)
    - Add Email.setSocketTimeout(Duration) and deprecate
    setSocketTimeout(int)
---
 src/changes/changes.xml                            |  3 ++
 src/main/java/org/apache/commons/mail/Email.java   | 51 +++++++++++++++++++---
 .../org/apache/commons/mail/EmailConstants.java    | 19 ++++----
 .../apache/commons/mail/EmailConstantsTest.java    | 34 +++++++++++++++
 .../java/org/apache/commons/mail/EmailTest.java    | 21 +++++++++
 .../org/apache/commons/mail/HtmlEmailTest.java     |  1 +
 6 files changed, 115 insertions(+), 14 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 55d0a99..a2710b2 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -45,6 +45,9 @@
       <action issue="EMAIL-176" type="add" dev="pschumacher">Add Automatic-Module-Name MANIFEST entry for Java 9 compatibility.</action>
       <action issue="EMAIL-207" type="add" dev="ggregory" due-to="Lee Jaeheon, Gary Gregory">Add org.apache.commons.mail.InputStreamDataSource.</action>
       <action issue="EMAIL-207" type="add" dev="ggregory" due-to="Lee Jaeheon, Gary Gregory">Don't waste memory in MimeMessageParser#createDataSource().</action>
+      <action type="add" due-to="Gary Gregory" dev="ggregory">Add EmailConstants.SOCKET_TIMEOUT and deprecate SOCKET_TIMEOUT_MS.</action>
+      <action type="add" due-to="Gary Gregory" dev="ggregory">Add Email.setSocketConnectionTimeout(Duration) and deprecate setSocketConnectionTimeout(int).</action>
+      <action type="add" due-to="Gary Gregory" dev="ggregory">Add Email.setSocketTimeout(Duration) and deprecate setSocketTimeout(int).</action>
       <!-- UPDATE -->
       <action type="update" due-to="Dependabot" dev="sebb">Bump org.slf4j:slf4j-jdk14 from 1.7.7 to 2.0.9 #165.</action>
       <action type="update" due-to="Dependabot" dev="sebb">Bump mockito-core from 4.11.0 to 5.8.0 #187.</action>
diff --git a/src/main/java/org/apache/commons/mail/Email.java b/src/main/java/org/apache/commons/mail/Email.java
index 2fa65f7..9484d1c 100644
--- a/src/main/java/org/apache/commons/mail/Email.java
+++ b/src/main/java/org/apache/commons/mail/Email.java
@@ -18,6 +18,7 @@ package org.apache.commons.mail;
 
 import java.io.UnsupportedEncodingException;
 import java.nio.charset.Charset;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Date;
@@ -274,11 +275,21 @@ public abstract class Email {
     @Deprecated
     protected boolean ssl;
 
-    /** Socket I/O timeout value in milliseconds. */
-    protected int socketTimeout = EmailConstants.SOCKET_TIMEOUT_MS;
+    /**
+     * Socket I/O timeout value in milliseconds.
+     *
+     * @deprecated Use {@link #getSocketTimeout()} and {@link #setSocketTimeout(Duration)}.
+     */
+    @Deprecated
+    protected int socketTimeout = Math.toIntExact(EmailConstants.SOCKET_TIMEOUT.toMillis());
 
-    /** Socket connection timeout value in milliseconds. */
-    protected int socketConnectionTimeout = EmailConstants.SOCKET_TIMEOUT_MS;
+    /**
+     * Socket connection timeout value in milliseconds.
+     *
+     * @deprecated Use {@link #getSocketConnectionTimeout()} and {@link #setSocketConnectionTimeout(Duration)}.
+     */
+    @Deprecated
+    protected int socketConnectionTimeout = Math.toIntExact(EmailConstants.SOCKET_TIMEOUT.toMillis());
 
     /**
      * If true, enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any
@@ -868,7 +879,7 @@ public abstract class Email {
             }
 
             // changed this (back) to getInstance due to security exceptions
-            // caused when testing using maven
+            // caused when testing using Maven
             this.session = Session.getInstance(properties, this.authenticator);
         }
         return this.session;
@@ -1190,7 +1201,7 @@ public abstract class Email {
     /**
      * Sets the content and contentType.
      *
-     * @param aObject      aObject
+     * @param aObject     aObject
      * @param contentType aContentType
      * @since 1.0
      */
@@ -1431,25 +1442,53 @@ public abstract class Email {
         this.smtpPort = Integer.toString(aPortNumber);
     }
 
+    /**
+     * Sets the socket connection timeout value in milliseconds. Default is a 60 second timeout.
+     *
+     * @param socketConnectionTimeout the connection timeout
+     * @throws IllegalStateException if the mail session is already initialized
+     * @since 1.6.0
+     */
+    public void setSocketConnectionTimeout(final Duration socketConnectionTimeout) {
+        checkSessionAlreadyInitialized();
+        this.socketConnectionTimeout = Math.toIntExact(socketConnectionTimeout.toMillis());
+    }
+
     /**
      * Sets the socket connection timeout value in milliseconds. Default is a 60 second timeout.
      *
      * @param socketConnectionTimeout the connection timeout
      * @throws IllegalStateException if the mail session is already initialized
      * @since 1.2
+     * @deprecated Use {@link #setSocketConnectionTimeout(Duration)}.
      */
+    @Deprecated
     public void setSocketConnectionTimeout(final int socketConnectionTimeout) {
         checkSessionAlreadyInitialized();
         this.socketConnectionTimeout = socketConnectionTimeout;
     }
 
+    /**
+     * Sets the socket I/O timeout value in milliseconds. Default is 60 second timeout.
+     *
+     * @param socketTimeout the socket I/O timeout
+     * @throws IllegalStateException if the mail session is already initialized
+     * @since 1.6.0
+     */
+    public void setSocketTimeout(final Duration socketTimeout) {
+        checkSessionAlreadyInitialized();
+        this.socketTimeout = Math.toIntExact(socketTimeout.toMillis());
+    }
+
     /**
      * Sets the socket I/O timeout value in milliseconds. Default is 60 second timeout.
      *
      * @param socketTimeout the socket I/O timeout
      * @throws IllegalStateException if the mail session is already initialized
      * @since 1.2
+     * @deprecated Use {@link #setSocketTimeout(Duration)}.
      */
+    @Deprecated
     public void setSocketTimeout(final int socketTimeout) {
         checkSessionAlreadyInitialized();
         this.socketTimeout = socketTimeout;
diff --git a/src/main/java/org/apache/commons/mail/EmailConstants.java b/src/main/java/org/apache/commons/mail/EmailConstants.java
index fb7a660..ac219ba 100644
--- a/src/main/java/org/apache/commons/mail/EmailConstants.java
+++ b/src/main/java/org/apache/commons/mail/EmailConstants.java
@@ -16,6 +16,8 @@
  */
 package org.apache.commons.mail;
 
+import java.time.Duration;
+
 /**
  * Constants used by Email classes.
  *
@@ -148,10 +150,6 @@ public final class EmailConstants {
      */
     public static final String MAIL_SMTP_SOCKET_FACTORY_PORT = "mail.smtp.socketFactory.port";
 
-    /////////////////////////////////////////////////////////////////////////
-    // since 1.2
-    /////////////////////////////////////////////////////////////////////////
-
     /**
      * Socket connection timeout value in milliseconds. Default is infinite timeout.
      *
@@ -166,16 +164,21 @@ public final class EmailConstants {
      */
     public static final String MAIL_SMTP_TIMEOUT = "mail.smtp.timeout";
 
-    /////////////////////////////////////////////////////////////////////////
-    // since 1.3
-    /////////////////////////////////////////////////////////////////////////
+    /**
+     * Default socket timeout.
+     *
+     * @since 1.6.0
+     */
+    public static final Duration SOCKET_TIMEOUT = Duration.ofMinutes(1);
 
     /**
      * Default socket timeout.
      *
      * @since 1.3
+     * @deprecated Use {@link #SOCKET_TIMEOUT}.
      */
-    public static final int SOCKET_TIMEOUT_MS = 60000;
+    @Deprecated
+    public static final int SOCKET_TIMEOUT_MS = 60_000;
 
     /**
      * If true, requires the use of the STARTTLS command. If the server doesn't support the STARTTLS command, the connection will fail.
diff --git a/src/test/java/org/apache/commons/mail/EmailConstantsTest.java b/src/test/java/org/apache/commons/mail/EmailConstantsTest.java
new file mode 100644
index 0000000..a4bb4d4
--- /dev/null
+++ b/src/test/java/org/apache/commons/mail/EmailConstantsTest.java
@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.mail;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.time.Duration;
+
+import org.junit.jupiter.api.Test;
+
+public class EmailConstantsTest {
+
+    @SuppressWarnings("deprecation")
+    @Test
+    public void test_SOCKET_TIMEOUT() {
+        assertEquals(EmailConstants.SOCKET_TIMEOUT, Duration.ofMillis(EmailConstants.SOCKET_TIMEOUT_MS));
+    }
+
+}
diff --git a/src/test/java/org/apache/commons/mail/EmailTest.java b/src/test/java/org/apache/commons/mail/EmailTest.java
index b8fa1d1..2cc7435 100644
--- a/src/test/java/org/apache/commons/mail/EmailTest.java
+++ b/src/test/java/org/apache/commons/mail/EmailTest.java
@@ -28,6 +28,7 @@ import java.io.File;
 import java.nio.charset.Charset;
 import java.nio.charset.IllegalCharsetNameException;
 import java.nio.charset.StandardCharsets;
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Calendar;
 import java.util.Collections;
@@ -1047,6 +1048,26 @@ public class EmailTest extends AbstractEmailTest {
         assertThrows(EmailException.class, () -> email.setTo(null));
     }
 
+    @Test
+    public void testSocketConnectionTimeout() {
+        assertEquals(EmailConstants.SOCKET_TIMEOUT_MS, email.getSocketConnectionTimeout());
+        assertEquals(EmailConstants.SOCKET_TIMEOUT.toMillis(), email.getSocketConnectionTimeout());
+        email.setSocketConnectionTimeout(1234);
+        assertEquals(1234, email.getSocketConnectionTimeout());
+        email.setSocketConnectionTimeout(Duration.ofMillis(5678));
+        assertEquals(5678, email.getSocketConnectionTimeout());
+    }
+
+    @Test
+    public void testSocketTimeout() {
+        assertEquals(EmailConstants.SOCKET_TIMEOUT_MS, email.getSocketTimeout());
+        assertEquals(EmailConstants.SOCKET_TIMEOUT.toMillis(), email.getSocketTimeout());
+        email.setSocketTimeout(1234);
+        assertEquals(1234, email.getSocketTimeout());
+        email.setSocketTimeout(Duration.ofMillis(5678));
+        assertEquals(5678, email.getSocketTimeout());
+    }
+
     @Test
     public void testSupportForInternationalDomainNames() throws Exception {
         email.setHostName(strTestMailServer);
diff --git a/src/test/java/org/apache/commons/mail/HtmlEmailTest.java b/src/test/java/org/apache/commons/mail/HtmlEmailTest.java
index e14c4c9..2046ba5 100644
--- a/src/test/java/org/apache/commons/mail/HtmlEmailTest.java
+++ b/src/test/java/org/apache/commons/mail/HtmlEmailTest.java
@@ -40,6 +40,7 @@ import static org.junit.jupiter.api.Assertions.*;
  * @since 1.0
  */
 public class HtmlEmailTest extends AbstractEmailTest {
+
     private MockHtmlEmailConcrete email;
 
     private void assertCorrectContentType(final String picture, final String contentType) throws Exception {