JavaMail 1.5 ============ (Updated February 7, 2013) Following is a description of the changes to the JavaMail API introduced in JavaMail 1.5. The numbers in parentheses are bug numbers; you can find more information about the bug reports at: https://github.com/javaee/javamail/issues/ Please send comments and feedback to javamail_ww@oracle.com. JavaMail 1.5 will also require at least J2SE 5.0. This allows JavaMail to take advantage of features of more modern Java SE releases. =================================================================== 1. Add FetchProfile.Item.SIZE (37) ---------------------------------- The FetchProfile.Item.SIZE item allows prefetching the size of a message. Previously this was an IMAP-specific fetch item. /** * SIZE is a fetch profile item that can be included in a * FetchProfile during a fetch request to a Folder. * This item indicates that the sizes of the messages in the specified * range should be prefetched.

* * @since JavaMail 1.5 */ public static final Item SIZE; =================================================================== 2. Fix protected fields in final classes in javax.mail.search (38) ------------------------------------------------------------------ Several final classes in the javax.mail.search package contain protected fields. Since the classes are final, they can't be subclassed, and the protected fields can not be accessed. This change cleans up these fields by making them private. The following fields are changed: javax.mail.search.AndTerm: private SearchTerm[] terms; javax.mail.search.FlagTerm: private boolean set; private Flags flags; javax.mail.search.HeaderTerm: private String headerName; javax.mail.search.NotTerm: private SearchTerm term; javax.mail.search.OrTerm: private SearchTerm[] terms; javax.mail.search.RecipientTerm: private Message.RecipientType type; =================================================================== 3. Add MimeMultipart(String subtype, BodyPart... bps) constructor (39) ---------------------------------------------------------------------- These convenience constructors create a MimeMultipart object given an array or varargs list of BodyParts. /** * Construct a MimeMultipart object of the default "mixed" subtype, * and with the given body parts. More body parts may be added later. * * @since JavaMail 1.5 */ public MimeMultipart(BodyPart... parts) throws MessagingException /** * Construct a MimeMultipart object of the given subtype * and with the given body parts. More body parts may be added later. * * @since JavaMail 1.5 */ public MimeMultipart(String subtype, BodyPart... parts) throws MessagingException =================================================================== 4. Exceptions should support exception chaining (40) ---------------------------------------------------- javax.mail.MessagingException was designed before exception chainging was added to Java SE, but it does support a similar concept itself, and that support should be made available to all subclasses. javax.mail.AuthenticationFailedException: /** * Constructs an AuthenticationFailedException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param message The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public AuthenticationFailedException(String message, Exception e) javax.mail.FolderClosedException: /** * Constructs a FolderClosedException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param folder The Folder * @param message The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public FolderClosedException(Folder folder, String message, Exception e) javax.mail.FolderNotFoundException: /** * Constructs a FolderNotFoundException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param folder The Folder * @param s The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public FolderNotFoundException(Folder folder, String s, Exception e) javax.mail.IllegalWriteException: /** * Constructs an IllegalWriteException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param s The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public IllegalWriteException(String s, Exception e) javax.mail.MessageRemovedException: /** * Constructs a MessageRemovedException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param s The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public MessageRemovedException(String s, Exception e) javax.mail.MethodNotSupportedException: /** * Constructs a MethodNotSupportedException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param s The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public MethodNotSupportedException(String s, Exception e) javax.mail.NoSuchProviderException: /** * Constructs a NoSuchProviderException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param message The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public NoSuchProviderException(String message, Exception e) javax.mail.ReadOnlyFolderException: /** * Constructs a ReadOnlyFolderException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param folder The Folder * @param message The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public ReadOnlyFolderException(Folder folder, String message, Exception e) javax.mail.StoreClosedException: /** * Constructs a StoreClosedException with the specified * detail message and embedded exception. The exception is chained * to this exception. * * @param store The dead Store object * @param message The detailed error message * @param e The embedded exception * @since JavaMail 1.5 */ public StoreClosedException(Store store, String message, Exception e) =================================================================== 5. ParameterList needs to support use by IMAP (41) -------------------------------------------------- The IMAP provider has special needs when processing multi-segment parameters defined by RFC 2231. This new method supports such use by the IMAP provider. /** * Normal users of this class will use simple parameter names. * In some cases, for example, when processing IMAP protocol * messages, individual segments of a multi-segment name * (specified by RFC 2231) will be encountered and passed to * the {@link #set} method. After all these segments are added * to this ParameterList, they need to be combined to represent * the logical parameter name and value. This method will combine * all segments of multi-segment names.

