javamail-1.1.txt

SUN的JAVA MAIL API

		
		JavaMail 1.1
		============

Following is a description of the new APIs that are being
introduced in JavaMail 1.1

Please send comments and feedback to [e-mail]

(1) MessageContext
==================

In some cases it is desirable for the object representing the content
of a BodyPart to know something about the "context" in which it is
operating, e.g., what other data is contained in the same Multipart
object, who sent the message containing the data, etc.  This allows
for more interesting content types that know more about the message
containing them and the mail system in general.

Some uses of multipart/related might require these capabilities.
For instance, the handler for a text/html body part contained in a
multipart/related object might need to know about the containing
object in order to find the related image data needed to display the
HTML document.

There is one particular case in the current implementation where
this need arises.  (This is a bug in the current release.)  When
constructing a MimeMessage object for a nested message contained
in another message, the DataContentHandler needs the Session
object in order to construct the new MimeMessage object.

To solve these problems we introduce a new class, a new interface,
and a number of new methods.

The MessageContext class provides the basic information about the
"context" in which a content object is operating:

/**
 * The context in which a piece of Message content is contained.  A
 * <code>MessageContext</code> object is returned by the
 * <code>getMessageContext</code> method of the
 * <code>MessageAware</code> interface.  <code>MessageAware</code> is
 * typically implemented by <code>DataSources</code> to allow a
 * <code>DataContentHandler</code> to pass on information about the
 * context in which a data content object is operating.
 *
 * @see javax.mail.MessageAware
 * @see javax.activation.DataSource
 * @see javax.activation.DataContentHandler
 */
public class MessageContext {

    /**
     * Create a MessageContext object describing the context of the 
     * given Part.
     */
    public MessageContext(Part part)

    /**
     * Return the Part that contains the content.
     *
     * @return	the containing Part, or null if not known
     */
    public Part getPart()

    /**
     * Return the Message that contains the content.
     * Follows the parent chain up through containing Multipart
     * objects until it comes to a Message object, or null.
     *
     * @return	the containing Message, or null if not known
     */
    public Message getMessage()

    /**
     * Return the Session we're operating in.
     *
     * @return	the Session, or null if not known
     */
    public Session getSession()
}


A MessageContext object can be obtained by a DataContentHandler from a
DataSource that also implements the MessageAware interface:

/**
 * An interface optionally implemented by <code>DataSources</code> to
 * supply information to a <code>DataContentHandler</code> about the
 * message context in which the data content object is operating.
 *
 * @see javax.mail.MessageContext
 * @see javax.activation.DataSource
 * @see javax.activation.DataContentHandler
 */
public interface MessageAware {
    /**
     * Return the message context.
     */
    public MessageContext getMessageContext();
}


This new interface and class provides the basic information needed by
the DataContentHandler to use in constructing more "interesting" objects
representing a particular type of data.

To allow navigation up the chain of components contained in a Message,
we add the following methods.

First, on BodyPart we add:

    /**
     * The <code>Multipart</code> object containing this 
     * <code>BodyPart</code>, if known.
     */
    protected Multipart parent;

    /**
     * Return the containing <code>Multipart</code> object,
     * or <code>null</code> if not known.
     */
    public Multipart getParent()


On Multipart we add:

    /**
     * The <code>Part</code> containing this <code>Multipart</code>,
     * if known.
     */
    protected Part parent;

    /**
     * Return the <code>Part</code> that contains this
     * (cod<code>Multipart</c object, or <code>null</code> if not known.
     */
    public Part getParent()

    /**
     * Set the parent of this <code>Multipart</code> to be the specified
     * <code>Part</code>.  Normally called by the <code>Message</code>
     * or <code>BodyPart</code> <code>setContent(Multipart)</code>
     * method. <p>
     *
     * <code>parent</code> may be <code>null</code> if the
     * <code>Multipart</code> is being removed from its containing
     * <code>Part</code>.
     */
    public void setParent(Part parent)


To enable this new functionality we change the implementations of
MimeBodyPart, MimeMessage, and MimeMultipart to maintain the "parent"
links where possible.  We also change MimePartDataSource to implement
the MessageAware interface.

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

(2) MessageID
=============
The MimeMessage class requires a getMessageID() method.

The client can now fetch it as a header, but since this is a "standard"
RFC822 header, we want to provide an easier access method. 

An added benefit is that protocols like IMAP, which provide this info
as part of the ENVELOPE structure, can implement this method much more
efficiently.

 /**
  * Returns the value of the "Message-ID" header field. Returns
  * null if this field is unavailable or its value is absent. <p>
  *
  * The default implementation provided here uses the
  * <code>getHeader()</code> method to return the value of the
  * "Message-ID" field.
  *
  * @return 	Message-ID
  * @exception	MessagingException, if the retrieval of this field
  *		causes any exception.
  * @see	javax.mail.search.MessageIDTerm
  */
  public String getMessageID() throws MessagingException;

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

