Subversion Repositories javautils

                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)