* * Normal users should never need to call this method. * * @since JavaMail 1.5 */ public void combineSegments() =================================================================== 6. ContentType and ContentDisposition toString should never return null (42) ---------------------------------------------------------------------------- The general contract of Object.toString is that it never returns null. The toString methods of ContentType and ContentDisposition were defined to return null in certain error cases. Given the general toString contract it seems unlikely that anyone ever depended on these special cases, and it would be more useful for these classes to obey the general contract. These methods have been changed to return an empty string in these error cases. javax.mail.internet.ContentType: /** * Retrieve a RFC2045 style string representation of * this Content-Type. Returns an empty string if * the conversion failed. * * @return RFC2045 style string */ public String toString() javax.mail.internet.ContentDisposition: /** * Retrieve a RFC2045 style string representation of * this ContentDisposition. Returns an empty string if * the conversion failed. * * @return RFC2045 style string * @since JavaMail 1.2 */ public String toString() =================================================================== 7. Add Transport.send(msg, username, password) method (44) ---------------------------------------------------------- It's now very common that email servers require authentication before sending a message, so we add these new convenience methods. /** * Send a message. The message will be sent to all recipient * addresses specified in the message (as returned from the * Message method getAllRecipients). * The send method calls the saveChanges * method on the message before sending it.

* * Use the specified user name and password to authenticate to * the mail server. * * @param msg the message to send * @param user the user name * @param password this user's password * @exception SendFailedException if the message could not * be sent to some or any of the recipients. * @exception MessagingException * @see Message#saveChanges * @see #send(Message) * @see javax.mail.SendFailedException * @since JavaMail 1.5 */ public static void send(Message msg, String user, String password) throws MessagingException /** * Send the message to the specified addresses, ignoring any * recipients specified in the message itself. The * send method calls the saveChanges * method on the message before sending it.

