commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sgoes...@apache.org
Subject svn commit: r1165830 - in /commons/proper/email/trunk/src: changes/ java/org/apache/commons/mail/ site/xdoc/ test/org/apache/commons/mail/ test/org/apache/commons/mail/settings/
Date Tue, 06 Sep 2011 20:34:43 GMT
Author: sgoeschl
Date: Tue Sep  6 20:34:43 2011
New Revision: 1165830

URL: http://svn.apache.org/viewvc?rev=1165830&view=rev
Log:
[EMAIL-105][EMAIL-106] Clarified the meaning of setTLS() which actually sends a "STARTTLS"
command from the client to the SMTP server. Please note that some "protected" variables were
renamed which could break existing code.

Modified:
    commons/proper/email/trunk/src/changes/changes.xml
    commons/proper/email/trunk/src/java/org/apache/commons/mail/Email.java
    commons/proper/email/trunk/src/java/org/apache/commons/mail/EmailConstants.java
    commons/proper/email/trunk/src/site/xdoc/userguide.xml
    commons/proper/email/trunk/src/test/org/apache/commons/mail/EmailLiveTest.java
    commons/proper/email/trunk/src/test/org/apache/commons/mail/settings/EmailConfiguration.java

Modified: commons/proper/email/trunk/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/changes/changes.xml?rev=1165830&r1=1165829&r2=1165830&view=diff
==============================================================================
--- commons/proper/email/trunk/src/changes/changes.xml (original)
+++ commons/proper/email/trunk/src/changes/changes.xml Tue Sep  6 20:34:43 2011
@@ -23,6 +23,14 @@
 
   <body>
     <release version="1.3" date="as in SVN">
+       <action dev="sgoeschl" type="fix" issue="EMAIL-106" date="2011-09-06" due-to="Bruno
Harbulot">
+          STARTTLS can be used even without authenticator.
+      </action>
+      <action dev="sgoeschl" type="fix" issue="EMAIL-105" date="2011-09-06" due-to="Bruno
Harbulot">
+        Clarified the meaning of setTLS() which actually sends a "STARTTLS" command from
the
+        client to the SMTP server. Please note that some "protected" variables were renamed
+        which could break existing code.
+      </action>
       <action dev="sgoeschl" type="fix" issue="EMAIL-102" date="2010-12-16" due-to="Okan
Özeren">
         Fixed HtmlEmail embed toLowerCase bug with Turkish locale.
       </action>

Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/Email.java
URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/Email.java?rev=1165830&r1=1165829&r2=1165830&view=diff
==============================================================================
--- commons/proper/email/trunk/src/java/org/apache/commons/mail/Email.java (original)
+++ commons/proper/email/trunk/src/java/org/apache/commons/mail/Email.java Tue Sep  6 20:34:43
2011
@@ -157,11 +157,14 @@ public abstract class Email implements E
     /** the password to log into the pop3 server */
     protected String popPassword;
 
-    /** does server require TLS encryption for authentication */
-    protected boolean tls;
+    /** does client want STARTTLS encryption */
+    protected boolean startTlsEnabled;
+    
+    /** does client require STARTTLS encryption */
+    protected boolean startTlsRequired;
 
-    /** does the current transport use SSL encryption? */
-    protected boolean ssl;
+    /** does the current transport use SSL/TLS encryption upon connection? */
+    protected boolean sslOnConnect;
 
     /** socket I/O timeout value in milliseconds */
     protected int socketTimeout = SOCKET_TIMEOUT_MS;
@@ -196,7 +199,7 @@ public abstract class Email implements E
      * @param password password for the SMTP server
      * @return An Email.
      * @see DefaultAuthenticator
-     * @see #setAuthenticator
+     * @see #setAuthenticator(Authenticator)
      * @since 1.0
      */
     public Email setAuthentication(String userName, String password)
