javamail-1.2-changes.txt

Java mail client (get all message on mails erver)

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.