JavaMail 1.6 ============ (Updated July 17, 2017) Following is a description of the changes to the JavaMail API introduced in JavaMail 1.6. 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.6 will also require at least Java SE 7. =================================================================== 1. MailSessionDefinition should use Repeatable annotation for Java EE 8 (226) ----------------------------------------------------------------------------- The MailSessionDefinition annotation now includes the Repeatable annotation: @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Repeatable(MailSessionDefinitions.class) public @interface MailSessionDefinition { ... } The Repeatable annotation is not known to Java SE 7 and will be ignored (as expected) when JavaMail 1.6 is used on Java SE 7. =================================================================== 2. MimeMessage.updateHeaders should set Date header if not already set (77) --------------------------------------------------------------------------- RFC 2822 requires a Date header. The MimeMessage.updateHeaders method now sets the Date header if it's not already set: /** * Called by the saveChanges method to actually * update the MIME headers. The implementation here sets the * Content-Transfer-Encoding header (if needed * and not already set), the Date header (if * not already set), the MIME-Version header * and the Message-ID header. Also, if the content * of this message is a MimeMultipart, its * updateHeaders method is called.

* * If the {@link #cachedContent} field is not null (that is, * it references a Multipart or Message object), then * that object is used to set a new DataHandler, any * stream data used to create this object is discarded, * and the {@link #cachedContent} field is cleared. * * @exception IllegalWriteException if the underlying * implementation does not support modification * @exception IllegalStateException if this message is * obtained from a READ_ONLY folder. * @exception MessagingException for other failures */ protected synchronized void updateHeaders() throws MessagingException { ... } =================================================================== 3. Update public API to use generics (232) ------------------------------------------ Methods on the following APIs have been updated to use generics when appropriate: javax.mail.Multipart javax.mail.Part javax.mail.Service javax.mail.internet.InternetHeaders javax.mail.internet.MimeBodyPart javax.mail.internet.MimeMessage javax.mail.internet.MimePart javax.mail.internet.ParameterList Details follow: diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/Multipart.java - a/mail/src/main/java/javax/mail/Multipart.java +++ b/mail/src/main/java/javax/mail/Multipart.java @@ -72,2 +72,1 @@ - @SuppressWarnings("rawtypes") - protected Vector parts = new Vector(); // Holds BodyParts + protected Vector parts = new Vector<>(); // Holds BodyParts diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/Part.java - a/mail/src/main/java/javax/mail/Part.java +++ b/mail/src/main/java/javax/mail/Part.java @@ -452,2 +452,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaders() throws MessagingException; + public Enumeration

getAllHeaders() throws MessagingException; @@ -463,2 +462,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getMatchingHeaders(String[] header_names) + public Enumeration
getMatchingHeaders(String[] header_names) @@ -475,2 +473,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNonMatchingHeaders(String[] header_names) + public Enumeration
getNonMatchingHeaders(String[] header_names) diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/Service.java - a/mail/src/main/java/javax/mail/Service.java +++ b/mail/src/main/java/javax/mail/Service.java @@ -640,2 +640,2 @@ - @SuppressWarnings("rawtypes") - protected void queueEvent(MailEvent event, Vector vector) { + protected void queueEvent(MailEvent event, + Vector vector) { diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/InternetHeaders.java - a/mail/src/main/java/javax/mail/internet/InternetHeaders.java +++ b/mail/src/main/java/javax/mail/internet/InternetHeaders.java @@ -300,2 +300,1 @@ - @SuppressWarnings("rawtypes") - protected List headers; + protected List headers; @@ -589,2 +585,1 @@ - @SuppressWarnings({"rawtypes", "unchecked"}) - public Enumeration getAllHeaders() { + public Enumeration
getAllHeaders() { @@ -600,2 +595,1 @@ - @SuppressWarnings({"rawtypes", "unchecked"}) - public Enumeration getMatchingHeaders(String[] names) { + public Enumeration
getMatchingHeaders(String[] names) { @@ -611,2 +605,1 @@ - @SuppressWarnings({"rawtypes", "unchecked"}) - public Enumeration getNonMatchingHeaders(String[] names) { + public Enumeration
getNonMatchingHeaders(String[] names) { @@ -649,2 +640,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaderLines() { + public Enumeration getAllHeaderLines() { @@ -660,2 +650,1 @@ - @SuppressWarnings({"rawtypes", "unchecked"}) - public Enumeration getMatchingHeaderLines(String[] names) { + public Enumeration getMatchingHeaderLines(String[] names) { @@ -671,2 +660,1 @@ - @SuppressWarnings({"rawtypes", "unchecked"}) - public Enumeration getNonMatchingHeaderLines(String[] names) { + public Enumeration getNonMatchingHeaderLines(String[] names) { diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/MimeBodyPart.java - a/mail/src/main/java/javax/mail/internet/MimeBodyPart.java +++ b/mail/src/main/java/javax/mail/internet/MimeBodyPart.java @@ -1036,2 +1036,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaders() throws MessagingException { + public Enumeration
getAllHeaders() throws MessagingException { @@ -1045,2 +1044,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getMatchingHeaders(String[] names) + public Enumeration
getMatchingHeaders(String[] names) @@ -1055,2 +1053,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNonMatchingHeaders(String[] names) + public Enumeration
getNonMatchingHeaders(String[] names) @@ -1073,2 +1070,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaderLines() throws MessagingException { + public Enumeration getAllHeaderLines() throws MessagingException { @@ -1083,2 +1079,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getMatchingHeaderLines(String[] names) + public Enumeration getMatchingHeaderLines(String[] names) @@ -1094,2 +1089,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNonMatchingHeaderLines(String[] names) + public Enumeration getNonMatchingHeaderLines(String[] names) diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/MimeMessage.java - a/mail/src/main/java/javax/mail/internet/MimeMessage.java +++ b/mail/src/main/java/javax/mail/internet/MimeMessage.java @@ -1992,2 +1991,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaders() throws MessagingException { + public Enumeration
getAllHeaders() throws MessagingException { @@ -2004,2 +2002,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getMatchingHeaders(String[] names) + public Enumeration
getMatchingHeaders(String[] names) @@ -2017,2 +2014,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNonMatchingHeaders(String[] names) + public Enumeration
getNonMatchingHeaders(String[] names) @@ -2043,2 +2039,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaderLines() throws MessagingException { + public Enumeration getAllHeaderLines() throws MessagingException { @@ -2055,2 +2050,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getMatchingHeaderLines(String[] names) + public Enumeration getMatchingHeaderLines(String[] names) @@ -2068,2 +2062,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNonMatchingHeaderLines(String[] names) + public Enumeration getNonMatchingHeaderLines(String[] names) diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/MimePart.java - a/mail/src/main/java/javax/mail/internet/MimePart.java +++ b/mail/src/main/java/javax/mail/internet/MimePart.java @@ -111,2 +111,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getAllHeaderLines() throws MessagingException; + public Enumeration getAllHeaderLines() throws MessagingException; @@ -123,2 +122,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getMatchingHeaderLines(String[] names) + public Enumeration getMatchingHeaderLines(String[] names) @@ -136,2 +134,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNonMatchingHeaderLines(String[] names) + public Enumeration getNonMatchingHeaderLines(String[] names) diff -r 1f6b2c17e291 mail/src/main/java/javax/mail/internet/ParameterList.java - a/mail/src/main/java/javax/mail/internet/ParameterList.java +++ b/mail/src/main/java/javax/mail/internet/ParameterList.java @@ -627,2 +627,1 @@ - @SuppressWarnings("rawtypes") - public Enumeration getNames() { + public Enumeration getNames() { =================================================================== 4. MailDateFormat changes for version 1.6 (174) ----------------------------------------------- The parse(String) method currently returns null for invalid dates, which violates the contract of DateFormat. It should throw ParseException. Some methods of MailDateFormat throw UnsupportedOperationException. The following methods should also do so: /** * This method always throws an UnsupportedOperationException and * should not be used because RFC 2822 mandates a specific pattern. * * @throws UnsupportedOperationException if this method is invoked * @since JavaMail 1.6 */ @Override public void applyLocalizedPattern(String pattern) { throw new UnsupportedOperationException("Method " + "applyLocalizedPattern() shouldn't be called"); } /** * This method always throws an UnsupportedOperationException and * should not be used because RFC 2822 mandates a specific pattern. * * @throws UnsupportedOperationException if this method is invoked * @since JavaMail 1.6 */ @Override public void applyPattern(String pattern) { throw new UnsupportedOperationException("Method " + "applyPattern() shouldn't be called"); } /** * This method always throws an UnsupportedOperationException and * should not be used because RFC 2822 mandates another strategy * for interpreting 2-digits years. * * @return the start of the 100-year period into which two digit * years are parsed * @throws UnsupportedOperationException if this method is invoked * @since JavaMail 1.6 */ @Override public Date get2DigitYearStart() { throw new UnsupportedOperationException("Method " + "get2DigitYearStart() shouldn't be called"); } /** * This method always throws an UnsupportedOperationException and * should not be used because RFC 2822 mandates another strategy * for interpreting 2-digits years. * * @throws UnsupportedOperationException if this method is invoked * @since JavaMail 1.6 */ @Override public void set2DigitYearStart(Date startDate) { throw new UnsupportedOperationException("Method " + "set2DigitYearStart() shouldn't be called"); } /** * This method always throws an UnsupportedOperationException and * should not be used because RFC 2822 mandates specific date * format symbols. * * @throws UnsupportedOperationException if this method is invoked * @since JavaMail 1.6 */ @Override public void setDateFormatSymbols(DateFormatSymbols newFormatSymbols) { throw new UnsupportedOperationException("Method " + "setDateFormatSymbols() shouldn't be called"); } MailDateFormat should include a proper clone method: /** * Overrides Cloneable. * * @return a clone of this instance * @since JavaMail 1.6 */ @Override public MailDateFormat clone() { return (MailDateFormat) super.clone(); } =================================================================== 5. Store, Transport, and Folder should implement AutoCloseable (159) -------------------------------------------------------------------- To enable use in a try-with-resources block, the Store, Transport, and Folder classes should implement the java.lang.AutoCloseable interface. Store and Transport are subclasses of Service, which already has the required close() method, so having Service implement AutoCloseable is sufficient. The Folder class includes a close method with a required "expunge" parameter so we add a new close() method with no parameter that behaves the same as close(true), and have Folder implement AutoCloseable. public abstract class Service implements AutoCloseable { ... } public abstract class Folder implements AutoCloseable { ... /** * Close this Folder and expunge deleted messages.

* * A CLOSED ConnectionEvent is delivered to any ConnectionListeners * registered on this Folder. Note that the folder is closed even * if this method terminates abnormally by throwing a * MessagingException.

* * This method supports the {@link java.lang.AutoCloseable AutoCloseable} * interface.

* * This implementation calls close(true). * * @exception IllegalStateException if this folder is not opened * @exception MessagingException for other failures * @see javax.mail.event.ConnectionEvent * @since JavaMail 1.6 */ @Override public void close() throws MessagingException { close(true); } } =================================================================== 6. The UIDFolder interface should have a getter for UIDNEXT (104) ----------------------------------------------------------------- The UIDFolder interface models the UID support in the IMAP protocol. After UIDFolder was originally created, the IMAP protocol added support for getting the value of the next UID that will be assigned. The IMAP provider in JavaMail has supported this for quite some time; it should be added to the UIDFolder interface: /** * Returns the predicted UID that will be assigned to the * next message that is appended to this folder. * Messages might be appended to the folder after this value * is retrieved, causing this value to be out of date. * This value might only be updated when a folder is first opened. * Note that messages may have been appended to the folder * while it was open and thus this value may be out of * date.

* * If the value is unknown, -1 is returned.

* * @return the UIDNEXT value, or -1 if unknown * @exception MessagingException for failures * @since JavaMail 1.6 */ public long getUIDNext() throws MessagingException; Ideally this new method added to the interface would include a default implementation to provide compatibility with existing classes that implement this method. However, since the JavaMail 1.6 reference implementation targets Java SE 7, this is not possible. It's very likely that the only class implementing this interface is the IMAPFolder class in the JavaMail reference implementation, thus this incompatibility is extremely unlikely to cause a problem in practice. =================================================================== 7. The UIDFolder interface should have a MAXUID constant (244) -------------------------------------------------------------- An IMAP UID is a 32-bit unsigned integer and is represented as a Java long. A new constant indicates the maximum value of a UID: /** * The largest value possible for a UID, a 32-bit unsigned integer. * This can be used to fetch all new messages by keeping track of the * last UID that was seen and using: * 

	 *
	 * 	Folder f = store.getFolder("whatever");
	 *	UIDFolder uf = (UIDFolder)f;
	 *	Message[] newMsgs =
	 *		uf.getMessagesByUID(lastSeenUID + 1, UIDFolder.MAXUID);
	 *
	 *

* * @since JavaMail 1.6 */ public static final long MAXUID = 0xffffffffL; =================================================================== 8. MimeMultipart should throw ParseException for parsing errors (75) -------------------------------------------------------------------- ParseException indicates an error parsing MIME messages. In addition to applying to MIME headers, it seems reasonable to expand it to cover multipart message parsing. Since ParseException is a subclass of MessagingException, it merely reports more precisely the cause of the error. The description of ParseException is changed to: * The exception thrown due to an error in parsing RFC822 * or MIME headers, including multipart bodies. MimeMultipart documents that ParseException can be thrown from an existing constructor and method: /** * Constructs a MimeMultipart object and its bodyparts from the * given DataSource.

* * This constructor handles as a special case the situation where the * given DataSource is a MultipartDataSource object. In this case, this * method just invokes the superclass (i.e., Multipart) constructor * that takes a MultipartDataSource object.

* * Otherwise, the DataSource is assumed to provide a MIME multipart * byte stream. The parsed flag is set to false. When * the data for the body parts are needed, the parser extracts the * "boundary" parameter from the content type of this DataSource, * skips the 'preamble' and reads bytes till the terminating * boundary and creates MimeBodyParts for each part of the stream. * * @param ds DataSource, can be a MultipartDataSource * @exception ParseException for failures parsing the message * @exception MessagingException for other failures */ public MimeMultipart(DataSource ds) throws MessagingException ... /** * Parse the InputStream from our DataSource, constructing the * appropriate MimeBodyParts. The parsed flag is * set to true, and if true on entry nothing is done. This * method is called by all other methods that need data for * the body parts, to make sure the data has been parsed. * The {@link #initializeProperties} method is called before * parsing the data. * * @exception ParseException for failures parsing the message * @exception MessagingException for other failures * @since JavaMail 1.2 */ protected synchronized void parse() throws MessagingException =================================================================== 9. Support addressing i18n via RFC 6530/6531/6532 (93) ------------------------------------------------------ To enable support for UTF-8 email addresses, the following methods are added to InternetAddress: /** * Convert the given array of InternetAddress objects into * a comma separated sequence of address strings. The * resulting string contains Unicode characters.

* * @param addresses array of InternetAddress objects * @exception ClassCastException if any address object in the * given array is not an InternetAddress object. * Note that this is a RuntimeException. * @return comma separated string of addresses * @since JavaMail 1.6 */ public static String toUnicodeString(Address[] addresses) /** * Convert the given array of InternetAddress objects into * a comma separated sequence of address strings. The * resulting string contains Unicode characters.

* * The 'used' parameter specifies the number of character positions * already taken up in the field into which the resulting address * sequence string is to be inserted. It is used to determine the * line-break positions in the resulting address sequence string. * * @param addresses array of InternetAddress objects * @param used number of character positions already used, in * the field into which the address string is to * be inserted. * @exception ClassCastException if any address object in the * given array is not an InternetAddress object. * Note that this is a RuntimeException. * @return comma separated string of addresses * @since JavaMail 1.6 */ public static String toUnicodeString(Address[] addresses, int used) The following constructor and method are added to InternetHeaders: /** * Read and parse the given RFC822 message stream till the * blank line separating the header from the body. The input * stream is left positioned at the start of the body. The * header lines are stored internally.

* * For efficiency, wrap a BufferedInputStream around the actual * input stream and pass it as the parameter.

* * No placeholder entries are inserted; the original order of * the headers is preserved. * * @param is RFC822 input stream * @param allowutf8 if UTF-8 encoded headers are allowed * @exception MessagingException for any I/O error reading the stream * @since JavaMail 1.6 */ public InternetHeaders(InputStream is, boolean allowutf8) throws MessagingException /** * Read and parse the given RFC822 message stream till the * blank line separating the header from the body. Store the * header lines inside this InternetHeaders object. The order * of header lines is preserved.

* * Note that the header lines are added into this InternetHeaders * object, so any existing headers in this object will not be * affected. Headers are added to the end of the existing list * of headers, in order. * * @param is RFC822 input stream * @param allowutf8 if UTF-8 encoded headers are allowed * @exception MessagingException for any I/O error reading the stream * @since JavaMail 1.6 */ public void load(InputStream is, boolean allowutf8) throws MessagingException The following Session property can be set to enable implicit use of these new methods: mail.mime.allowutf8: If set to "true", UTF-8 strings are allowed in message headers, e.g., in addresses. This should only be set if the mail server also supports UTF-8. =================================================================== 10. Look for resource files in /conf on JDK 1.9 (247) ---------------------------------------------------------------- JDK 1.9 adds a new /conf directory to hold configuration files that were previously stored in /lib. When using JavaMail on JDK 1.9, it should look for its (optional) configuration files in the /conf directory. The specification of the Session class is changed as follows: /** * The Session class represents a mail session and is not subclassed. * It collects together properties and defaults used by the mail API's. * A single default session can be shared by multiple applications on * the desktop. Unshared sessions can also be created.

* * The Session class provides access to the protocol providers that * implement the Store, Transport, and related * classes. The protocol providers are configured using the following * files: *

    *
  • javamail.providers and * javamail.default.providers
    • *
  • javamail.address.map and * javamail.default.address.map
    • *
*

* Each javamail.X resource file is searched for * using three methods in the following order: *

    *
  1. java.home/conf/javamail.X
    2. *
  2. META-INF/javamail.X
    3. *
  3. META-INF/javamail.default.X
    4. *
*

* (Where java.home is the value of the "java.home" System * property and conf is the directory named "conf" if it exists, * otherwise the directory named "lib"; the "conf" directory was * introduced in JDK 1.9.) *

* The first method allows the user to include their own version of the * resource file by placing it in the conf directory where the * java.home property points. The second method allows an * application that uses the JavaMail APIs to include their own resource * files in their application's or jar file's META-INF * directory. The javamail.default.X default files * are part of the JavaMail mail.jar file and should not be * supplied by users.

=================================================================== 11. Flags convenience methods (249) ----------------------------------- When copying messages from one server to another, it's sometimes necessary to adjust the message flags based on the capabilities of the target server. It would be convenient if the Flags class had methods to clear any flags not supported by the target server, to clear all user flags, and to clear all system flags. /** * Remove any flags not in the given Flags object. * Useful for clearing flags not supported by a server. If the * given Flags object includes the Flags.Flag.USER flag, all user * flags in this Flags object are retained. * * @param f the flags to keep * @return true if this Flags object changed * @since JavaMail 1.6 */ public boolean retainAll(Flags f) /** * Clear all of the system flags. * * @since JavaMail 1.6 */ public void clearSystemFlags() /** * Clear all of the user flags. * * @since JavaMail 1.6 */ public void clearUserFlags()