javamail-1.4-changes.txt

Java mail client (get all message on mails erver)

		JavaMail 1.4
		============

		(Updated August 15, 2005)

Following is a description of the new APIs that are being
introduced in JavaMail 1.4.  The numbers in parentheses
are bug numbers; you can find more information about the
bug reports at:

    http://bugs.sun.com/bugdatabase/index.jsp

Please send comments and feedback to [e-mail].

Many of these changes expand JavaMail's conformance with Internet
standards, or make JavaMail more tolerant of messages that don't
quite conform to the standards.  "Be liberal in what you receive
and conservative in what you send."

JavaMail 1.4 will also require at least J2SE 1.4.  This allows
JavaMail to take advantage of features of more modern J2SE releases.


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

1. Add MimePart.setText(text, charset, subtype) method (6300765)
----------------------------------------------------------------

The setText method is a convenience method used to set the content
for a text/plain part.  With the increased use of HTML and XML in
mail messages, it would be useful to have a convenience method to
set content of those types as well.  To support this usage we add
a new method to the MimePart interface:

    /**
     * Convenience method that sets the given String as this part's
     * content, with a primary MIME type of "text" and the specified
     * MIME subtype.  The given Unicode string will be charset-encoded
     * using the specified charset. The charset is also used to set
     * the "charset" parameter.
     *
     * @param	text	the text content to set
     * @param	charset	the charset to use for the text
     * @param	subtype	the MIME subtype to use (e.g., "html")
     * @exception	MessagingException	if an error occurs
     * @since	JavaMail 1.4
     */
    public void setText(String text, String charset, String subtype)
                        throws MessagingException;

The MimeMessage and MimeBodyPart classes, which implement the
MimePart interface, will be updated to provide implementations
of the new method.


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

2. Add mail.mime.encodefilename and decodefilename properties (6300768)
-----------------------------------------------------------------------

According to the MIME spec (RFC 2047), filenames included in the
filename parameter of the Content-Disposition header may not
include MIME "encoded-words", and thus may contain only US-ASCII
characters.  However, many mailers violate this spec requirement
and use standard MIME encoding techniques to store non-ASCII
filenames in this filename parameter.

If the mail.mime.encodefilename System property is set to "true".
the MimeMessage and MimeBodyPart setFileName methods will use the
MimeUtility.encodeText method to encode the filename.

If the mail.mime.decodefilename System property is set to "true".
the MimeMessage and MimeBodyPart getFileName methods will use the
MimeUtility.decodeText method to decode the filename.

Both of these properties default to "false".