@@ -336,16 +339,42 @@ public abstract class Email implements E
     }
 
     /**
-     * Set or disable the TLS encryption
+     * Set or disable the STARTTLS encryption. Please see EMAIL-105
+     * for the reasons of deprecation.
      *
-     * @param withTLS true if TLS needed, false otherwise
+     * @deprecated since 1.3
+     * @param startTlsEnabled true if STARTTLS requested, false otherwise
      * @return An Email.
      * @since 1.1
      */
-    public Email setTLS(boolean withTLS)
+    public Email setTLS(boolean startTlsEnabled)
+    {
+        return setStartTLSEnabled(startTlsEnabled);
+    }
+    
+    /**
+     * Set or disable the STARTTLS encryption.
+     *
+     * @param startTlsEnabled true if STARTTLS requested, false otherwise
+     * @return An Email.
+     */
+    public Email setStartTLSEnabled(boolean startTlsEnabled)
     {
         checkSessionAlreadyInitialized();
-        this.tls = withTLS;
+        this.startTlsEnabled = startTlsEnabled;
+        return this;
+    }
+    
+    /**
+     * Set or disable the STARTTLS encryption.
+     *
+     * @param startTlsRequired true if STARTTLS requested, false otherwise
+     * @return An Email.
+     */
+    public Email setStartTLSRequired(boolean startTlsRequired)
+    {
+        checkSessionAlreadyInitialized();
+        this.startTlsRequired = startTlsRequired;
         return this;
     }
 
@@ -481,14 +510,25 @@ public abstract class Email implements E
             properties.setProperty(MAIL_HOST, this.hostName);
             properties.setProperty(MAIL_DEBUG, String.valueOf(this.debug));
 
+            properties.setProperty(MAIL_TRANSPORT_STARTTLS_ENABLE, startTlsEnabled ? "true"
: "false");
+            properties.setProperty(MAIL_TRANSPORT_STARTTLS_REQUIRED, startTlsRequired ? "true"
: "false");
+            
             if (this.authenticator != null)
             {
-                properties.setProperty(MAIL_TRANSPORT_TLS, tls ? "true" : "false");
                 properties.setProperty(MAIL_SMTP_AUTH, "true");
             }
+            
+            if (this.sslOnConnect || this.startTlsEnabled || this.startTlsRequired)
+            {
+                properties.setProperty(MAIL_SMTP_SSL_SOCKET_FACTORY_PORT, this.sslSmtpPort);
+                properties.setProperty(MAIL_SMTP_SSL_SOCKET_FACTORY_CLASS, "javax.net.ssl.SSLSocketFactory");
+                properties.setProperty(MAIL_SMTP_SOCKET_FACTORY_FALLBACK, "false");
+        	    properties.put(MAIL_SMTP_SSL_CHECKSERVERIDENTITY, Boolean.TRUE);
+            }
 
-            if (this.ssl)
+            if (this.sslOnConnect)
             {
+        	    properties.put(MAIL_SMTP_SSL_ENABLE, Boolean.TRUE);
                 properties.setProperty(MAIL_PORT, this.sslSmtpPort);
                 properties.setProperty(MAIL_SMTP_SOCKET_FACTORY_PORT, this.sslSmtpPort);
                 properties.setProperty(MAIL_SMTP_SOCKET_FACTORY_CLASS, "javax.net.ssl.SSLSocketFactory");
@@ -1253,16 +1293,38 @@ public abstract class Email implements E
         }
         return null;
     }
