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 (8415)
-------------------------------------------
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
*
* 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
*
* 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 (8568)
---------------------------------------------------------------
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:
*
*
* @since JavaMail 1.6
*/
public static final long MAXUID = 0xffffffffL;
===================================================================
8. MimeMultipart should throw ParseException for parsing errors (6069)
----------------------------------------------------------------------
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
*
* @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
*
* The Session class provides access to the protocol providers that
* implement the
* Each
* (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
*
===================================================================
11. Flags convenience methods (8822)
------------------------------------
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()
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 (6281)
------------------------------------------------------------------
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.
*
* Folder f = store.getFolder("whatever");
* UIDFolder uf = (UIDFolder)f;
* Message[] newMsgs =
* uf.getMessagesByUID(lastSeenUID + 1, UIDFolder.MAXUID);
*
* 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 (6216)
--------------------------------------------------------
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. 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 javamail.X resource file is searched for
* using three methods in the following order:
*
*
* java.home/conf/javamail.X META-INF/javamail.X META-INF/javamail.default.X 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.