(3) UIDFolder
=============

The following methods in the UIDFolder interface have certain problems.

We are proposing changes that will fix these problems. These are
binary incompatible changes, but we think these changes are necessary for
this interface to work in a useful manner. We are also not aware of
anyone that has shipped a Store Provider that implements this interface,
so we are hoping that the effect of this change is minimal (non-existent).

(1) Message getMessageByUID(long uid)

Description:
	Get the Message corresponding to the given UID. If no such
message exists, the java.util.NoSuchElementException is thrown.

Problem:
	A disconnected client can have a stash of UIDs from a
previous session. Some of these UIDs may have been expunged from the
server, but the disconnected client does not know this. It is quite
reasonable (and expected) for a disconnected client to use this
method when reconnecting - to check whether a UID is valid or not at
the server.
	Since failure is an expected result here, using a
RunTimeException to indicate it, seems wrong and counter-intuitive for
the client.

Solution:
	Our solution is to allow this method to return null to indicate
that the requested UID is not valid anymore. Thus, this method will no
longer throw the java.util.NoSuchElementException.

(2)  Message[] getMessagesByUID(long start, long end)

Description:
	Get the Messages corresponding to the given UID range. If any
UID is invalid, the java.util.NoSuchElementException is thrown.

Problem:
	Similar, but worse than (1). We think that disconnected clients
(or clients that prefer to use UIDs) may issue 
	getMessagesByUID(1, LASTUID) 
to get all the Messages at the server, especially when the client does
not know the exact UIDs for this folder. In this case, we certainly
do not want this method to fail if some id in the given range is 
not a valid UID; rather we want it to return all available Messages from
the server.

Solution:
	Our solution is to remove the NoSuchElementException exception
and allow this method to return Message objects in the given range.

(3) Message[] getMessagesByUID(long[] uids)

Description:
	Get the Messages corresponding to the given UID range. If any
UID is invalid, the java.util.NoSuchElementException is thrown.

Problem:
	Identical to (1).
	A disconnected client can have a stash of UIDs from a
previous session. Some of these UIDs may have been expunged from the
server, but the disconnected client does not know this. It is quite
reasonable (and expected) for a disconnected client to use this
method when reconnecting - to check whether a set of UIDs are valid
or not at the server.
	Since failure can be an expected result, using a
RunTimeException to indicate it, seems wrong and counter-intuitive for
the client.

Solution:
	Our solution is to allow this method to return null entries
to indicate that a requested UID is not valid anymore. Thus, the
message array returned by this method can have null entries for the
invalid UIDs; and this method will no longer throw the 
java.util.NoSuchElementException.
	Note that the size of the returned Message array is the same
as the size of the request array of UIDs, and that each entry in the
Message array corresponds to the same index entry in the UID array.
===================================================================

(4) InternetAddress
===================

The InternetAddress class needs the following protected field to
properly support encoding of the "personal name".

	protected String encodedPersonal; // the encoded personal name

No other API changes are associated with this. 

This is a binary compatible change to JavaMail 1.0. However, there is
a potential problem for any existing InternetAddress subclasses, which
can cause them to break. This typically will affect only providers,
not clients.

Details:
-------

The InternetAddress implementation will use this field to store the
encoded personal name. 

	The getPersonal() method will return the protected
'personal' field; if this field is null, it will check the 'encodedPersonal'
field and decode its value and return it.
	The toString() method will use the protected 'encodedPersonal'
field to create the RFC2047 compliant address string. If this field is
null, it will check the 'personal' field, encode that if necessary and
use it.

This implies that, if an InternetAddress subclass changes either 
the 'personal' or 'encodedPersonal' fields,  it should set the other
to null to force its recomputation. Unfortunately, this also implies
that existing subclasses of InternetAddress that directly set the
'personal' field can break in certain situations.
	We feel that the risk of this happening is minimal, since we
don't expect that our users have subclassed InternetAddress. Also, this
is necessary to properly support encoded personal names, so we feel that
this has to be done.
================================================================

(5) MimeCharset
================

A utility method to convert java charsets into MIME charsets is
needed.

The JDK supports a variety of charsets. The JDK has names for these
charsets, unfortunately they dont always match to their MIME or IANA
equivalents. 

It is necessary in some cases, (especially for providers) to map the
JDK charset names into their MIME or IANA equivalents. This method does
that.

The API:
-------

This is a new static method to the javax.mail.internet.MimeUtility class

	/**