* * Use the specified user name and password to authenticate to * the mail server. * * @param msg the message to send * @param addresses the addresses to which to send the message * @param user the user name * @param password this user's password * @exception SendFailedException if the message could not * be sent to some or any of the recipients. * @exception MessagingException * @see Message#saveChanges * @see #send(Message) * @see javax.mail.SendFailedException * @since JavaMail 1.5 */ public static void send(Message msg, Address[] addresses, String user, String password) throws MessagingException =================================================================== 8. Add MimeMessage.setFrom(String) method (45) ---------------------------------------------- This new convenience method allows the From header to be set using a String. /** * Set the RFC 822 "From" header field. Any existing values are * replaced with the given addresses. If address is null, * this header is removed. * * @param address the sender(s) of this message * @exception IllegalWriteException if the underlying * implementation does not support modification * of existing values * @exception IllegalStateException if this message is * obtained from a READ_ONLY folder. * @exception MessagingException * @since JvaMail 1.5 */ public void setFrom(String address) throws MessagingException =================================================================== 9. Add Message.getSesssion() method (46) ---------------------------------------- Alow access to the Session used when the Message was created. /** * Return the Session used when this message was created. * * @return the message's Session * @since JavaMail 1.5 */ public Session getSession() =================================================================== 10. MimeBodyPart.attachFile should set the disposition to ATTACHMENT (47) ------------------------------------------------------------------------- An oversight when these methods were originally added. Clearly attachments should set the disposition to ATTACHMENT. /** * Use the specified file to provide the data for this part. * The simple file name is used as the file name for this * part and the data in the file is used as the data for this * part. The encoding will be chosen appropriately for the * file data. The disposition of this part is set to * {@link Part#ATTACHMENT Part.ATTACHMENT}. * * @param file the File object to attach * @exception IOException errors related to accessing the file * @exception MessagingException message related errors * @since JavaMail 1.4 */ public void attachFile(File file) throws IOException, MessagingException /** * Use the specified file to provide the data for this part. * The simple file name is used as the file name for this * part and the data in the file is used as the data for this * part. The encoding will be chosen appropriately for the * file data. * * @param file the name of the file to attach * @exception IOException errors related to accessing the file * @exception MessagingException message related errors * @since JavaMail 1.4 */ public void attachFile(String file) throws IOException, MessagingException =================================================================== 11. Add MimeMessage.reply(replyToAll, setAnswered) method (48) -------------------------------------------------------------- Add a method to control whether the ANSWERED flag is set in the original message when creating a reply message. /** * Get a new Message suitable for a reply to this message. * The new Message will have its attributes and headers * set up appropriately. Note that this new message object * will be empty, i.e., it will not have a "content". * These will have to be suitably filled in by the client.

* * If replyToAll is set, the new Message will be addressed * to all recipients of this message. Otherwise, the reply will be * addressed to only the sender of this message (using the value * of the getReplyTo method).

* * If setAnswered is set, the * {@link javax.mail.Flags.Flag#ANSWERED ANSWERED} flag is set * in this message.

* * The "Subject" field is filled in with the original subject * prefixed with "Re:" (unless it already starts with "Re:"). * The "In-Reply-To" header is set in the new message if this * message has a "Message-Id" header. * * The current implementation also sets the "References" header * in the new message to include the contents of the "References" * header (or, if missing, the "In-Reply-To" header) in this message, * plus the contents of the "Message-Id" header of this message, * as described in RFC 2822. * * @param replyToAll reply should be sent to all recipients * of this message * @param setAnswered set the ANSWERED flag in this message? * @return the reply Message * @exception MessagingException * @since JavaMail 1.5 */ public Message reply(boolean replyToAll, boolean setAnswered) throws MessagingException =================================================================== 12. Add additional "next" methods to HeaderTokenizer (49) --------------------------------------------------------- These additional "next" methods make it easier to parse headers that don't obey the MIME syntax requirements. /** * Parses the next token from this String. * If endOfAtom is not NUL, the token extends until the * endOfAtom character is seen, or to the end of the header. * This method is useful when parsing headers that don't * obey the MIME specification, e.g., by failing to quote * parameter values that contain spaces. * * @param endOfAtom if not NUL, character marking end of token * @return the next Token * @exception ParseException if the parse fails * @since JavaMail 1.5 */ public Token next(char endOfAtom) throws ParseException /** * Parses the next token from this String. * endOfAtom is handled as above. If keepEscapes is true, * any backslash escapes are preserved in the returned string. * This method is useful when parsing headers that don't * obey the MIME specification, e.g., by failing to escape * backslashes in the filename parameter. * * @param endOfAtom if not NUL, character marking end of token * @param keepEscapes keep all backslashes in returned string? * @return the next Token * @exception ParseException if the parse fails * @since JavaMail 1.5 */ public Token next(char endOfAtom, boolean keepEscapes) throws ParseException =================================================================== 13. Add @MailSessionDefinition and @MailSessionDefinitions for Java EE 7 (51) ----------------------------------------------------------------------------- These new annotations support configuring JavaMail Session resources in Java EE 7 application servers. javax.mail.MailSessionDefinition: /** * Annotation used by Java EE applications to define a MailSession * to be registered with JNDI. The MailSession may be configured * by setting the annotation elements for commonly used Session * properties. Additional standard and vendor-specific properties may be * specified using the properties element. *

* The session will be registered under the name specified in the * name element. It may be defined to be in any valid * Java EE namespace, and will determine the accessibility of * the session from other components. * * @since JavaMail 1.5 */ @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface MailSessionDefinition { /** * Description of this mail session. */ String description() default ""; /** * JNDI name by which the mail session will be registered. */ String name(); /** * Store protocol name. */ String storeProtocol() default ""; /** * Transport protocol name. */ String transportProtocol() default ""; /** * Host name for the mail server. */ String host() default ""; /** * User name to use for authentication. */ String user() default ""; /** * Password to use for authentication. */ String password() default ""; /** * From address for the user. */ String from() default ""; /** * Properties to include in the Session. * Properties are specified using the format: * propertyName=propertyValue with one property per array element. */ String[] properties() default {}; } javax.mail.MailSessionDefinitions: import java.lang.annotation.Target; import java.lang.annotation.Retention; import java.lang.annotation.ElementType; import java.lang.annotation.RetentionPolicy; /** * Declares one or more MailSessionDefinition annotations. * * @see MailSessionDefinition * @since JavaMail 1.5 */ @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) public @interface MailSessionDefinitions { MailSessionDefinition[] value(); } =================================================================== 14. Make cachedContent field protected in MimeMessage and MimeBodyPart (52) --------------------------------------------------------------------------- Exposing this previously private field makes it easier to subclass these classes. /** * If our content is a Multipart or Message object, we save it * the first time it's created by parsing a stream so that changes * to the contained objects will not be lost.

* * If this field is not null, it's return by the {@link #getContent} * method. The {@link #getContent} method sets this field if it * would return a Multipart or MimeMessage object. This field is * is cleared by the {@link #setDataHandler} method. * * @since JavaMail 1.5 */ protected Object cachedContent; =================================================================== 15. Make MimeMultipart fields protected to allow subclassing (53) ----------------------------------------------------------------- Most of these fields control how the MimeMultipart class parses messages that don't conform to the MIME spec. The new initializeProperties method initializes these fields based on System properties. Exposing these previously private fields makes it easier to subclass MimeMultipart. /** * Have we seen the final bounary line? * * @since JavaMail 1.5 */ protected boolean complete = true; /** * The MIME multipart preamble text, the text that * occurs before the first boundary line. * * @since JavaMail 1.5 */ protected String preamble = null; /** * Flag corresponding to the "mail.mime.multipart.ignoremissingendboundary" * property, set in the {@link #initializeProperties} method called from * constructors and the parse method. * * @since JavaMail 1.5 */ protected boolean ignoreMissingEndBoundary = true; /** * Flag corresponding to the * "mail.mime.multipart.ignoremissingboundaryparameter" * property, set in the {@link #initializeProperties} method called from * constructors and the parse method. * * @since JavaMail 1.5 */ protected boolean ignoreMissingBoundaryParameter = true; /** * Flag corresponding to the * "mail.mime.multipart.ignoreexistingboundaryparameter" * property, set in the {@link #initializeProperties} method called from * constructors and the parse method. * * @since JavaMail 1.5 */ protected boolean ignoreExistingBoundaryParameter = false; /** * Flag corresponding to the "mail.mime.multipart.allowempty" * property, set in the {@link #initializeProperties} method called from * constructors and the parse method. * * @since JavaMail 1.5 */ protected boolean allowEmpty = false; /** * Initialize flags that control parsing behavior, * based on System properties described above in * the class documentation. * * @since JavaMail 1.5 */ protected void initializeProperties() The following additional System properties are defined corresponding to the last two fields above: mail.mime.multipart.ignoreexistingboundaryparameter: Normally the boundary parameter in the Content-Type header of a multipart body part is used to specify the separator between parts of the multipart body. This System property may be set to "true" to cause the parser to look for a line in the multipart body that looks like a boundary line and use that value as the separator between subsequent parts. This may be useful in cases where a broken anti-virus product has rewritten the message incorrectly such that the boundary parameter and the actual boundary value no longer match. The default value of this property is false. mail.mime.multipart.allowempty: Normally, when writing out a MimeMultipart that contains no body parts, or when trying to parse a multipart message with no body parts, a MessagingException is thrown. The MIME spec does not allow multipart content with no body parts. This System property may be set to "true" to override this behavior. When writing out such a MimeMultipart, a single empty part will be included. When reading such a multipart, a MimeMultipart will be created with no body parts. The default value of this property is false. =================================================================== 16. Need simple way to override MIME type and encoding of attachment (55) ------------------------------------------------------------------------- First, we define an interface that allows a DataSource to specify the Content-Transfer-Encoding to use: package javax.mail; /** * A {@link javax.activation.DataSource DataSource} that also implements * EncodingAware may specify the Content-Transfer-Encoding * to use for its data. Valid Content-Transfer-Encoding values specified * by RFC 2045 are "7bit", "8bit", "quoted-printable", "base64", and "binary". *