+    
+    /**
+     * Gets whether the client is configured to require STARTTLS.
+     *
+     * @return true if using STARTTLS for authentication, false otherwise
+     */
+    public boolean isStartTLSRequired()
+    {
+        return this.startTlsRequired;
+    }
+    
+    /**
+     * Gets whether the client is configured to try to enable STARTTLS.
+     *
+     * @return true if using STARTTLS for authentication, false otherwise
+     */
+    public boolean isStartTLSEnabled()
+    {
+        return this.startTlsEnabled;
+    }
 
     /**
-     * Gets encryption mode for authentication.
+     * Gets whether the client is configured to try to enable STARTTLS.
+     * See EMAIL-105 for reason of deprecation.
      *
-     * @return true if using TLS for authentication, false otherwise
+     * @deprecated since 1.3
+     * @return true if using STARTTLS for authentication, false otherwise
      * @since 1.1
      */
     public boolean isTLS()
     {
-        return this.tls;
+        return isStartTLSEnabled();
     }
 
     /**
@@ -1305,25 +1367,50 @@ public abstract class Email implements E
     }
 
     /**
-     * Returns whether SSL encryption for the transport is currently enabled.
-     *
+     * Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS).
+     * See EMAIL-105 for reason of deprecation.
+     * 
+     * @deprecated since 1.3
      * @return true if SSL enabled for the transport
      */
     public boolean isSSL()
     {
-        return ssl;
+        return isSSLOnConnect();
     }
-
+    
     /**
-     * Sets whether SSL encryption should be enabled for the SMTP transport.
+     * Returns whether SSL/TLS encryption for the transport is currently enabled (SMTPS/POPS).
+     * 
+     * @return true if SSL enabled for the transport
+     */
+    public boolean isSSLOnConnect()
+    {
+        return sslOnConnect;
+    }
+    
+    /**
+     * Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection
(SMTPS/POPS).
+     * See EMAIL-105 for reason of deprecation.
      *
+     * @deprecated since 1.3
      * @param ssl whether to enable the SSL transport
      * @return An Email.
      */
     public Email setSSL(boolean ssl)
     {
+        return setSSLOnConnect(ssl);
+    }
+
+    /**
+     * Sets whether SSL/TLS encryption should be enabled for the SMTP transport upon connection
(SMTPS/POPS).
+     *
+     * @param ssl whether to enable the SSL transport
+     * @return An Email.
+     */
+    public Email setSSLOnConnect(boolean ssl)
+    {
         checkSessionAlreadyInitialized();
-        this.ssl = ssl;
+        this.sslOnConnect = ssl;
         return this;
     }
 

Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/EmailConstants.java
URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/EmailConstants.java?rev=1165830&r1=1165829&r2=1165830&view=diff
==============================================================================
--- commons/proper/email/trunk/src/java/org/apache/commons/mail/EmailConstants.java (original)
+++ commons/proper/email/trunk/src/java/org/apache/commons/mail/EmailConstants.java Tue Sep
 6 20:34:43 2011
@@ -63,7 +63,10 @@ public interface EmailConstants
     // since 1.1
     /////////////////////////////////////////////////////////////////////////
 
+    /** @deprecated since 1.3 */
     String MAIL_TRANSPORT_TLS = "mail.smtp.starttls.enable";
+
+    String MAIL_TRANSPORT_STARTTLS_ENABLE = "mail.smtp.starttls.enable";
     String MAIL_SMTP_SOCKET_FACTORY_FALLBACK = "mail.smtp.socketFactory.fallback";
     String MAIL_SMTP_SOCKET_FACTORY_CLASS = "mail.smtp.socketFactory.class";
     String MAIL_SMTP_SOCKET_FACTORY_PORT = "mail.smtp.socketFactory.port";
@@ -89,4 +92,10 @@ public interface EmailConstants
     /////////////////////////////////////////////////////////////////////////
 
     int SOCKET_TIMEOUT_MS = 60000;
+
+    String MAIL_TRANSPORT_STARTTLS_REQUIRED = "mail.smtp.starttls.required";
+    String MAIL_SMTP_SSL_ENABLE = "mail.smtp.ssl.enable";
+    String MAIL_SMTP_SSL_CHECKSERVERIDENTITY = "mail.smtp.ssl.checkserveridentity";
+    String MAIL_SMTP_SSL_SOCKET_FACTORY_CLASS = "mail.smtp.ssl.socketFactory.class";
+    String MAIL_SMTP_SSL_SOCKET_FACTORY_PORT = "mail.smtp.ssl.socketFactory.port";
 }

