javamail-1.2-changes.txt

Java mail client (get all message on mails erver)

		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 [e-mail].


===================================================================

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.