javamail-1.1.txt

SUN的JAVA MAIL API

	 * Convert a java charset into its MIME charset name. <p>
	 *
	 * Note that a future version of JDK (post 1.2) might provide
	 * this functionality, in which case, we might deprecate this
	 * method then.
	 *
	 * @param   charset    the JDK charset
	 * @return	the MIME/IANA equivalent. If a mapping
	 *		is not possible, the passed in charset itself
	 *		is returned.
	 */			
	public static String mimeCharset(String charset);

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

(6) getDefaultJavaCharset()
============================

This method returns the default charset for the platform's locale, as
a Java charset. This is a new static method to the MimeUtility class.

    /**
     * Get the default charset for this locale. <p>
     *
     * @return  the default charset of the platform's locale,
     *          as a Java charset. (NOT a MIME charset)
     */
    public static String getDefaultJavaCharset()

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

(7) Method to print out the nested Exceptions
=============================================

The MessagingException class currently allows nested exceptions. It
would be nice to have one single method to dump out all the 
nested exceptions' messages into System.out

Proposal
--------

Override the getMessage() method from the superclass (Throwable), to
append the messages from all nested Exceptions. This is similar to
java.rmi.RemoteException.

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

(8) New SearchTerms
====================

The current address related search terms - AddressTerm, FromTerm and
RecipientTerm are limited in that they operate on Address objects, not
Strings. These terms use the equals() method to compare the addresses -
which is not useful for the common case of substring comparisons.

Hence we introduce three new SearchTerms:

public AddressStringTerm extends StringTerm {
    /**
     * Constructor.
     * @param pattern	the address pattern to be compared
     */
    protected AddressStringTerm(String pattern);

    /**
     * Check whether the address pattern specified in the 
     * constructor is a substring of the string representation of 
     * the given Address object.
     *
     * @param	address	the address to match against
     */
    protected boolean match(Address address);
}

public FromStringTerm extends AddressStringTerm {
    /**
     * Constructor.
     * @param	address	the address to be compared.
     */
    public FromStringTerm(String string);

    /**
     * Check whether the address specified in the constructor is
     * a substring of the "From" attribute of this message.
     *
     * @param	msg the address comparison is applied to this Message
     */
     public boolean match(Message msg);
}

public RecipientStringTerm extends AddressStringTerm {

    /**
     * Constructor.
     *
     * @param type      the recipient type
     * @param address	the address to be compared.
     */
    public RecipientStringTerm(Message.RecipientType type, String address);

    /**
     * Return the type of recipient to match with.
     */
    public Message.RecipientType getRecipientType();

    /**
     * Check whether the address specified in the constructor is
     * a substring of the given Recipient attribute of this message.
     *
     * @param	msg the address comparison is applied to this Message
     */
     public boolean match(Message msg);
}

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

(9) InternetAddress.toString(Address[] addresses, int used)
===========================================================

As per RFC2047 (MIME), the length of a header field that contains
encoded-words is limited to 76 characters.

There are two methods in the InternetAddress class that generate
RFC822 style address strings:

 - The toString() method on InternetAddress, which generates
 the string for one InternetAddress object
 - The toString() static method, which generates a comma separated
 string for the given array of InternetAddress objects.

Both these methods currently do not honor the 76 character limit.
Actually, the former does to an extent, since the encodedWord
generator (i.e the MimeUtility.encodeWord() method) does break
encoded words into multiples, if they stretch beyond 76 characters.

Solution
--------

For the 1.1 release, we are planning to fix the the toString()
static method as follows:

Add a new static method 
	static String toString(Address[] address, int used)

This method takes an array of Address objects and an integer representing
the number of "used" character positions for the first line of this
field. The typical use of this method is when setting RFC822 headers,
like the "From" header. 'used' can be set to sizeof("From: ") in
this case.

When generating the string, this method starts a new line if the
addition of the next address.toString() causes the current line's 
line-length to go over 76.

Note that this algorithm does not work right if the length of a single
InternetAddress is itself more than 76 characters. Also, it does not
optimally break an address field, so that the maximum characters are
accommodated in a single line.

So, essentially, this is an initial attempt to solve this problem. We
will add more APIs in the next version to further refine this.
==================================================================

(10) Folder.getMode()
=====================

It is currently not possible to tell whether a folder is open READ_ONLY
or READ_WRITE without attempting to write it and catching the exception.