Modified: commons/proper/email/trunk/src/site/xdoc/userguide.xml
URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/site/xdoc/userguide.xml?rev=1165830&r1=1165829&r2=1165830&view=diff
==============================================================================
--- commons/proper/email/trunk/src/site/xdoc/userguide.xml (original)
+++ commons/proper/email/trunk/src/site/xdoc/userguide.xml Tue Sep  6 20:34:43 2011
@@ -33,9 +33,9 @@
 <![CDATA[
 Email email = new SimpleEmail();
 email.setHostName("smtp.gmail.com");
-email.setSmtpPort(587);
+email.setSmtpPort(465);
 email.setAuthenticator(new DefaultAuthenticator("username", "password"));
-email.setTLS(true);
+email.setSSLOnConnect(true);
 email.setFrom("user@gmail.com");
 email.setSubject("TestMail");
 email.setMsg("This is a test mail ... :-)");

Modified: commons/proper/email/trunk/src/test/org/apache/commons/mail/EmailLiveTest.java
URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/test/org/apache/commons/mail/EmailLiveTest.java?rev=1165830&r1=1165829&r2=1165830&view=diff
==============================================================================
--- commons/proper/email/trunk/src/test/org/apache/commons/mail/EmailLiveTest.java (original)
+++ commons/proper/email/trunk/src/test/org/apache/commons/mail/EmailLiveTest.java Tue Sep
 6 20:34:43 2011
@@ -95,8 +95,8 @@ public class EmailLiveTest extends BaseE
 
         Email email = (Email) clazz.newInstance();
 
-        email.setTLS(EmailConfiguration.MAIL_USE_TLS);
-        email.setSSL(EmailConfiguration.MAIL_USE_SSL);
+        email.setStartTLSEnabled(EmailConfiguration.MAIL_USE_STARTTLS);
+        email.setSSLOnConnect(EmailConfiguration.MAIL_USE_SSL);
         email.setHostName(EmailConfiguration.MAIL_SERVER);
         email.setSmtpPort(EmailConfiguration.MAIL_SERVER_PORT);
         email.setBounceAddress(EmailConfiguration.TEST_FROM);
@@ -345,4 +345,4 @@ public class EmailLiveTest extends BaseE
             transport.close();
          }
     }
-}
\ No newline at end of file
+}

Modified: commons/proper/email/trunk/src/test/org/apache/commons/mail/settings/EmailConfiguration.java
URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/test/org/apache/commons/mail/settings/EmailConfiguration.java?rev=1165830&r1=1165829&r2=1165830&view=diff
==============================================================================
--- commons/proper/email/trunk/src/test/org/apache/commons/mail/settings/EmailConfiguration.java
(original)
+++ commons/proper/email/trunk/src/test/org/apache/commons/mail/settings/EmailConfiguration.java
Tue Sep  6 20:34:43 2011
@@ -28,6 +28,12 @@ import org.apache.commons.mail.EmailCons
  */
 public final class EmailConfiguration
 {
+    // when using GMail for testing the following combination work
+    //
+    // port 25      - StartTLS
+    // port 25      - StartTLS & UseSSL
+    // port 465     - UseSSL
+    // port 465     - StartTLS & UseSSL
 
     public static final boolean MAIL_FORCE_SEND     = false;
 	public static final boolean MAIL_DEBUG          = false;
@@ -39,7 +45,7 @@ public final class EmailConfiguration
     public static final String  TEST_USER           = "user";
     public static final String  TEST_PASSWD         = "password";
     public static final boolean MAIL_USE_SSL        = false;
-    public static final boolean MAIL_USE_TLS        = false;
+    public static final boolean MAIL_USE_STARTTLS   = false;
 
     public static final String TEST_URL = EmailConfiguration.class
         .getResource("/images/asf_logo_wide.gif")



Mime
View raw message