javamail-1.2-changes.txt

Java mail client (get all message on mails erver)

     * 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)