Author: sgoeschl Date: Sat Nov 6 00:58:11 2010 New Revision: 1031900 URL: http://svn.apache.org/viewvc?rev=1031900&view=rev Log: Preparing a release candidate.
Modified: commons/proper/email/trunk/NOTICE.txt commons/proper/email/trunk/RELEASE-NOTES.txt commons/proper/email/trunk/pom.xml commons/proper/email/trunk/src/changes/changes.xml commons/proper/email/trunk/src/java/org/apache/commons/mail/ByteArrayDataSource.java 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/java/org/apache/commons/mail/ImageHtmlEmail.java commons/proper/email/trunk/src/java/org/apache/commons/mail/impl/DataSourceResolverImpl.java commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageParser.java commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageUtils.java commons/proper/email/trunk/src/site/xdoc/index.xml Modified: commons/proper/email/trunk/NOTICE.txt URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/NOTICE.txt?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/NOTICE.txt (original) +++ commons/proper/email/trunk/NOTICE.txt Sat Nov 6 00:58:11 2010 @@ -1,5 +1,5 @@ Apache Commons Email -Copyright 2001-2009 The Apache Software Foundation +Copyright 2001-2010 The Apache Software Foundation This product includes software developed by The Apache Software Foundation (http://www.apache.org/). Modified: commons/proper/email/trunk/RELEASE-NOTES.txt URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/RELEASE-NOTES.txt?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/RELEASE-NOTES.txt (original) +++ commons/proper/email/trunk/RELEASE-NOTES.txt Sat Nov 6 00:58:11 2010 @@ -19,6 +19,45 @@ This is a maintenance release which fixe release and adds a number of small enhancements requested by users. All current users are encouraged to upgrade. +CHANGES FROM 1.2: +----------------- + +== New Features == + +o Added MimeMessageParser and MimeMessageUtils. + +== Fixed Bugs == + +o Throwing an IllegalStateException when setting mail session properties + for an already created mail session because the settings would be + ignored. Please note that this change could potentially break existing + (but invalid) code. Issue: EMAIL-96. + +o Encoding and folding of headers is now done by commons-email. + Issue: EMAIL-98. Thanks to Mario Daepp. + +o The default connection timeout is set to a reasonable default value of + 60 seconds. Issue: EMAIL-100. Thanks to David Parks. + +o Moving the various constants from 'EMail' to 'EmailConstants' + +o All setters are returning "this" to simplify building an email. + Issue: EMAIL-76. Thanks to Yu Kobayashi. + +o Adding ImageHtmlEmail to create HTML emails with embedded images either + downloaded from HTTP or from the local file system. + Issue: EMAIL-92. Thanks to Dominik Stadler. + +o Calling buildMimeMessage() before invoking send() caused duplicated + mime parts for HtmlEmail. The implementation now enforces that an email + can be only used once and throw an exception when multiple invocations of + buildMimeMessage() are detected. Issue: EMAIL-95. + +o Incorrect SMTP Port number shown in error message when an email fails + to send due to a blocked port and SSL is used. + Issue: EMAIL-91. Thanks to Kevin Lester. + + CHANGES FROM 1.1: ----------------- @@ -71,7 +110,7 @@ REQUIREMENTS: J2SE environments ----------------- -Commons Email requires JavaMail 1.4 or later. The Sun implementation +Commons Email requires JavaMail 1.4.1 or later. The Sun implementation is available at: http://java.sun.com/products/javamail/ Modified: commons/proper/email/trunk/pom.xml URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/pom.xml?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/pom.xml (original) +++ commons/proper/email/trunk/pom.xml Sat Nov 6 00:58:11 2010 @@ -251,8 +251,8 @@ <commons.componentid>email</commons.componentid> <commons.jira.id>EMAIL</commons.jira.id> <commons.jira.pid>12310474</commons.jira.pid> - <commons.release.version>1.2</commons.release.version> - <commons.rc.version>RC3</commons.rc.version> + <commons.release.version>1.3</commons.release.version> + <commons.rc.version>RC1</commons.rc.version> <commons.binary.suffix>-bin</commons.binary.suffix> </properties> @@ -350,7 +350,7 @@ <comparisonArtifact> <groupId>org.apache.commons</groupId> <artifactId>commons-email</artifactId> - <version>1.1</version> + <version>1.2</version> </comparisonArtifact> </comparisonArtifacts> </configuration> Modified: commons/proper/email/trunk/src/changes/changes.xml URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/changes/changes.xml?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/changes/changes.xml (original) +++ commons/proper/email/trunk/src/changes/changes.xml Sat Nov 6 00:58:11 2010 @@ -22,7 +22,7 @@ </properties> <body> - <release version="1.3-SNAPSHOT" date="as in SVN"> + <release version="1.3" date="2010-11-05"> <action dev="sgoeschl" type="add" date="2010-11-01"> Added MimeMessageParser and MimeMessageUtils. </action> Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/ByteArrayDataSource.java URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/ByteArrayDataSource.java?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/java/org/apache/commons/mail/ByteArrayDataSource.java (original) +++ commons/proper/email/trunk/src/java/org/apache/commons/mail/ByteArrayDataSource.java Sat Nov 6 00:58:11 2010 @@ -93,7 +93,7 @@ public class ByteArrayDataSource impleme /** * Create a datasource from a String. * N.B. assumes the data string can be converted using the charset iso-8859-1 - * + * * @param data A String. * @param aType A String. * @throws IOException IOException @@ -177,8 +177,6 @@ public class ByteArrayDataSource impleme } } - - /** * Get the content type. * 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=1031900&r1=1031899&r2=1031900&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 Sat Nov 6 00:58:11 2010 @@ -164,10 +164,10 @@ public abstract class Email implements E protected boolean ssl; /** socket I/O timeout value in milliseconds */ - protected int socketTimeout = 60000; - + protected int socketTimeout = SOCKET_TIMEOUT_MS; + /** socket connection timeout value in milliseconds */ - protected int socketConnectionTimeout = 60000; + protected int socketConnectionTimeout = SOCKET_TIMEOUT_MS; /** The Session to mail with */ private Session session; @@ -1092,7 +1092,7 @@ public abstract class Email implements E { String name = (String) iterHeaderKeys.next(); String value = (String) headers.get(name); - String foldedValue = createFoldedHeaderValue(name, value); + String foldedValue = createFoldedHeaderValue(name, value); this.message.addHeader(name, foldedValue); } } @@ -1550,7 +1550,7 @@ public abstract class Email implements E /** * When a mail session is already initialized setting the * session properties has no effect. In order to flag the - * problem throw an IllegalStateException. + * problem throw an IllegalStateException. * * @throws IllegalStateException when the mail session is * already initialized 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=1031900&r1=1031899&r2=1031900&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 Sat Nov 6 00:58:11 2010 @@ -19,12 +19,17 @@ package org.apache.commons.mail; /** * Constants used by Email classes. * + * A description of the mail session parameter you find at + * <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/smtp/package-summary.html"> + * http://java.sun.com/products/javamail/javadocs/com/sun/mail/smtp/package-summary.html + * </a>. + * * @since 1.3 */ public interface EmailConstants { // Constants used by Email classes - + String SENDER_EMAIL = "sender.email"; String SENDER_NAME = "sender.name"; String RECEIVER_EMAIL = "receiver.email"; @@ -32,6 +37,8 @@ public interface EmailConstants String EMAIL_SUBJECT = "email.subject"; String EMAIL_BODY = "email.body"; String CONTENT_TYPE = "content.type"; + String ATTACHMENTS = "attachments"; + String FILE_SERVER = "file.server"; // Charset constants String KOI8_R = "koi8-r"; @@ -39,13 +46,7 @@ public interface EmailConstants String US_ASCII = "us-ascii"; String UTF_8 = "utf-8"; - String SMTP = "smtp"; - String TEXT_HTML = "text/html"; - String TEXT_PLAIN = "text/plain"; - String ATTACHMENTS = "attachments"; - String FILE_SERVER = "file.server"; String MAIL_DEBUG = "mail.debug"; - String MAIL_HOST = "mail.smtp.host"; String MAIL_PORT = "mail.smtp.port"; String MAIL_SMTP_FROM = "mail.smtp.from"; @@ -53,6 +54,10 @@ public interface EmailConstants String MAIL_SMTP_USER = "mail.smtp.user"; String MAIL_SMTP_PASSWORD = "mail.smtp.password"; String MAIL_TRANSPORT_PROTOCOL = "mail.transport.protocol"; + String SMTP = "smtp"; + String TEXT_HTML = "text/html"; + String TEXT_PLAIN = "text/plain"; + ///////////////////////////////////////////////////////////////////////// // since 1.1 @@ -78,4 +83,10 @@ public interface EmailConstants * @since 1.2 */ String MAIL_SMTP_TIMEOUT = "mail.smtp.timeout"; + + ///////////////////////////////////////////////////////////////////////// + // since 1.3 + ///////////////////////////////////////////////////////////////////////// + + int SOCKET_TIMEOUT_MS = 60000; } Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/ImageHtmlEmail.java URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/ImageHtmlEmail.java?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/java/org/apache/commons/mail/ImageHtmlEmail.java (original) +++ commons/proper/email/trunk/src/java/org/apache/commons/mail/ImageHtmlEmail.java Sat Nov 6 00:58:11 2010 @@ -25,18 +25,19 @@ import java.util.regex.Pattern; /** * Small wrapper class on top of HtmlEmail which encapsulates the required logic - * to retrieve images that are contained in "<img src=../>" elements in the HTML + * to retrieve images that are contained in "<img src=../>" elements in the HTML * code. This is done by replacing all img-src-elements with "cid:"-entries and * embedding images in the email. - * + * </br> * For local files the class tries to either load them via an absolute path or - * if available - use a relative path starting from a base directory. For files * that are not found locally, the implementation tries to download * the element and link it in. - * - * This code was submitted to commons-email under the Apache 2.0 license, see - * https://issues.apache.org/jira/browse/EMAIL-92 - * + * </br> + * The image loading is done by an instance of <code>DataSourceResolver</code> + * which has to be provided by the caller. + * </br> + * * @since 1.3 */ public class ImageHtmlEmail extends HtmlEmail @@ -64,24 +65,38 @@ public class ImageHtmlEmail extends Html /** resolve the images and script resources to a DataSource */ private DataSourceResolver dataSourceResolver; + /** + * Get the data source resolver. + * + * @return the resolver + */ public DataSourceResolver getDataSourceResolver() { return dataSourceResolver; } + /** + * Set the data source resolver. + * + * @param dataSourceResolver the resolver + */ public void setDataSourceResolver(DataSourceResolver dataSourceResolver) { this.dataSourceResolver = dataSourceResolver; } + /** + * Does the work of actually building the MimeMessage. + * + * @see org.apache.commons.mail.HtmlEmail#buildMimeMessage() + * @throws EmailException building the MimeMessage failed + */ public void buildMimeMessage() throws EmailException { - String temp; - try { // embed all the matching image and script resources within the email - temp = replacePattern(super.html, IMG_PATTERN); + String temp = replacePattern(super.html, IMG_PATTERN); temp = replacePattern(temp, SCRIPT_PATTERN); setHtmlMsg(temp); super.buildMimeMessage(); Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/impl/DataSourceResolverImpl.java URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/impl/DataSourceResolverImpl.java?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/java/org/apache/commons/mail/impl/DataSourceResolverImpl.java (original) +++ commons/proper/email/trunk/src/java/org/apache/commons/mail/impl/DataSourceResolverImpl.java Sat Nov 6 00:58:11 2010 @@ -51,7 +51,7 @@ public class DataSourceResolverImpl impl * Constructor. * * @param baseUrl the base URL used for resolving relative resource locations - * @param lenient shall we ignore resources not found or complain with an exception + * @param lenient shall we ignore resources not found or complain with an exception */ public DataSourceResolverImpl(URL baseUrl, boolean lenient) { @@ -59,11 +59,21 @@ public class DataSourceResolverImpl impl this.isLenient = lenient; } + /** + * Get the base URL used for resolving relative resource locations. + * + * @return the baseUrl + */ public URL getBaseUrl() { return baseUrl; } + /** + * Shall we ignore resources not found or throw an exception? + * + * @return the lenient flag + */ public boolean isLenient() { return isLenient; Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageParser.java URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageParser.java?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageParser.java (original) +++ commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageParser.java Sat Nov 6 00:58:11 2010 @@ -91,7 +91,7 @@ public class MimeMessageParser public Collection getTo() throws Exception { javax.mail.Address[] recipients = this.mimeMessage.getRecipients(Message.RecipientType.TO); - return (recipients != null ? Arrays.asList(recipients) : new ArrayList()); + return recipients != null ? Arrays.asList(recipients) : new ArrayList(); } /** @@ -101,7 +101,7 @@ public class MimeMessageParser public Collection getCc() throws Exception { javax.mail.Address[] recipients = this.mimeMessage.getRecipients(Message.RecipientType.CC); - return (recipients != null ? Arrays.asList(recipients) : new ArrayList()); + return recipients != null ? Arrays.asList(recipients) : new ArrayList(); } /** @@ -111,7 +111,7 @@ public class MimeMessageParser public Collection getBcc() throws Exception { javax.mail.Address[] recipients = this.mimeMessage.getRecipients(Message.RecipientType.BCC); - return (recipients != null ? Arrays.asList(recipients) : new ArrayList()); + return recipients != null ? Arrays.asList(recipients) : new ArrayList(); } /** @@ -257,19 +257,19 @@ public class MimeMessageParser /** @return true if a plain content is available */ public boolean hasPlainContent() { - return (this.plainContent != null); + return this.plainContent != null; } /** @return true if HTML content is available */ public boolean hasHtmlContent() { - return (this.htmlContent != null); + return this.htmlContent != null; } /** @return true if attachments are available */ public boolean hasAttachments() { - return (this.attachmentList.size() > 0); + return this.attachmentList.size() > 0; } /** @@ -280,7 +280,7 @@ public class MimeMessageParser */ public DataSource findAttachmentByName(String name) { - DataSource dataSource = null; + DataSource dataSource; for (int i = 0; i < getAttachmentList().size(); i++) { Modified: commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageUtils.java URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageUtils.java?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageUtils.java (original) +++ commons/proper/email/trunk/src/java/org/apache/commons/mail/util/MimeMessageUtils.java Sat Nov 6 00:58:11 2010 @@ -137,7 +137,7 @@ public final class MimeMessageUtils { is.close(); } - } + } } /** Modified: commons/proper/email/trunk/src/site/xdoc/index.xml URL: http://svn.apache.org/viewvc/commons/proper/email/trunk/src/site/xdoc/index.xml?rev=1031900&r1=1031899&r2=1031900&view=diff ============================================================================== --- commons/proper/email/trunk/src/site/xdoc/index.xml (original) +++ commons/proper/email/trunk/src/site/xdoc/index.xml Sat Nov 6 00:58:11 2010 @@ -16,87 +16,116 @@ limitations under the License. --> <document> - <properties> - <title>Home</title> - <author email="d...@commons.apache.org">Commons Documentation Team</author> - </properties> -<body> -<!-- ================================================== --> -<section name="Commons Email"> -<p> -Commons Email aims to provide a API for sending email. -It is built on top of the Java Mail API, which it aims to simplify. -</p> -<p> -Some of the mail classes that are provided are as follows: -<ul> -<li> -<b>SimpleEmail</b> - -This class is used to send basic text based emails. -</li> -<li> -<b>MultiPartEmail</b> - -This class is used to send multipart messages. -This allows a text message with attachments either inline or attached. -</li> -<li> -<b>HtmlEmail</b> - -This class is used to send HTML formatted emails. -It has all of the capabilities as MultiPartEmail allowing attachments to be easily added. -It also supports embedded images. -</li> -<li> -<b>EmailAttachment</b> - -This is a simple container class to allow for easy handling of attachments. -It is for use with instances of MultiPartEmail and HtmlEmail. -</li> -</ul> -</p> -</section> -<!-- ================================================== --> -<section name="Documentation"> -<p> -The <a href="userguide.html">Commons Email User Guide</a> covers many -typical cases and provides several useful examples. -</p> -<p> -The JavaDoc API documents are available online: -</p> -<ul> -<li>The <a href="api-release/index.html">current release 1.2</a></li> -<li>The <a href="api-1.1/index.html">previous version 1.1</a></li> -<li>The <a href="api-1.0/index.html">previous version 1.0</a></li> -<li>The <a href="apidocs/index.html">latest SVN</a></li> -</ul> -<p> -The <a href="source-repository.html">subversion repository</a> can be -<a href="http://svn.apache.org/viewvc/commons/proper/email/trunk/">browsed</a>. -</p> -</section> -<!-- ================================================== --> -<section name="Releases"> -<p> -The latest version v1.2, is JDK 1.4 compatible - -<a href="http://commons.apache.org/email/download_email.cgi">Download now!</a><br /> -The full <a href="changes-report.html">change log</a> is available -</p> -<p> -For previous releases, see the <a href="http://archive.apache.org/dist/commons/email/">Apache Archive</a>. -</p> -</section> -<!-- ================================================== --> -<section name="Support"> -<p> -The <a href="mail-lists.html">commons mailing lists</a> act as the main support forum. -The user list is suitable for most library usage queries. -The dev list is intended for the development discussion. -Please remember that the lists are shared between all commons components, -so prefix your email by [email]. -</p> -<p> -Issues may be reported via <a href="issue-tracking.html">ASF JIRA</a>. -</p> -</section> -<!-- ================================================== --> -</body> + <properties> + <title>Home</title> + <author email="d...@commons.apache.org">Commons Documentation Team</author> + </properties> + <body> + <!-- ================================================== --> + <section name="Commons Email"> + <p> + Commons Email aims to provide a API for sending email. + It is built on top of the Java Mail API, which it aims to simplify. + </p> + <p> + Some of the mail classes that are provided are as follows: + <ul> + <li> + <b>SimpleEmail</b> + - + This class is used to send basic text based emails. + </li> + <li> + <b>MultiPartEmail</b> + - + This class is used to send multipart messages. + This allows a text message with attachments either inline or attached. + </li> + <li> + <b>HtmlEmail</b> + - + This class is used to send HTML formatted emails. + It has all of the capabilities as MultiPartEmail allowing attachments to be easily added. + It also supports embedded images. + </li> + <li> + <b>ImageHtmlEmail</b> + - + This class is used to send HTML formatted emails with inline images. + It has all of the capabilities as HtmlEmail but transform all image + references to inline images. + </li> + <li> + <b>EmailAttachment</b> + - + This is a simple container class to allow for easy handling of attachments. + It is for use with instances of MultiPartEmail and HtmlEmail. + </li> + </ul> + </p> + </section> + <!-- ================================================== --> + <section name="Documentation"> + <p> + The + <a href="userguide.html">Commons Email User Guide</a> + covers many + typical cases and provides several useful examples. + </p> + <p> + The JavaDoc API documents are available online: + </p> + <ul> + <li>The + <a href="api-release/index.html">current release 1.2</a> + </li> + <li>The + <a href="api-1.1/index.html">previous version 1.1</a> + </li> + <li>The + <a href="api-1.0/index.html">previous version 1.0</a> + </li> + <li>The + <a href="apidocs/index.html">latest SVN</a> + </li> + </ul> + <p> + The + <a href="source-repository.html">subversion repository</a> + can be + <a href="http://svn.apache.org/viewvc/commons/proper/email/trunk/">browsed</a>. + </p> + </section> + <!-- ================================================== --> + <section name="Releases"> + <p> + The latest version v1.2, is JDK 1.4 compatible - + <a href="http://commons.apache.org/email/download_email.cgi">Download now!</a> + <br/> + The full + <a href="changes-report.html">change log</a> + is available + </p> + <p> + For previous releases, see the<a href="http://archive.apache.org/dist/commons/email/">Apache Archive</a> + . + </p> + </section> + <!-- ================================================== --> + <section name="Support"> + <p> + The + <a href="mail-lists.html">commons mailing lists</a> + act as the main support forum. + The user list is suitable for most library usage queries. + The dev list is intended for the development discussion. + Please remember that the lists are shared between all commons components, + so prefix your email by [email]. + </p> + <p> + Issues may be reported via<a href="issue-tracking.html">ASF JIRA</a>. + </p> + </section> + <!-- ================================================== --> + </body> </document>