* For example, a {@link javax.activation.FileDataSource FileDataSource} * could be created that forces all files to be base64 encoded:

* 

 *  public class Base64FileDataSource extends FileDataSource
 *					implements EncodingAware {
 *	public Base64FileDataSource(File file) {
 *	    super(file);
 *	}
 *
 *	// implements EncodingAware.getEncoding()
 *	public String getEncoding() {
 *	    return "base64";
 *	}
 *  }
 *

* * @since JavaMail 1.5 * @author Bill Shannon */ public interface EncodingAware { /** * Return the MIME Content-Transfer-Encoding to use for this data, * or null to indicate that an appropriate value should be chosen * by the caller. * * @return the Content-Transfer-Encoding value, or null */ public String getEncoding(); } Then we add new methods to MimeBodyPart: /** * Use the specified file with the specified Content-Type and * Content-Transfer-Encoding to provide the data for this part. * If contentType or encoding are null, appropriate values will * be chosen. * The simple file name is used as the file name for this * part and the data in the file is used as the data for this * part. The disposition of this part is set to * {@link Part#ATTACHMENT Part.ATTACHMENT}. * * @param file the File object to attach * @param contentType the Content-Type, or null * @param encoding the Content-Transfer-Encoding, or null * @exception IOException errors related to accessing the file * @exception MessagingException message related errors * @since JavaMail 1.5 */ public void attachFile(File file, String contentType, String encoding) throws IOException, MessagingException /** * Use the specified file with the specified Content-Type and * Content-Transfer-Encoding to provide the data for this part. * If contentType or encoding are null, appropriate values will * be chosen. * The simple file name is used as the file name for this * part and the data in the file is used as the data for this * part. The disposition of this part is set to * {@link Part#ATTACHMENT Part.ATTACHMENT}. * * @param file the name of the file * @param contentType the Content-Type, or null * @param encoding the Content-Transfer-Encoding, or null * @exception IOException errors related to accessing the file * @exception MessagingException message related errors * @since JavaMail 1.5 */ public void attachFile(String file, String contentType, String encoding) throws IOException, MessagingException =================================================================== 17. Enable RFC 2231 support by default (56) ------------------------------------------- RFC 2231 support for encoded parameter values is now widely implemented, it's time to change the default to support this standard. Given the way RFC 2231 is defined, it's extremely unlikely that this would cause compatibility problems with existing applications. The System properties mail.mime.decodeparameters and mail.mime.encodeparameters now default to true instead of false.