diff --git a/WHATSNEW b/WHATSNEW
index d30464dfb..a7f77d27a 100644
--- a/WHATSNEW
+++ b/WHATSNEW
@@ -99,6 +99,8 @@ Other changes:
* ant -diagnostics lists contents of ${user.home}/.ant/lib
+* mail task accepts nested header element. Bugzilla report 24713.
+
Changes from Ant 1.6.2 to current Ant 1.6 CVS version
=====================================================
diff --git a/docs/manual/CoreTasks/mail.html b/docs/manual/CoreTasks/mail.html
index 986b33937..e61590b1d 100644
--- a/docs/manual/CoreTasks/mail.html
+++ b/docs/manual/CoreTasks/mail.html
@@ -212,6 +212,31 @@ inside the <message> element. Property expansion will occur
in the message, whether it is specified as an external file or as text within
the <message> element.
+header
+Since Ant 1.7, arbitrary mail headers can be added by
+ specifying these attributes on one or more nested header elements:
+
+
+
+ | Attribute |
+ Description |
+ Required |
+
+
+ | name |
+ The name associated with this mail header. |
+ Yes |
+
+
+ | value |
+ The value to assign to this mail header. |
+ Yes |
+
+
+
+It is permissible to duplicate the name attribute amongst multiple headers.
+
+
Examples
@@ -259,7 +284,7 @@ will be replaced with the buildname property's value.
Test Build, the message body being coded in UTF-8
-Copyright © 2000-2004 The Apache Software Foundation. All rights
+
Copyright © 2000-2005 The Apache Software Foundation. All rights
Reserved.
diff --git a/src/main/org/apache/tools/ant/taskdefs/email/EmailTask.java b/src/main/org/apache/tools/ant/taskdefs/email/EmailTask.java
index a1d731e50..c7995435e 100644
--- a/src/main/org/apache/tools/ant/taskdefs/email/EmailTask.java
+++ b/src/main/org/apache/tools/ant/taskdefs/email/EmailTask.java
@@ -1,5 +1,5 @@
/*
- * Copyright 2000-2004 The Apache Software Foundation
+ * Copyright 2000-2005 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -16,12 +16,11 @@
*/
package org.apache.tools.ant.taskdefs.email;
-// Ant imports
-
import java.io.File;
+import java.util.Vector;
import java.util.Enumeration;
import java.util.StringTokenizer;
-import java.util.Vector;
+
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.DirectoryScanner;
import org.apache.tools.ant.Project;
@@ -36,8 +35,7 @@ import org.apache.tools.ant.types.FileSet;
* @since Ant 1.5
* @ant.task name="mail" category="network"
*/
-public class EmailTask
- extends Task {
+public class EmailTask extends Task {
/** Constant to show that the best available mailer should be used. */
public static final String AUTO = "auto";
/** Constant to allow the Mime mailer to be requested */
@@ -47,9 +45,8 @@ public class EmailTask
/** Constant to allow the plaintext mailer to be requested */
public static final String PLAIN = "plain";
-
/**
- * Enumerates the encoding constants
+ * Enumerates the encoding constants.
*/
public static class Encoding extends EnumeratedAttribute {
/**
@@ -74,7 +71,7 @@ public class EmailTask
private boolean failOnError = true;
private boolean includeFileNames = false;
private String messageMimeType = null;
- /** special headers */
+ /* special headers */
/** sender */
private EmailAddress from = null;
/** replyto */
@@ -86,6 +83,9 @@ public class EmailTask
/** BCC (Blind Carbon Copy) recipients */
private Vector bccList = new Vector();
+ /** generic headers */
+ private Vector headers = new Vector();
+
/** file list */
private Vector files = new Vector();
private Vector filesets = new Vector();
@@ -99,64 +99,61 @@ public class EmailTask
private boolean SSL = false;
/**
- * sets the user for SMTP auth; this requires JavaMail
- * @param user
- * @since ant 1.6
+ * Set the user for SMTP auth; this requires JavaMail.
+ * @param user the String username.
+ * @since Ant 1.6
*/
public void setUser(String user) {
this.user = user;
}
/**
- * sets the password for SMTP auth; this requires JavaMail
- * @param password
- * @since ant 1.6
+ * Set the password for SMTP auth; this requires JavaMail.
+ * @param password the String password.
+ * @since Ant 1.6
*/
public void setPassword(String password) {
this.password = password;
}
/**
- * tells if the user needs to send his data over SSL
- * @param SSL
- * @since ant 1.6
+ * Set whether to send data over SSL.
+ * @param SSL boolean; if true SSL will be used.
+ * @since Ant 1.6
*/
public void setSSL(boolean SSL) {
this.SSL = SSL;
}
/**
- * Allows the build writer to choose the preferred encoding method
+ * Set the preferred encoding method.
*
- * @param encoding The encoding (one of AUTO,MIME,UU,PLAIN)
+ * @param encoding The encoding (one of AUTO, MIME, UU, PLAIN).
*/
public void setEncoding(Encoding encoding) {
this.encoding = encoding.getValue();
}
-
/**
- * Sets the mail server port
+ * Set the mail server port.
*
- * @param port The port to use
+ * @param port The port to use.
*/
public void setMailport(int port) {
this.port = port;
}
-
/**
- * Sets the host
+ * Set the host.
*
- * @param host The host to connect to
+ * @param host The host to connect to.
*/
public void setMailhost(String host) {
this.host = host;
}
-
/**
- * Sets the subject line of the email
+ * Set the subject line of the email.
*
* @param subject Subject of this email.
*/
@@ -164,9 +161,8 @@ public class EmailTask
this.subject = subject;
}
-
/**
- * Shorthand method to set the message
+ * Shorthand method to set the message.
*
* @param message Message body of this email.
*/
@@ -175,120 +171,105 @@ public class EmailTask
throw new BuildException("Only one message can be sent in an "
+ "email");
}
-
this.message = new Message(message);
this.message.setProject(getProject());
}
-
/**
- * Shorthand method to set the message from a file
+ * Shorthand method to set the message from a file.
*
- * @param file The file from which to take the message
+ * @param file The file from which to take the message.
*/
public void setMessageFile(File file) {
if (this.message != null) {
throw new BuildException("Only one message can be sent in an "
+ "email");
}
-
this.message = new Message(file);
this.message.setProject(getProject());
}
-
/**
* Shorthand method to set type of the text message, text/plain by default
* but text/html or text/xml is quite feasible.
*
- * @param type The new MessageMimeType value
+ * @param type The new MessageMimeType value.
*/
public void setMessageMimeType(String type) {
this.messageMimeType = type;
}
-
/**
- * Add a message element
+ * Add a message element.
*
- * @param message The message object
- * @throws BuildException if a message has already been added
+ * @param message The message object.
+ * @throws BuildException if a message has already been added.
*/
- public void addMessage(Message message)
- throws BuildException {
+ public void addMessage(Message message) throws BuildException {
if (this.message != null) {
- throw new BuildException("Only one message can be sent in an "
- + "email");
+ throw new BuildException(
+ "Only one message can be sent in an email");
}
-
this.message = message;
}
-
/**
- * Adds a from address element
+ * Add a from address element.
*
- * @param address The address to send from
+ * @param address The address to send from.
*/
public void addFrom(EmailAddress address) {
if (this.from != null) {
throw new BuildException("Emails can only be from one address");
}
-
this.from = address;
}
-
/**
- * Shorthand to set the from address element
+ * Shorthand to set the from address element.
*
- * @param address The address to send mail from
+ * @param address The address to send mail from.
*/
public void setFrom(String address) {
if (this.from != null) {
throw new BuildException("Emails can only be from one address");
}
-
this.from = new EmailAddress(address);
}
-
/**
- * Adds a replyto address element
+ * Add a replyto address element.
*
- * @param address The address to reply to
- * @since ant 1.6
+ * @param address The address to reply to.
+ * @since Ant 1.6
*/
public void addReplyTo(EmailAddress address) {
this.replyToList.add(address);
}
-
/**
- * Shorthand to set the replyto address element
+ * Shorthand to set the replyto address element.
*
- * @param address The address to which replies should be directed
- * @since ant 1.6
+ * @param address The address to which replies should be directed.
+ * @since Ant 1.6
*/
public void setReplyTo(String address) {
this.replyToList.add(new EmailAddress(address));
}
-
/**
- * Adds a to address element
+ * Add a to address element.
*
- * @param address An email address
+ * @param address An email address.
*/
public void addTo(EmailAddress address) {
toList.addElement(address);
}
-
/**
- * Adds "to" address elements
+ * Shorthand to set the "to" address element.
*
- * @param list Comma separated list of addresses
+ * @param list Comma-separated list of addresses.
*/
public void setToList(String list) {
StringTokenizer tokens = new StringTokenizer(list, ",");
@@ -298,21 +279,19 @@ public class EmailTask
}
}
-
/**
- * Adds "cc" address element
+ * Add a "cc" address element.
*
- * @param address The email address
+ * @param address The email address.
*/
public void addCc(EmailAddress address) {
ccList.addElement(address);
}
-
/**
- * Adds "cc" address elements
+ * Shorthand to set the "cc" address element.
*
- * @param list Comma separated list of addresses
+ * @param list Comma separated list of addresses.
*/
public void setCcList(String list) {
StringTokenizer tokens = new StringTokenizer(list, ",");
@@ -322,21 +301,19 @@ public class EmailTask
}
}
-
/**
- * Adds "bcc" address elements
+ * Add a "bcc" address element.
*
- * @param address The email address
+ * @param address The email address.
*/
public void addBcc(EmailAddress address) {
bccList.addElement(address);
}
-
/**
- * Adds "bcc" address elements
+ * Shorthand to set the "bcc" address element.
*
- * @param list comma separated list of addresses
+ * @param list comma separated list of addresses.
*/
public void setBccList(String list) {
StringTokenizer tokens = new StringTokenizer(list, ",");
@@ -346,21 +323,19 @@ public class EmailTask
}
}
-
/**
- * Indicates whether BuildExceptions should be passed back to the core
+ * Set whether BuildExceptions should be passed back to the core.
*
- * @param failOnError The new FailOnError value
+ * @param failOnError The new FailOnError value.
*/
public void setFailOnError(boolean failOnError) {
this.failOnError = failOnError;
}
-
/**
- * Adds a list of files to be attached
+ * Set the list of files to be attached.
*
- * @param filenames Comma separated list of files
+ * @param filenames Comma-separated list of files.
*/
public void setFiles(String filenames) {
StringTokenizer t = new StringTokenizer(filenames, ", ");
@@ -370,39 +345,47 @@ public class EmailTask
}
}
-
/**
- * Adds a set of files (nested fileset attribute).
+ * Add a set of files (nested fileset attribute).
*
- * @param fs The fileset
+ * @param fs The fileset.
*/
public void addFileset(FileSet fs) {
filesets.addElement(fs);
}
+ /**
+ * Create a nested header element.
+ * @return a Header instance.
+ */
+ public Header createHeader() {
+ Header h = new Header();
+ headers.add(h);
+ return h;
+ }
/**
- * Sets Includefilenames attribute
+ * Set whether to include filenames.
*
* @param includeFileNames Whether to include filenames in the text of the
- * message
+ * message.
*/
public void setIncludefilenames(boolean includeFileNames) {
this.includeFileNames = includeFileNames;
}
-
/**
- * Identifies whether file names should be included
+ * Get whether file names should be included.
*
- * @return Identifies whether file names should be included
+ * @return Identifies whether file names should be included.
*/
public boolean getIncludeFileNames() {
return includeFileNames;
}
-
- /** Sends an email */
+ /**
+ * Send an email.
+ */
public void execute() {
Message savedMessage = message;
Vector savedFiles = (Vector) files.clone();
@@ -416,8 +399,8 @@ public class EmailTask
if (encoding.equals(MIME)
|| (encoding.equals(AUTO) && !autoFound)) {
try {
- mailer =
- (Mailer) Class.forName("org.apache.tools.ant.taskdefs.email.MimeMailer")
+ mailer = (Mailer) Class.forName(
+ "org.apache.tools.ant.taskdefs.email.MimeMailer")
.newInstance();
autoFound = true;
log("Using MIME mail", Project.MSG_VERBOSE);
@@ -436,8 +419,6 @@ public class EmailTask
&& (encoding.equals(UU) || encoding.equals(PLAIN))) {
throw new BuildException("SSL only possible with MIME mail");
}
-
-
// try UU format
if (encoding.equals(UU)
|| (encoding.equals(AUTO) && !autoFound)) {
@@ -451,7 +432,6 @@ public class EmailTask
log("Failed to initialise UU mail", Project.MSG_WARN);
}
}
-
// try plain format
if (encoding.equals(PLAIN)
|| (encoding.equals(AUTO) && !autoFound)) {
@@ -459,49 +439,41 @@ public class EmailTask
autoFound = true;
log("Using plain mail", Project.MSG_VERBOSE);
}
-
// a valid mailer must be present by now
if (mailer == null) {
throw new BuildException("Failed to initialise encoding: "
+ encoding);
}
-
// a valid message is required
if (message == null) {
message = new Message();
message.setProject(getProject());
}
-
// an address to send from is required
if (from == null || from.getAddress() == null) {
throw new BuildException("A from element is required");
}
-
// at least one address to send to/cc/bcc is required
if (toList.isEmpty() && ccList.isEmpty() && bccList.isEmpty()) {
- throw new BuildException("At least one of to,cc or bcc must "
+ throw new BuildException("At least one of to, cc or bcc must "
+ "be supplied");
}
-
// set the mimetype if not done already (and required)
if (messageMimeType != null) {
if (message.isMimeTypeSpecified()) {
throw new BuildException("The mime type can only be "
+ "specified in one location");
- } else {
- message.setMimeType(messageMimeType);
}
+ message.setMimeType(messageMimeType);
}
// set the character set if not done already (and required)
if (charset != null) {
if (message.getCharset() != null) {
throw new BuildException("The charset can only be "
+ "specified in one location");
- } else {
- message.setCharset(charset);
}
+ message.setCharset(charset);
}
-
// identify which files should be attached
Enumeration e = filesets.elements();
@@ -513,12 +485,9 @@ public class EmailTask
File baseDir = ds.getBasedir();
for (int j = 0; j < includedFiles.length; ++j) {
- File file = new File(baseDir, includedFiles[j]);
-
- files.addElement(file);
+ files.addElement(new File(baseDir, includedFiles[j]));
}
}
-
// let the user know what's going to happen
log("Sending email: " + subject, Project.MSG_INFO);
log("From " + from, Project.MSG_VERBOSE);
@@ -543,6 +512,7 @@ public class EmailTask
mailer.setSubject(subject);
mailer.setTask(this);
mailer.setIncludeFileNames(includeFileNames);
+ mailer.setHeaders(headers);
// send the email
mailer.send();
@@ -567,15 +537,17 @@ public class EmailTask
files = savedFiles;
}
}
+
/**
* Sets the character set of mail message.
* Will be ignored if mimeType contains ....; Charset=... substring or
- * encoding is not a