The following text is added to the MimeMessage and MimeBodyPart
setFileName methods:

     * If the <code>mail.mime.encodefilename</code> System property
     * is set to true, the {@link MimeUtility#encodeText
     * MimeUtility.encodeText method will be used to encode the
     * filename.  While such encoding is not supported by the MIME
     * spec, many mailers use this technique to support non-ASCII
     * characters in filenames.  The default value of this property
     * is false.

The following text is added to the MimeMessage and MimeBodyPart
getFileName methods:

     * If the <code>mail.mime.encodefilename</code> System property
     * is set to true, the {@link MimeUtility#decodeText
     * MimeUtility.decodeText method will be used to decode the
     * filename.  While such encoding is not supported by the MIME
     * spec, many mailers use this technique to support non-ASCII
     * characters in filenames.  The default value of this property
     * is false.


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

3. Add Service.connect(user, password) (6300771)
------------------------------------------------

This convenience method uses the host already known to the Service
(Transport or Store).  Equivalent to connect(null, user, password).

    /**
     * Connect to the current host using the specified username
     * and password.  This method is equivalent to calling the
     * <code>connect(host, user, password)</code> method with null
     * for the host name.
     *
     * @param user      the user name
     * @param password  this user's password
     * @exception AuthenticationFailedException for authentication failures
     * @exception MessagingException            for other failures
     * @exception IllegalStateException if the service is already connected
     * @see javax.mail.event.ConnectionEvent
     * @see javax.mail.Session#setPasswordAuthentication
     * @see #connect(java.lang.String, java.lang.String, java.lang.String)
     * @since		JavaMail 1.4
     */
    public void connect(String user, String password) throws MessagingException


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

4. Add mail.mime.multipart.ignoremissingendboundary System property (4971381)
-----------------------------------------------------------------------------

The current implementation of the MimeMultipart class will
ignore a missing end boundary line; if EOF is reached when
parsing the content before seeing an end boundary line, the
last part of the multipart is terminated and no error is
returned.

Some users have requested a way to force the multipart
parsing to more strictly enforce the MIME specification.
To support this we we introduce a new System property:

    mail.mime.multipart.ignoremissingendboundary

If this property is set to "false" MimeMultipart will throw a
MessagingException when parsing a multipart that does not
include the proper end boundary line.

This property is already supported as part of the JavaMail
implementation.  This change makes the property a part of the
standard API.

 * The <code>mail.mime.multipart.ignoremissingendboundary</code>
 * System property may be set to <code>false</code> to cause a
 * <code>MessagingException</code> to be thrown if the multipart
 * data does not end with the required end boundary line.  If this
 * property is set to <code>true</code> or not set, missing end
 * boundaries are not considered an error and the final body part
 * ends at the end of the data. <p>


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

5. Add MimeMultipart.isComplete() method (6300811)
--------------------------------------------------

As described above, parsing of a MIME multipart may terminate
without an error, even though no final boundary line was seen.
This method will return true if the final boundary line was
seen.  This will allow applications to successfully parse
mal-formed messages, while also being able to tell that they
were mal-formed.

    /**
     * Return true if the final boundary line for this
     * multipart was seen.  When parsing multipart content,
     * this class will (by default) terminate parsing with
     * no error if the end of input is reached before seeing
     * the final multipart boundary line.  In such a case,
     * this method will return false.  (If the System property
     * "mail.mime.multipart.ignoremissingendboundary" is set to
     * false, parsing such a message will instead throw a
     * MessagingException.)
     *
     * @return	true if the final boundary line was seen
     * @since		JavaMail 1.4
     */
    public boolean isComplete() throws MessagingException


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

6. Add mail.mime.multipart.ignoremissingboundaryparameter property (6300814)
----------------------------------------------------------------------------

The following property is already supported as part of the JavaMail
implementation.  This change makes the property a part of the
standard API.

 * The <code>mail.mime.multipart.ignoremissingboundaryparameter</code>
 * System property may be set to <code>false</code> to cause a
 * <code>MessagingException</code> to be thrown if the Content-Type
 * of the MimeMultipart does not include a <code>boundary</code> parameter.
 * If this property is set to <code>true</code> or not set, the multipart
 * parsing code will look for a line that looks like a bounary line and
 * use that as the boundary separating the parts.


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

7. Add MimeMultipart getPreamble and setPreamble methods (6300828)
------------------------------------------------------------------

In a MIME multipart message, it's possible to include text between
the headers and the first boundary line.  This text is called the
preamble.  It may include instructions for users of non-MIME
compliant software.  The getPreamble method allows access to this
text when available.  (Note that IMAP servers provide no convenient
access to this text.)  The setPreamble method allows an application
to set the preamble for a message being constructed.

    /**
     * Get the preamble text, if any, that appears before the
     * first body part of this multipart.  Some protocols,
     * such as IMAP, will not allow access to the preamble text.
     *
     * @return		the preamble text, or null if no preamble
     * @since		JavaMail 1.4
     */
    public String getPreamble() throws MessagingException

    /**
     * Set the preamble text to be included before the first
     * body part.  Applications should generally not include
     * any preamble text.  In some cases it may be helpful to
     * include preamble text with instructions for users of
     * pre-MIME software.
     *
     * @param	preamble	the preamble text
     * @since		JavaMail 1.4
     */
    public void setPreamble(String preamble) throws MessagingException


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

8. Add MimeMessage.updateMessageID() protected method (6300831)
---------------------------------------------------------------

Some applications want more control over the data that's used
to create the Message-ID for a message.  This method allows
an application to provide a simple subclass of MimeMessage
that overrides the Message-ID algorithm.

    /**
     * Update the Message-ID header.  This method is called
     * by the <code>updateHeaders</code> and allows a subclass
     * to override only the algorithm for choosing a Message-ID.
     *
     * @since		JavaMail 1.4
     */
    protected void updateMessageID() throws MessagingException


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

9. Add MimeMessage.createMimeMessage() protected method (6300833)
-----------------------------------------------------------------

The MimeMessage.reply method creates and returns a new MimeMessage.
Subclasses of MimeMessage may need the reply method to create a new
message of the appropriate subclass.  This method allows subclasses
to control the class created in this case.

    /**
     * Create and return a MimeMessage object.  The reply method
     * uses this method to create the MimeMessage object that it
     * will return.  Subclasses can override this method to return
     * a subclass of MimeMessage.  This implementation simply constructs
     * and returns a MimeMessage object using the supplied Session.
     *
     * @param	session	the Session to use for the new message
     * @return		the new MimeMessage object
     * @since		JavaMail 1.4
     */
    protected MimeMessage createMimeMessage(Session session)
				throws MessagingException


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

10. Make the "part" field of MimePartDataSource protected (6300834)
-------------------------------------------------------------------

Subclasses of MimePartDataSource may need access to the "part"
field in order to implement the getInputStream method.  The
part field is currently private, this change will make it protected.

	/**
	 * The MimePart that provides the data for this DataSource.
	 *
	 * @since	JavaMail 1.4
	 */
	protected MimePart part;


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

11. Folder.getSeparator should not require the folder to exist (6301381)
------------------------------------------------------------------------

IMAP folders are able to determine the separator character without
knowing whether the folder exists.  Checking whether the folder
exists in order to throw FolderNotFoundException introduces additional
overhead.  Because other methods often need to know the separator
character, this overhead can be noticable.  The specification of this
method is changed as follows:

    /**
     * Return the delimiter character that separates this Folder's pathname
     * from the names of immediate subfolders. This method can be invoked 
     * on a closed Folder.
     *
     * @exception 	FolderNotFoundException if the implementation
     *			requires the folder to exist, but it does not
     * @return          Hierarchy separator character
     */
    public abstract char getSeparator() throws MessagingException;


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

12. Add PreencodedMimeBodyPart class (6301386)
----------------------------------------------

In some cases an application will have data that has already
been encoded using (for example) base64 encoding.  There should
be an easy way to attach such data to a message without the need
to decode it and reencode it.  This class provides such support.

/**
 * A MimeBodyPart that handles data that has already been encoded.
 * This class is useful when constructing a message and attaching
 * data that has already been encoded (for example, using base64
 * encoding).  The data may have been encoded by the application,
 * or may have been stored in a file or database in encoded form.
 * The encoding is supplied when this object is created.  The data
 * is attached to this object in the usual fashion, by using the
 * <code>setText</code>, <code>setContent</code>, or
 * <code>setDataHandler</code> methods.
 *
 * @since	JavaMail 1.4
 */