We propose to add a protected field to Folder to store the open mode and
a new method to Folder to return the open mode.  Because existing 
subclasses will not use this new field, we can't guarantee that the 
method will always return the correct value (although all Folder subclasses
in the JavaMail package will be updated to return the correct value).

    /**
     * The open mode (<code>Folder.READ_ONLY</code>,
     * <code>Folder.READ_WRITE</code>, or -1 if not known).
     */
    protected int mode = -1;

    /**
     * Return the open mode of this folder.  Returns
     * <code>Folder.READ_ONLY</code>, <code>Folder.READ_WRITE</code>,
     * or -1 if the open mode is not known (usually only because an older
     * <code>Folder</code> provider has not been updated to use this new
     * method).
     *
     * @exception	IllegalStateException if this folder is not opened
     * @return	        the open mode of this folder
     */
    public int getMode() {
	if (!isOpen())
	    throw new IllegalStateException("Folder not open");
	return mode;
    }

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

(11) Folder.getURLName()
========================

The URLName support in the JavaMail 1.0 API's is incomplete and
inadequately specified.  While you can get a Folder from a Session
given a URLName for the folder, you can't find out the URLName
for a given Folder object.  We propose adding the following method
to Folder:

    /**
     * Return a URLName representing this folder.  The returned URLName
     * does <em>not</em> include the password used to access the store.
     *
     * @return	the URLName representing this folder
     * @see	URLName
     */
    public URLName getURLName() throws MessagingException

Previously it was not specified whether the URLName returned from
the Store.getURLName method would include the password field or
not, but sometimes it did.  We propose to tighen the specification
and fix the implementation so that the password field is not returned:

    /**
     * Return a URLName representing this store.  The returned URLName
     * does <em>not</em> include the password field.  <p>
     *
     * Subclasses should only override this method if their
     * URLName does not follow the standard format.
     *
     * @return	the URLName representing this store
     * @see	URLName
     */
    public URLName getURLName()

Similarly for Transport.

Previously it was unspecified how the Store and Transport connect
methods interacted with the url field.  In some cases it would be
updated and in other cases it would not.  We propose to tighen the
specification as follows:

    /**
     * Connect to the specified address. This method provides a simple
     * authentication scheme that requires a username and password. <p>
     *
     * If the connection is successful, an "open" ConnectionEvent is
     * delivered to any ConnectionListeners on this Store. <p>
     *
     * It is an error to connect to an already connected Store. <p>
     *
     * The implementation in the Store class will collect defaults
     * for the host, user, and password from the session, prompting the
     * user if necessary, and will then call the protocolConnect method,
     * which the subclass must override.  The subclass should also
     * implement the <code>getURLName</code> method, or use the 
     * implementation in this class. <p>
     *
     * On a successful connection, the <code>setURLName</code> method is
     * called with a URLName that includes the information used to make
     * the connection, including the password. <p>
     *
     * If the password passed in is null and this is the first successful
     * connection to this store, the user name and the password
     * collected from the user will be saved as defaults for subsequent
     * connection attempts to this same store.  If the password passed
     * in is not null, it is not saved, on the assumption that the 
     * application is managing passwords explicitly.
     *
     * @param host 	the host to connect to
     * @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 store is already connected
     * @see javax.mail.event.ConnectionEvent
     */
    public void connect(String host, String user, String password)
			throws MessagingException

And add this method to Store and Transport:

    /**
     * Set the URLName representing this store.
     * Normally used to update the <code>url</code> field
     * after a store has successfully connected. <p>
     *
     * Subclasses should only override this method if their
     * URLName does not follow the standard format. <p>
     *
     * The implementation in the Store class simply sets the
     * <code>url</code> field.
     *
     * @see URLName
     */
    protected void setURLName(URLName url)

And finally, to simplify the implementation of Store and Transport,
and make the common design patterns between them more clear, we're
considering introducing a new Service class as a superclass of
Store and Transport, and moving all common methods (the various
connnect methods, URLName methods, and some listener methods) to
the superclass.  Note that this is a binary compatible change.

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

12) New Service class
======================

To emphasize the commonality in behavior between the Store and
Transport classes, and to simplify maintenance of these classes, we
propose moving many of the common methods to a new superclass called
javax.mail.Service.  Store and Transport would then extend Service.
These existing methods currently have identical implementations in the
Store and Transport classes so moving them to a common superclass will
not change the behavior of either Store or Transport.

The Service class will contain all the methods and fields having to do
with connecting, connection listeners, and naming via URLNames.  The
Store class retains the methods for getting Folders and managing Store
and Folder listeners.  The Transport class retains the methods for
sending messages and managing Transport listeners.

Note that this is a binary compatible change both for existing users of
the Store and Transport classes, as well as for existing subclasses of
these classes.

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