| |
| JavaMail 1.2 |
| ============ |
| |
| Following is a description of the new APIs that are being |
| introduced in JavaMail 1.2. The numbers in parentheses |
| are bug numbers; you can find more information about the |
| bug reports at: |
| |
| http://developer.java.sun.com/developer/bugParade/index.html |
| |
| Please send comments and feedback to javamail@sun.com. |
| |
| |
| =================================================================== |
| |
| 1. New protected field and methods (4129743) |
| -------------------------------------------- |
| |
| To simplify creating subclasses of MimeMessage, the following |
| field and method that were previously private are now protected: |
| |
| /** |
| * A flag indicating whether the message has been modified. |
| * If the message has not been modified, any data in the |
| * <code>content</code> array is assumed to be valid and is used |
| * directly in the <code>writeTo</code> method. This flag is |
| * set to true when an empty message is created or when the |
| * <code>saveChanges</code> method is called. |
| */ |
| protected boolean modified = false; |
| |
| /** |
| * Parse the InputStream setting the <code>headers</code> and |
| * <code>content</code> fields appropriately. Also resets the |
| * <code>modified</code> flag. <p> |
| * |
| * This method is intended for use by subclasses that need to |
| * control when the InputStream is parsed. |
| * |
| * @param is The message input stream |
| * @exception MessagingException |
| */ |
| protected void parse(InputStream is) throws MessagingException |
| |
| |
| The javadocs for the following exsting methods have been updated to |
| describe the use of the modified flag: |
| |
| /** |
| * Default constructor. An empty message object is created. |
| * The <code>headers</code> field is set to an empty InternetHeaders |
| * object. The <code>flags</code> field is set to an empty Flags |
| * object. The <code>modified</code> flag is set to true. |
| */ |
| public MimeMessage(Session session) |
| |
| /** |
| * Output the message as an RFC 822 format stream, without |
| * specified headers. If the <code>modified</code> flag is not |
| * set and the <code>content</code> array is not null, the |
| * <code>content</code> array is written directly, after |
| * writing the appropriate message headers. |
| * |
| * @exception javax.mail.MessagingException |
| * @exception IOException if an error occurs writing to the stream |
| * or if an error is generated by the |
| * javax.activation layer. |
| * @see javax.activation.DataHandler#writeTo |
| */ |
| public void writeTo(OutputStream os, String[] ignoreList) |
| throws IOException, MessagingException |
| |
| /** |
| * Updates the appropriate header fields of this message to be |
| * consistent with the message's contents. If this message is |
| * contained in a Folder, any changes made to this message are |
| * committed to the containing folder. <p> |
| * |
| * If any part of a message's headers or contents are changed, |
| * <code>saveChanges</code> must be called to ensure that those |
| * changes are permanent. Otherwise, any such modifications may or |
| * may not be saved, depending on the folder implementation. <p> |
| * |
| * Messages obtained from folders opened READ_ONLY should not be |
| * modified and saveChanges should not be called on such messages. <p> |
| * |
| * This method sets the <code>modified</code> flag to true and then |
| * calls the <code>updateHeaders<code> method. |
| * |
| * @exception IllegalWriteException if the underlying |
| * implementation does not support modification |
| * @exception IllegalStateException if this message is |
| * obtained from a READ_ONLY folder. |
| * @exception MessagingException |
| */ |
| public void saveChanges() throws MessagingException |
| |
| The following method is added to MimeMessage: |
| |
| /** |
| * Create and return an InternetHeaders object that loads the |
| * headers from the given InputStream. Subclasses can override |
| * this method to return a subclass of InternetHeaders, if |
| * necessary. This implementation simply constructs and returns |
| * an InternetHeaders object. |
| * |
| * @param is the InputStream to read the headers from |
| * @exception MessagingException |
| */ |
| protected InternetHeaders createInternetHeaders(InputStream is) |
| throws MessagingException |
| |
| Likewise, to simplify creating subclasses of MimeMultipart, the parse |
| method is made protected: |
| |
| /** |
| * Parse the InputStream from our DataSource, constructing the |
| * appropriate MimeBodyParts. The <code>parsed</code> 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. |
| */ |
| protected synchronized void parse() throws MessagingException |
| |
| and the following protected methods are added: |
| |
| /** |
| * Create and return an InternetHeaders object that loads the |
| * headers from the given InputStream. Subclasses can override |
| * this method to return a subclass of InternetHeaders, if |
| * necessary. This implementation simply constructs and returns |
| * an InternetHeaders object. |
| * |
| * @param is the InputStream to read the headers from |
| * @exception MessagingException |
| */ |
| protected InternetHeaders createInternetHeaders(InputStream is) |
| throws MessagingException |
| |
| /** |
| * Create and return a MimeBodyPart object to represent a |
| * body part parsed from the InputStream. Subclasses can override |
| * this method to return a subclass of MimeBodyPart, if |
| * necessary. This implementation simply constructs and returns |
| * a MimeBodyPart object. |
| * |
| * @param headers the headers for the body part |
| * @param content the content ofthe body part |
| * @exception MessagingException |
| */ |
| protected MimeBodyPart createMimeBodyPart(InternetHeaders headers, |
| byte[] content) throws MessagingException |
| |
| /** |
| * Create and return a MimeBodyPart object to represent a |
| * body part parsed from the InputStream. Subclasses can override |
| * this method to return a subclass of MimeBodyPart, if |
| * necessary. This implementation simply constructs and returns |
| * a MimeBodyPart object. |
| * |
| * @param is InputStream containing the body part |
| * @exception MessagingException |
| */ |
| protected MimeBodyPart createMimeBodyPart(InputStream is) |
| throws MessagingException |
| |
| =================================================================== |
| |
| 2. MimeMessage and MimeBodyPart getRawInputStream method (4124840) |
| ------------------------------------------------------------------ |
| |
| In some cases it is desirable to get the data for a body part |
| before JavaMail attempts to decode it. This is particularly important |
| if the Content-Transfer-Encoding header is incorrect. (For example, |
| some mail software is known to use "7-bit" instead of the MIME |
| defined "7bit".) Access to this data is currently provided |
| through the protected getContentStream method. Since simply |
| making this method public has the potential to cause a source |
| incompatibility for any subclasses that declare this method as |
| protected, we instead add a new public method that calls this |
| protected method: |
| |
| /** |
| * Return an InputStream to the raw data with any Content-Transfer-Encoding |
| * intact. This method is useful if the "Content-Transfer-Encoding" |
| * header is incorrect or corrupt, which would prevent the |
| * <code>getInputStream</code> method or <code>getContent</code> method |
| * from returning the correct data. In such a case the application may |
| * use this method and attempt to decode the raw data itself. <p> |
| * |
| * This implementation simply calls the <code>getContentStream</code> |
| * method. |
| * |
| * @see #getInputStream |
| * @see #getContentStream |
| */ |
| public InputStream getRawInputStream() throws MessagingException |
| |
| |
| =================================================================== |
| |
| 3. ReadOnlyFolderException (4163360) |
| ------------------------------------ |
| |
| A new MessagingException subclass to indicate a read-only folder |
| is needed. |
| |
| Currently, if a client attempts to open a folder in read-write mode |
| and the folder is read-only, a MessagingException is thrown. This |
| exception type does not indicate that the anomaly was caused due to |
| the lack of write-permissions. |
| |
| /** |
| * This exception is thrown when an attempt is made to open a folder |
| * with read-write access when the folder is marked read-only. <p> |
| */ |
| |
| public class ReadOnlyFolderException extends MessagingException { |
| |
| /** |
| * Constructor. |
| * @param folder the Folder |
| */ |
| public ReadOnlyFolderException(Folder folder) |
| |
| /** |
| * Constructor. |
| * @param folder the Folder |
| * @param message the detailed error message |
| */ |
| public ReadOnlyFolderException(Folder folder, String message) |
| |
| /** |
| * Returns the Folder object. |
| */ |
| public Folder getFolder() |
| } |
| |
| =================================================================== |
| |
| 4. InternetAddress implements Cloneable (4181144) |
| ------------------------------------------------- |
| |
| To simplify copying of InternetAddress objects, the InternetAddress |
| class will implement the Cloneable interface and will provide a |
| public clone method. |
| |
| public class InternetAddress extends Address implements Cloneable { |
| |
| /** |
| * Return a copy of this InternetAddress object. |
| */ |
| public Object clone() |
| } |
| |
| =================================================================== |
| |
| 5. MimeMessage copy constructor (4107752) |
| ----------------------------------------- |
| |
| When forwarding or saving a message retrieved from a Store, it is |
| sometimes desirable to be able to modify the message first. Since |
| most Stores do not allow their Message objects to be modified, the |
| message must first be copied. To simplify copying a MimeMessage, |
| we introduce a copy constructor that allows a new MimeMessage to |
| be created and initialized with a copy of another MimeMessage. |
| |
| /** |
| * Constructs a new MimeMessage with content initialized form the |
| * <code>source</code> MimeMessage. The new message is independent |
| * of the original. <p> |
| * |
| * @param source the message to copy content from |
| * @exception MessagingException |
| */ |
| public MimeMessage(MimeMessage source) throws MessagingException |
| |
| =================================================================== |
| |
| 6. AuthenticationFailedException includes server message (4230553) |
| ------------------------------------------------------------------ |
| |
| When authentication with a server fails, the server often supplies |
| some information in its protocol message that indicates the reason |
| for the failure. To allow a service provider to return this information |
| to the user, we now allow the Service.protocolConnect() method to |
| throw an AuthenticationFailedException in this case. The exception |
| may contain a string message that includes the additional information |
| from the server. |
| |
| /** |
| * The service implementation should override this method to |
| * perform the actual protocol-specific connection attempt. |
| * The default implementation of the <code>connect</code> method |
| * calls this method as needed. <p> |
| * |
| * The <code>protocolConnect</code> method should return |
| * <code>false</code> if a user name or password is required |
| * for authentication but the corresponding parameter is null; |
| * the <code>connect</code> method will prompt the user when |
| * needed to supply missing information. This method may |
| * also return <code>false</code> if authentication fails for |
| * the supplied user name or password. Alternatively, this method |
| * may throw an AuthenticationFailedException when authentication |
| * fails. This exception may include a String message with more |
| * detail about the failure. <p> |
| * |
| * The <code>protocolConnect</code> method should throw an |
| * exception to report failures not related to authentication, |
| * such as an invalid host name or port number, loss of a |
| * connection during the authentication process, unavailability |
| * of the server, etc. |
| * |
| * @param host the name of the host to connect to |
| * @param port the port to use (-1 means use default port) |
| * @param user the name of the user to login as |
| * @param password the user's password |
| * @return true if connection successful, false if authentication failed |
| * @exception AuthenticationFailedException for authentication failures |
| * @exception MessagingException for non-authentication failures |
| */ |
| protected boolean protocolConnect(String host, int port, String user, |
| String password) throws MessagingException |
| |
| =================================================================== |
| |
| 7. Support ESMTP 8BITMIME extension (4132029) |
| --------------------------------------------- |
| |
| JavaMail chooses the encoding for body parts when the Message.saveChanges() |
| method is called. At the time this method is called, JavaMail has no |
| information about the Transport that might be used to send the message. |
| Thus, communicating the Transport's capabilities to the part of JavaMail |
| that chooses body part encodings is problematic. |
| |
| To provide some minimal support for the 8BITMIME extension, the SMTP |
| protocol provider is extended in the following way. Note that this |
| capability is part of Sun's SMTP protocol provider, and is *not* a |
| part of the JavaMail API spec. We include it here for convenience only. |
| |
| If the property "mail.smtp.allow8bitmime" is set to "true", and the |
| SMTP server supports the 8BITMIME extension, the SMTP Transport will |
| traverse the message and adjust the Content-Transfer-Encoding of text |
| body parts from "quoted-printable" or "base64" to "8bit" as appropriate. |
| |
| Note that if the same message is subsequently sent over a Transport |
| or to a server that does not support 8bit MIME, the message will *not* |
| be converted back to a non-8bit encoding. Normally this will not be a |
| problem. Note also that a message using "8bit" encoding can be safely |
| appended to an IMAP folder. |
| |
| =================================================================== |
| |
| 8. Make MailDateFormat class public (4266390) |
| --------------------------------------------- |
| |
| It would be useful to have the MailDateFormat class available as part |
| of the javax.mail.internet package to allow parsing and formatting |
| dates in other MIME headers. |
| |
| /** |
| * Formats and parses date specification based on the |
| * draft-ietf-drums-msg-fmt-08 dated January 26, 2000. This is a followup |
| * spec to RFC822.<p> |
| * |
| * This class does not take pattern strings. It always formats the |
| * date based on the specification below.<p> |
| * |
| * 3.3 Date and Time Specification<p> |
| * |
| * Date and time occur in several header fields of a message. This section |
| * specifies the syntax for a full date and time specification. Though folding |
| * whitespace is permitted throughout the date-time specification, it is |
| * recommended that only a single space be used where FWS is required and no |
| * space be used where FWS is optional in the date-time specification; some |
| * older implementations may not interpret other occurrences of folding |
| * whitespace correctly.<p> |
| * |
| * date-time = [ day-of-week "," ] date FWS time [CFWS]<p> |
| * |
| * day-of-week = ([FWS] day-name) / obs-day-of-week<p> |
| * |
| * day-name = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"<p> |
| * |
| * date = day month year<p> |
| * |
| * year = 4*DIGIT / obs-year<p> |
| * |
| * month = (FWS month-name FWS) / obs-month<p> |
| * |
| *<pre>month-name = "Jan" / "Feb" / "Mar" / "Apr" / |
| * "May" / "Jun" / "Jul" / "Aug" / |
| * "Sep" / "Oct" / "Nov" / "Dec" |
| * </pre><p> |
| * day = ([FWS] 1*2DIGIT) / obs-day<p> |
| * |
| * time = time-of-day FWS zone<p> |
| * |
| * time-of-day = hour ":" minute [ ":" second ]<p> |
| * |
| * hour = 2DIGIT / obs-hour<p> |
| * |
| * minute = 2DIGIT / obs-minute<p> |
| * |
| * second = 2DIGIT / obs-second<p> |
| * |
| * zone = (( "+" / "-" ) 4DIGIT) / obs-zone<p> |
| * |
| * |
| * The day is the numeric day of the month. The year is any numeric year in |
| * the common era.<p> |
| * |
| * The time-of-day specifies the number of hours, minutes, and optionally |
| * seconds since midnight of the date indicated.<p> |
| * |
| * The date and time-of-day SHOULD express local time.<p> |
| * |
| * The zone specifies the offset from Coordinated Universal Time (UTC, |
| * formerly referred to as "Greenwich Mean Time") that the date and |
| * time-of-day represent. The "+" or "-" indicates whether the time-of-day is |
| * ahead of or behind Universal Time. The first two digits indicate the number |
| * of hours difference from Universal Time, and the last two digits indicate |
| * the number of minutes difference from Universal Time. (Hence, +hhmm means |
| * +(hh * 60 + mm) minutes, and -hhmm means -(hh * 60 + mm) minutes). The form |
| * "+0000" SHOULD be used to indicate a time zone at Universal Time. Though |
| * "-0000" also indicates Universal Time, it is used to indicate that the time |
| * was generated on a system that may be in a local time zone other than |
| * Universal Time.<p> |
| * |
| * A date-time specification MUST be semantically valid. That is, the |
| * day-of-the week (if included) MUST be the day implied by the date, the |
| * numeric day-of-month MUST be between 1 and the number of days allowed for |
| * the specified month (in the specified year), the time-of-day MUST be in the |
| * range 00:00:00 through 23:59:60 (the number of seconds allowing for a leap |
| * second; see [STD-12]), and the zone MUST be within the range -9959 through |
| * +9959.<p> |
| * |
| */ |
| public class MailDateFormat extends SimpleDateFormat { |
| |
| public MailDateFormat() |
| |
| /** |
| * Formats the given date in the format specified by |
| * draft-ietf-drums-msg-fmt-08 in the current TimeZone |
| * |
| * @param date the Date object |
| * @param dateStrBuf the formatted string |
| * @param fieldPosition the current field position |
| * @returns StringBuffer the formatted String |
| */ |
| public StringBuffer format(Date date, StringBuffer dateStrBuf, |
| FieldPosition fieldPosition) |
| |
| /** |
| * Parses the given date in the format specified by |
| * draft-ietf-drums-msg-fmt-08 in the current TimeZone |
| * |
| * @param text the formatted date to be parsed |
| * @param pos the current parse position |
| * @returns Date the parsed date in a Date object |
| */ |
| public Date parse(String text, ParsePosition pos) |
| } |
| |
| =================================================================== |
| |
| 9. String-based MimeMessage setRecipients and addRecipients methods (4328824) |
| ----------------------------------------------------------------------------- |
| The following convenience methods will be added to MimeMessage. They take a |
| String for setting/adding a recipient (instead of javax.mail.Address objects). |
| |
| /** |
| * Set the specified recipient type to the given addresses. |
| * If the address parameter is <code>null</code>, the corresponding |
| * recipient field is removed. |
| * |
| * @param type Recipient type |
| * @param addresses Addresses |
| * @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 |
| * @see #getRecipients |
| */ |
| public void setRecipients(Message.RecipientType type, String addresses) |
| throws MessagingException |
| |
| /** |
| * Add the given addresses to the specified recipient type. |
| * |
| * @param type Recipient type |
| * @param addresses Addresses |
| * @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 |
| */ |
| public void addRecipients(Message.RecipientType type, String addresses) |
| throws MessagingException |
| |
| =================================================================== |
| |
| 10. Add Session.getDefaultInstance(Properties props) and |
| Session.getInstance(Properties props) methods (4328826) |
| --------------------------------------------------------------- |
| |
| These are convenience methods for retrieving the default Session or a new |
| Session object which does not require an Authenticator parameter |
| (it is assumed to be null). |
| |
| /** |
| * Get the default Session object. If a default has not yet been |
| * setup, a new Session object is created and installed as the |
| * default.<p> |
| * |
| * Note that a default session created with no Authenticator is |
| * available to all code executing in the same Java virtual |
| * machine, and the session can contain security sensitive |
| * information such as user names and passwords. |
| * |
| * @param props Properties object. Used only if a new Session |
| * object is created.<br> |
| * It is expected that the client supplies values |
| * for the properties listed in Appendix A of the |
| * JavaMail spec (particularly mail.store.protocol, |
| * mail.transport.protocol, mail.host, mail.user, |
| * and mail.from) as the defaults are unlikely to |
| * work in all cases. |
| * @return the default Session object |
| */ |
| public static Session getDefaultInstance(Properties props) |
| |
| /** |
| * Get a new Session object. |
| * |
| * @param props Properties object that hold relevant properties.<br> |
| * It is expected that the client supplies values |
| * for the properties listed in Appendix A of the |
| * JavaMail spec (particularly mail.store.protocol, |
| * mail.transport.protocol, mail.host, mail.user, |
| * and mail.from) as the defaults are unlikely to |
| * work in all cases. |
| * @return a new Session object |
| * @see javax.mail.Authenticator |
| */ |
| public static Session getInstance(Properties props) |
| |
| =================================================================== |
| |
| 11. Allow for providing a filename when using MimeUtility.encode() (4140579) |
| ---------------------------------------------------------------------------- |
| |
| The UUEncode encoder requires the filename to be inserted into the encoded |
| stream. The public access point to the encoder is thru the MimeUtility.encode() |
| method, which does not have any parameter that can provide the filename. |
| Hence the uuencoded stream always has "encode.buf" as filename. This new |
| method allows the setting of the filename. |
| |
| /** |
| * Wrap an encoder around the given output stream. |
| * All the encodings defined in RFC 2045 are supported here. |
| * They include "base64", "quoted-printable", "7bit", "8bit" and |
| * "binary". In addition, "uuencode" is also supported. |
| * The <code>filename</code> parameter is used with the "uuencode" |
| * encoding and is included in the encoded output. |
| * |
| * @param os output stream |
| * @param encoding the encoding of the stream. |
| * @param filename name for the file being encoded |
| * @exception MessagingException |
| * @return output stream that applies the |
| * specified encoding. |
| */ |
| public static OutputStream encode(OutputStream os, String encoding, |
| String filename) |
| throws MessagingException |
| |
| =================================================================== |
| |
| 12. New exception constructors (4259211) |
| ---------------------------------------- |
| |
| The FolderNotFoundException constructors are not consistant with other |
| exceptions defined in the API. New constructors are needed to eliminate |
| these inconsistencies. |
| |
| /** |
| * Constructs a MessagingException with the specified folder |
| * @param folder the Folder |
| */ |
| public FolderNotFoundException(Folder folder) |
| |
| /** |
| * Constructs a MessagingException with the specified detail message |
| * and the specified folder. |
| * @param folder the Folder |
| * @param s the detail message |
| */ |
| public FolderNotFoundException(Folder folder, String s) |
| |
| =================================================================== |
| |
| 13. InternetAddress.toUnicodeString() method (4281729) |
| ------------------------------------------------------- |
| |
| Problem: AddressStringTerm.match does not return the correct results |
| in some situations. |
| |
| AddressStringTerm wants to do the match against the formatted address |
| string in Unicode, not the ASCII version that might include charset |
| encoding information. To do this it attempts to format the address |
| itself, but it's not smart enough to know all the rules about |
| formatting an address (e.g., when to quote the personal name) so it |
| does this formatting differently than InternetAddress.toString does. |
| When the address contains only ASCII characters, the formatting should |
| be identical. |
| |
| /** |
| * Returns a properly formatted address (RFC 822 syntax) of |
| * Unicode characters. |
| * |
| * @return Unicode address string |
| */ |
| public String toUnicodeString() |
| |
| =================================================================== |
| |
| 14. Call saveChanges automatically on newly constructed message (4339203) |
| ------------------------------------------------------------------------- |
| |
| One of the most common errors when constructing new messages is forgetting |
| to call the saveChanges() method before writing out the message or calling |
| the Transport.sendMessage() method. To solve this problem we add a flag |
| to MimeMessage and change the writeTo() method accordingly: |
| |
| /** |
| * Does the <code>saveChanges</code> method need to be called on |
| * this message? This flag is set to false by the public constructor |
| * and set to true by the <code>saveChanges</code> method. The |
| * <code>writeTo</code> method checks this flag and calls the |
| * <code>saveChanges</code> method as necessary. This avoids the |
| * common mistake of forgetting to call the <code>saveChanges</code> |
| * method on a newly constructed message. |
| */ |
| protected boolean saved = false; |
| |
| /** |
| * Updates the appropriate header fields of this message to be |
| * consistent with the message's contents. If this message is |
| * contained in a Folder, any changes made to this message are |
| * committed to the containing folder. <p> |
| * |
| * If any part of a message's headers or contents are changed, |
| * <code>saveChanges</code> must be called to ensure that those |
| * changes are permanent. Otherwise, any such modifications may or |
| * may not be saved, depending on the folder implementation. <p> |
| * |
| * Messages obtained from folders opened READ_ONLY should not be |
| * modified and saveChanges should not be called on such messages. <p> |
| * |
| * This method sets the <code>modified</code> flag to true, the |
| * <code>save</code> flag to true, and then calls the |
| * <code>updateHeaders<code> method. |
| * |
| * @exception IllegalWriteException if the underlying |
| * implementation does not support modification |
| * @exception IllegalStateException if this message is |
| * obtained from a READ_ONLY folder. |
| * @exception MessagingException |
| */ |
| public void saveChanges() throws MessagingException |
| |
| /** |
| * Output the message as an RFC 822 format stream, without |
| * specified headers. If the <code>saved</code> flag is not set, |
| * the <code>saveChanges</code> method is called. |
| * If the <code>modified</code> flag is not |
| * set and the <code>content</code> array is not null, the |
| * <code>content</code> array is written directly, after |
| * writing the appropriate message headers. |
| * |
| * @exception javax.mail.MessagingException |
| * @exception IOException if an error occurs writing to the stream |
| * or if an error is generated by the |
| * javax.activation layer. |
| * @see javax.activation.DataHandler#writeTo |
| */ |
| public void writeTo(OutputStream os, String[] ignoreList) |
| throws IOException, MessagingException |
| |
| =================================================================== |
| |
| 15. New MimeUtility.getEncoding(DataHandler) method (4340648) |
| ------------------------------------------------------------- |
| |
| To improve the performance of JavaMail, we previously added a (package |
| private) getEncoding() method to MimeUtility. This method is now public: |
| |
| /** |
| * Same as <code>getEncoding(DataSource)</code> except that instead |
| * of reading the data from an <code>InputStream</code> it uses the |
| * <code>writeTo</code> method to examine the data. This is more |
| * efficient in the common case of a <code>DataHandler</code> |
| * created with an object and a MIME type (for example, a |
| * "text/plain" String) because all the I/O is done in this |
| * thread. In the case requiring an <code>InputStream</code> the |
| * <code>DataHandler</code> uses a thread, a pair of pipe streams, |
| * and the <code>writeTo</code> method to produce the data. <p> |
| */ |
| public static String getEncoding(DataHandler dh) |
| |
| =================================================================== |
| |
| 16. New TransportEvent.getMessage() method (4331674) |
| ----------------------------------------------------- |
| |
| The TransportEvent class saves the message that caused the error, |
| but provides no getMessage method for the listener to retrieve the |
| Message object. The following method will be added: |
| |
| /** |
| * Get the Message object associated with this Transport Event. |
| * |
| * @return the Message object |
| */ |
| public Message getMessage() |
| |
| |
| =================================================================== |
| |
| 17. javax.mail.search terms should be serializable (4126013) |
| ------------------------------------------------------------ |
| |
| The javax.mail.search package allows you to programmatically construct |
| a search term. It would be convenient if those terms could be saved |
| in persistent storage and restored in a later session. Using |
| serialization to store these expressions is the simplest approach. |
| |
| Many of the search terms reference other objects that must also be |
| serializable. The most problematic such objects are of the class |
| Message.RecipientType. This class uses the java "type-safe enum" |
| idiom, which involves a number of static final instances of the class. |
| Applications are allowed to test for equivalence with these "constants" |
| by using the "==" equality operator. Thus, it's critical that only a |
| single instance of each constant exist in the Java virtual machine. |
| To ensure that this constraint is met when deserializing an object |
| of this class, we must take advantage of the JDK 1.2 readReplace() |
| method. Since this method is not available on JDK 1.1, objects of |
| this class, and thus search terms that reference them, can not be |
| correctly deserialized on JDK 1.1. This is a limitation of this |
| new capability. |
| |
| To provide this support, the following classes and all their subclasses |
| now implement the Serializable interface: |
| |
| javax.mail.search.SearchTerm |
| javax.mail.Address |
| javax.mail.Flags |
| javax.mail.Message.RecipientType |
| |
| In addition, to allow comparison between search terms, the equals |
| and hashCode methods on SearchTerm (and all subclasses) now implement |
| "value" equivalence rather than identity equivalence. |
| |
| |
| =================================================================== |
| |
| 18. Support IMAP NAMESPACE extension (4364827) |
| ------------------------------------------------------------ |
| |
| We propose the following new APIs to be added to javax.mail.Store to |
| provide namespace information. If the IMAP server supports the |
| NAMESPACE extension, it will be used to return this information. |
| |
| /** |
| * Return a set of folders representing the <i>personal</i> namespaces |
| * for the current user. A personal namespace is a set of names that |
| * is considered within the personal scope of the authenticated user. |
| * Typically, only the authenticated user has access to mail folders |
| * in their personal namespace. If an INBOX exists for a user, it |
| * must appear within the user's personal namespace. In the |
| * typical case, there should be only one personal namespace for each |
| * user in each Store. <p> |
| * |
| * This implementation returns an array with a single entry containing |
| * the return value of the <code>getDefaultFolder</code> method. |
| * Subclasses should override this method to return appropriate information. |
| * |
| * @exception IllegalStateException if this Store is not connected. |
| * @return array of Folder objects |
| */ |
| public Folder[] getPersonalNamespaces() throws MessagingException |
| |
| /** |
| * Return a set of folders representing the namespaces for |
| * <code>user</code>. The namespaces returned represent the |
| * personal namespaces for the user. To access mail folders in the |
| * other user's namespace, the currently authenticated user must be |
| * explicitly granted access rights. For example, it is common for |
| * a manager to grant to their secretary access rights to their |
| * mail folders. <p> |
| * |
| * This implementation returns an empty array. Subclasses should |
| * override this method to return appropriate information. |
| * |
| * @exception IllegalStateException if this Store is not connected. |
| * @return array of Folder objects |
| */ |
| public Folder[] getUserNamespaces(String user) throws MessagingException |
| |
| /** |
| * Return a set of folders representing the <i>shared</i> namespaces. |
| * A shared namespace is a namespace that consists of mail folders |
| * that are intended to be shared amongst users and do not exist |
| * within a user's personal namespace. <p> |
| * |
| * This implementation returns an empty array. Subclasses should |
| * override this method to return appropriate information. |
| * |
| * @exception IllegalStateException if this Store is not connected. |
| * @return array of Folder objects |
| */ |
| public Folder[] getSharedNamespaces() throws MessagingException |
| |
| |
| =================================================================== |
| |
| 19. Make ContentDisposition class public (4366373) |
| -------------------------------------------------- |
| |
| The javax.mail.internet.ContentDisposition class is package private |
| and should be made public. The API is: |
| |
| /** |
| * This class represents a MIME ContentDisposition value. It provides |
| * methods to parse a ContentDisposition string into individual components |
| * and to generate a MIME style ContentDisposition string. |
| */ |
| |
| public class ContentDisposition |
| |
| /** |
| * No-arg Constructor. |
| */ |
| public ContentDisposition() |
| |
| /** |
| * Constructor. |
| * |
| * @param disposition disposition |
| * @param list ParameterList |
| */ |
| public ContentDisposition(String disposition, ParameterList list) |
| |
| /** |
| * Constructor that takes a ContentDisposition string. The String |
| * is parsed into its constituents: dispostion and parameters. |
| * A ParseException is thrown if the parse fails. |
| * |
| * @param s the ContentDisposition string. |
| * @exception ParseException if the parse fails. |
| */ |
| public ContentDisposition(String s) throws ParseException |
| |
| /** |
| * Return the disposition value. |
| * @return the disposition |
| */ |
| public String getDisposition() |
| |
| /** |
| * Return the specified parameter value. Returns <code>null</code> |
| * if this parameter is absent. |
| * @return parameter value |
| */ |
| public String getParameter(String name) |
| |
| /** |
| * Return a ParameterList object that holds all the available |
| * parameters. Returns null if no parameters are available. |
| * |
| * @return ParameterList |
| */ |
| public ParameterList getParameterList() |
| |
| /** |
| * Set the primary type. Overrides existing primary type. |
| * @param primaryType primary type |
| */ |
| public void setDisposition(String disposition) |
| |
| /** |
| * Set the specified parameter. If this parameter already exists, |
| * it is replaced by this new value. |
| * |
| * @param name parameter name |
| * @param value parameter value |
| */ |
| public void setParameter(String name, String value) |
| |
| /** |
| * Set a new ParameterList. |
| * @param list ParameterList |
| */ |
| public void setParameterList(ParameterList list) |
| |
| /** |
| * Retrieve a RFC2045 style string representation of |
| * this ContentDisposition. Returns <code>null</code> if |
| * the conversion failed. |
| * |
| * @return RFC2045 style string |
| */ |
| public String toString() |
| } |
| |
| =================================================================== |
| |
| 20. Improve performance of MimeMessage (4371862) |
| -------------------------------------------------- |
| |
| To allow us to improve the performance of the MimeMessage and MimeMultipart |
| classes when parsing data from an InputStream, we introduce a new |
| interface that allows the data in the InputStream to be shared instead |
| of copied, and we use this new interface in key parts of the implementation. |
| |
| The following field is added to MimeMessage: |
| |
| /** |
| * If the data for this message was supplied by an |
| * InputStream that implements the SharedInputStream interface, |
| * <code>contentStream</code> is another such stream representing |
| * the content of this message. In this case, <code>content</code> |
| * will be null. |
| */ |
| protected InputStream contentStream; |
| |
| The following field is added to MimeBodyPart: |
| |
| /** |
| * If the data for this body part was supplied by an |
| * InputStream that implements the SharedInputStream interface, |
| * <code>contentStream</code> is another such stream representing |
| * the content of this body part. In this case, <code>content</code> |
| * will be null. |
| */ |
| protected InputStream contentStream; |
| |
| The following interface is added: |
| |
| package javax.mail.internet; |
| |
| /** |
| * An InputStream that is backed by data that can be shared by multiple |
| * readers may implement this interface. This allows users of such an |
| * InputStream to determine the current positionin the InputStream, and |
| * to create new InputStreams representing a subset of the data in the |
| * original InputStream. The new InputStream will access the same |
| * underlying data as the original, without copying the data. |
| */ |
| |
| public interface SharedInputStream { |
| /** |
| * Return the current position in the InputStream, as an |
| * offset from the beginning of the InputStream. |
| * |
| * @return the current position |
| */ |
| public long getPosition(); |
| |
| /** |
| * Return a new InputStream representing a subset of the data |
| * from this InputStream, starting at <code>start</code> (inclusive) |
| * up to <code>end</code> (exclusive). <code>start</code> must be |
| * non-negative. If <code>end</code> is -1, the new stream ends |
| * at the same place as this stream. The returned InputStream |
| * will also implement the SharedInputStream interface. |
| * |
| * @param start the starting position |
| * @param end the ending position + 1 |
| * @return the new stream |
| */ |
| public InputStream newStream(long start, long end); |
| } |
| |
| =================================================================== |
| |
| 21. New ParameterList.toString(int used) method. |
| -------------------------------------------------- |
| |
| The ParameterList.toString() method returns its results "unfolded". It |
| would be useful to have the results "folded" in certain situations. A |
| new method will be added to the ParamterList class which will return |
| "folded" results. Folding is defined by RFC 822 as the process of splitting |
| a header field into multiple lines. "The general rule is that wherever there |
| may be linear-white-space (NOT simply LWSP-chars), a CRLF immediately |
| followed by AT LEAST one LWSP-char may instead be inserted." Unfolding is |
| the process of returning to a single line representation. "Unfolding is |
| accomplished by regarding CRLF immediately followed by a LWSP-char as |
| equivalent to the LWSP-char." |
| |
| /** |
| * Convert this ParameterList into a MIME String. If this is |
| * an empty list, an empty string is returned. |
| * |
| * 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's used to determine where |
| * to "fold" the resulting parameter list. |
| * |
| * @param used number of character positions already used, in |
| * the field into which the parameter list is to |
| * be inserted. |
| * @return String |
| */ |
| public String toString(int used) |
