doc/spec/JavaMail-1.3-changes.txt - jakartaee/mail-api - Git at Google


 		JavaMail 1.3
 		============

 		(Updated April 1, 2002)

 Following is a description of the new APIs that are being
 introduced in JavaMail 1.3.  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 javamail@sun.com.

 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."


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

 1. Add setSender and getSender methods to MimeMessage (4405115)
 ---------------------------------------------------------------

 These convenience methods support setting and reading the RFC 822
 Sender header.

     /**
      * Returns the value of the RFC 822 "Sender" header field.
      * If the "Sender" header field is absent, <code>null</code>
      * is returned.<p>
      *
      * This implementation uses the <code>getHeader</code> method
      * to obtain the requisite header field.
      *
      * @return		Address object
      * @exception	MessagingException
      * @see		#headers
      * @since		JavaMail 1.3
      */
     public Address getSender() throws MessagingException

     /**
      * Set the RFC 822 "Sender" header field. Any existing values are
      * replaced with the given address. If address is <code>null</code>,
      * this header is removed.
      *
      * @param address	the sender of this message
      * @exception	IllegalWriteException if the underlying
      *			implementation does not support modification
      *			of existing values
      * @exception	IllegalStateException if this message is
      *			obtained from a READ_ONLY folder.
      * @exception	MessagingException
      * @since		JavaMail 1.3
      */
     public void setSender(Address address) throws MessagingException

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

 2. Add setContentID method to MimeBodyPart (4377720)
 ----------------------------------------------------

 This convenience method supports setting the Content-ID header.

     /**
      * Set the "Content-ID" header field of this body part.
      * If the <code>cid</code> parameter is null, any existing
      * "Content-ID" is removed.
      *
      * @exception	IllegalWriteException if the underlying
      *			implementation does not support modification
      * @exception	IllegalStateException if this body part is
      *			obtained from a READ_ONLY folder.
      * @exception	MessagingException
      * @since		JavaMail 1.3
      */
     public void setContentID(String cid) throws MessagingException

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

 3. Add mail.mime.charset property (4377731)
 -------------------------------------------

 The "mail.mime.charset" System property (NOTE: *not* Session property)
 names the default charset to be used by JavaMail.  If not set, the
 standard J2SE "file.encoding" System property is used.  This allows
 applications to specify a default character set for sending messages
 that's different than the character set used for files stored on the
 system.  This is common on Japanese systems.

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

 4. Add getDeletedMesageCount method to Folder (4388730)
 -------------------------------------------------------

 This convenience method would return a count of the number of deleted
 messages in a folder.

     /**
      * Get the number of deleted messages in this Folder. <p>
      *
      * This method can be invoked on a closed folder. However, note
      * that for some folder implementations, getting the deleted message
      * count can be an expensive operation involving actually opening
      * the folder. In such cases, a provider can choose not to support
      * this functionality in the closed state, in which case this method
      * must return -1. <p>
      *
      * Clients invoking this method on a closed folder must be aware
      * that this is a potentially expensive operation. Clients must
      * also be prepared to handle a return value of -1 in this case. <p>
      *
      * This implementation returns -1 if this folder is closed. Else
      * this implementation gets each Message in the folder using
      * <code>getMessage(int)</code> and checks whether its
      * <code>DELETED</code> flag is set. The total number of messages
      * that have this flag set is returned.
      *
      * @return 		number of deleted messages. -1 may be returned
      *			by certain implementations if this method is
      *			invoked on a closed folder.
      * @exception	FolderNotFoundException if this folder does
      *			not exist.
      * @exception       MessagingException
      * @since		JavaMail 1.3
      */
     public int getDeletedMessageCount() throws MessagingException

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

 5. Support parsing "illegal" Internet addresses (4650940)
 ---------------------------------------------------------

 The parse method on the InternetAddress class takes a flag that tells
 whether or not to strictly enforce the RFC822 syntax rules.  Currently,
 when the flag is false most rules are still checked while a few are not.
 To better support the range of "invalid" addresses seen in real messages,
 and in combination with the following two changes, the parseHeader
 method would enforce fewer syntax rules when the strict flag is false
 and would enforce more rules when the strict flag is true.  If the
 strict flag is false and the parse is successful in separating out an
 email address or addresses, the syntax of the addresses themselves
 would not be checked.  (Introducing a new method preserves
 compatibility with users of the existing parse method.)

     /**
      * Parse the given sequence of addresses into InternetAddress
      * objects.  If <code>strict</code> is false, the full syntax rules for
      * individual addresses are not enforced.  If <code>strict</code> is
      * true, many (but not all) of the RFC822 syntax rules are enforced.
      *
      * Non-strict parsing is typically used when parsing a list of
      * mail addresses entered by a human.  Strict parsing is typically
      * used when parsing address headers in mail messages.
      *
      * @param	addresslist	comma separated address strings
      * @param	strict		enforce RFC822 syntax
      * @return			array of InternetAddress objects
      * @exception	AddressException if the parse failed
      * @since		JavaMail 1.3
      */
     public static InternetAddress[] parseHeader(String s, boolean strict)
 					    throws AddressException


 To allow applications to check the syntax of addresses that might've
 been parsed with the strict flag set to false, we add a validate
 method.

     /**
      * Validate that this address conforms to the syntax rules
      * of RFC 822.  The current implementation checks many, not
      * all, syntax rules.  Note that, even though the syntax of
      * the address may be correct, there's no guarantee that a
      * mailbox of that name exists.
      *
      * @exception	AddressException if the address
      *			isn't valid.
      * @since		JavaMail 1.3
      */
     public void validate() throws AddressException


 To control the strict flag when constructing a single InternetAddress
 object we add a new constructor.

     /**
      * Parse the given string and create an InternetAddress.
      * If <code>strict</code> is false, the detailed syntax of the
      * address isn't checked.
      *
      * @param	address		the address in RFC822 format
      * @param	strict		enforce RFC822 syntax
      * @exception		AddressException if the parse failed
      * @since			JavaMail 1.3
      */
     public InternetAddress(String address, boolean strict)
 						throws AddressException

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

 6. Add mail.mime.address.strict property (4650940)
 --------------------------------------------------

 The MimeMessage class will use the new parseHeader method introduced
 above to parse headers in messages.  The "mail.mime.address.strict"
 Session property will control the strict flag passed to the parseHeader
 method.  The default is true.

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

 7. Add mail.mime.decodetext.strict property (4201203)
 -----------------------------------------------------

 RFC 2047 requires that encoded text start at the beginning of a
 whitespace separated word.  Some mailers, especially Japanese mailers,
 improperly encode text and included encoded text in the middle of words.
 The "mail.mime.decodetext.strict" System property (NOTE: *not* Session
 property) controls whether JavaMail will attempt to decode such
 incorrectly encoded text.  The default is true.

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

 8. Add mail.mime.encodeeol.strict property (4650949)
 ----------------------------------------------------

 When choosing an encoding for the data of a message, JavaMail assumes
 that any of CR, LF, or CRLF are valid line terminators in message
 parts that contain only printable ASCII characters, even if the part is
 not a MIME text type.  It's common, especially on UNIX systems, for
 data of MIME type application/octet-stream (for example) to really be
 textual data that should be transmitted with the encoding rules for
 MIME text.  In rare cases, such pure ASCII text may in fact be binary
 data in which the CR and LF characters must be preserved exactly.  The
 "mail.mime.encodeeol.strict" System property (NOTE: *not* Session
 property) controls whether JavaMail will consider a lone CR or LF in a
 body part that's not a MIME text type to indicate that the body part
 needs to be encoded.

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

 9. Add isGroup and getGroup methods to InternetAddress (4650952)
 ----------------------------------------------------------------

 To better support RFC822 group addresses, the following methods
 would be added.

     /**
      * Indicates whether this address is an RFC 822 group address.
      * Note that a group address is different than the mailing
      * list addresses supported by most mail servers.  Group addresses
      * are rarely used; see RFC 822 for details.
      *
      * @return		true if this address represents a group
      * @since		JavaMail 1.3
      */
     public boolean isGroup()

     /**
      * Return the members of a group address.  A group may have zero,
      * one, or more members.  If this address is not a group, null
      * is returned.  The <code>strict</code> parameter controls whether
      * the group list is parsed using strict RFC 822 rules or not.
      * The parsing is done using the <code>parseHeader</code> method.
      *
      * @return		array of InternetAddress objects, or null
      * @exception	AddressException if the group list can't be parsed
      * @since		JavaMail 1.3
      */
     public InternetAddress[] getGroup(boolean strict) throws AddressException


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

 10. Support per-session debug output stream (4517686)
 -----------------------------------------------------

 To allow the debugging output for a session to be redirected, we add
 the following methods to Session.

     /**
      * Set the stream to be used for debugging output for this session.
      * If <code>out</code> is null, <code>System.out</code> will be used.
      * Note that debugging output that occurs before any session is created,
      * as a result of setting the <code>mail.debug</code> system property,
      * will always be sent to <code>System.out</code>.
      *
      * @param	out	the PrintStream to use for debugging output
      * @since		JavaMail 1.3
      */
     public void setDebugOut(PrintStream out)

     /**
      * Returns the stream to be used for debugging output.  If no stream
      * has been set, <code>System.out</code> is returned.
      *
      * @return		the PrintStream to use for debugging output
      * @since		JavaMail 1.3
      */
     public PrintStream getDebugOut()

	JavaMail 1.3
	============

	(Updated April 1, 2002)

	Following is a description of the new APIs that are being
	introduced in JavaMail 1.3. 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 javamail@sun.com.

	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."


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

	1. Add setSender and getSender methods to MimeMessage (4405115)
	---------------------------------------------------------------

	These convenience methods support setting and reading the RFC 822
	Sender header.

	/**
	* Returns the value of the RFC 822 "Sender" header field.
	* If the "Sender" header field is absent, <code>null</code>
	* is returned.<p>
	*
	* This implementation uses the <code>getHeader</code> method
	* to obtain the requisite header field.
	*
	* @return Address object
	* @exception MessagingException
	* @see #headers
	* @since JavaMail 1.3
	*/
	public Address getSender() throws MessagingException

	/**
	* Set the RFC 822 "Sender" header field. Any existing values are
	* replaced with the given address. If address is <code>null</code>,
	* this header is removed.
	*
	* @param address the sender of this message
	* @exception IllegalWriteException if the underlying
	* implementation does not support modification
	* of existing values
	* @exception IllegalStateException if this message is
	* obtained from a READ_ONLY folder.
	* @exception MessagingException
	* @since JavaMail 1.3
	*/
	public void setSender(Address address) throws MessagingException

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

	2. Add setContentID method to MimeBodyPart (4377720)
	----------------------------------------------------

	This convenience method supports setting the Content-ID header.

	/**
	* Set the "Content-ID" header field of this body part.
	* If the <code>cid</code> parameter is null, any existing
	* "Content-ID" is removed.
	*
	* @exception IllegalWriteException if the underlying
	* implementation does not support modification
	* @exception IllegalStateException if this body part is
	* obtained from a READ_ONLY folder.
	* @exception MessagingException
	* @since JavaMail 1.3
	*/
	public void setContentID(String cid) throws MessagingException

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

	3. Add mail.mime.charset property (4377731)
	-------------------------------------------

	The "mail.mime.charset" System property (NOTE: not Session property)
	names the default charset to be used by JavaMail. If not set, the
	standard J2SE "file.encoding" System property is used. This allows
	applications to specify a default character set for sending messages
	that's different than the character set used for files stored on the
	system. This is common on Japanese systems.

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

	4. Add getDeletedMesageCount method to Folder (4388730)
	-------------------------------------------------------

	This convenience method would return a count of the number of deleted
	messages in a folder.

	/**
	* Get the number of deleted messages in this Folder. <p>
	*
	* This method can be invoked on a closed folder. However, note
	* that for some folder implementations, getting the deleted message
	* count can be an expensive operation involving actually opening
	* the folder. In such cases, a provider can choose not to support
	* this functionality in the closed state, in which case this method
	* must return -1. <p>
	*
	* Clients invoking this method on a closed folder must be aware
	* that this is a potentially expensive operation. Clients must
	* also be prepared to handle a return value of -1 in this case. <p>
	*
	* This implementation returns -1 if this folder is closed. Else
	* this implementation gets each Message in the folder using
	* <code>getMessage(int)</code> and checks whether its
	* <code>DELETED</code> flag is set. The total number of messages
	* that have this flag set is returned.
	*
	* @return number of deleted messages. -1 may be returned
	* by certain implementations if this method is
	* invoked on a closed folder.
	* @exception FolderNotFoundException if this folder does
	* not exist.
	* @exception MessagingException
	* @since JavaMail 1.3
	*/
	public int getDeletedMessageCount() throws MessagingException

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

	5. Support parsing "illegal" Internet addresses (4650940)
	---------------------------------------------------------

	The parse method on the InternetAddress class takes a flag that tells
	whether or not to strictly enforce the RFC822 syntax rules. Currently,
	when the flag is false most rules are still checked while a few are not.
	To better support the range of "invalid" addresses seen in real messages,
	and in combination with the following two changes, the parseHeader
	method would enforce fewer syntax rules when the strict flag is false
	and would enforce more rules when the strict flag is true. If the
	strict flag is false and the parse is successful in separating out an
	email address or addresses, the syntax of the addresses themselves
	would not be checked. (Introducing a new method preserves
	compatibility with users of the existing parse method.)

	/**
	* Parse the given sequence of addresses into InternetAddress
	* objects. If <code>strict</code> is false, the full syntax rules for
	* individual addresses are not enforced. If <code>strict</code> is
	* true, many (but not all) of the RFC822 syntax rules are enforced.
	*
	* Non-strict parsing is typically used when parsing a list of
	* mail addresses entered by a human. Strict parsing is typically
	* used when parsing address headers in mail messages.
	*
	* @param addresslist comma separated address strings
	* @param strict enforce RFC822 syntax
	* @return array of InternetAddress objects
	* @exception AddressException if the parse failed
	* @since JavaMail 1.3
	*/
	public static InternetAddress[] parseHeader(String s, boolean strict)
	throws AddressException


	To allow applications to check the syntax of addresses that might've
	been parsed with the strict flag set to false, we add a validate
	method.

	/**
	* Validate that this address conforms to the syntax rules
	* of RFC 822. The current implementation checks many, not
	* all, syntax rules. Note that, even though the syntax of
	* the address may be correct, there's no guarantee that a
	* mailbox of that name exists.
	*
	* @exception AddressException if the address
	* isn't valid.
	* @since JavaMail 1.3
	*/
	public void validate() throws AddressException


	To control the strict flag when constructing a single InternetAddress
	object we add a new constructor.

	/**
	* Parse the given string and create an InternetAddress.
	* If <code>strict</code> is false, the detailed syntax of the
	* address isn't checked.
	*
	* @param address the address in RFC822 format
	* @param strict enforce RFC822 syntax
	* @exception AddressException if the parse failed
	* @since JavaMail 1.3
	*/
	public InternetAddress(String address, boolean strict)
	throws AddressException

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

	6. Add mail.mime.address.strict property (4650940)
	--------------------------------------------------

	The MimeMessage class will use the new parseHeader method introduced
	above to parse headers in messages. The "mail.mime.address.strict"
	Session property will control the strict flag passed to the parseHeader
	method. The default is true.

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

	7. Add mail.mime.decodetext.strict property (4201203)
	-----------------------------------------------------

	RFC 2047 requires that encoded text start at the beginning of a
	whitespace separated word. Some mailers, especially Japanese mailers,
	improperly encode text and included encoded text in the middle of words.
	The "mail.mime.decodetext.strict" System property (NOTE: not Session
	property) controls whether JavaMail will attempt to decode such
	incorrectly encoded text. The default is true.

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

	8. Add mail.mime.encodeeol.strict property (4650949)
	----------------------------------------------------

	When choosing an encoding for the data of a message, JavaMail assumes
	that any of CR, LF, or CRLF are valid line terminators in message
	parts that contain only printable ASCII characters, even if the part is
	not a MIME text type. It's common, especially on UNIX systems, for
	data of MIME type application/octet-stream (for example) to really be
	textual data that should be transmitted with the encoding rules for
	MIME text. In rare cases, such pure ASCII text may in fact be binary
	data in which the CR and LF characters must be preserved exactly. The
	"mail.mime.encodeeol.strict" System property (NOTE: not Session
	property) controls whether JavaMail will consider a lone CR or LF in a
	body part that's not a MIME text type to indicate that the body part
	needs to be encoded.

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

	9. Add isGroup and getGroup methods to InternetAddress (4650952)
	----------------------------------------------------------------

	To better support RFC822 group addresses, the following methods
	would be added.

	/**
	* Indicates whether this address is an RFC 822 group address.
	* Note that a group address is different than the mailing
	* list addresses supported by most mail servers. Group addresses
	* are rarely used; see RFC 822 for details.
	*
	* @return true if this address represents a group
	* @since JavaMail 1.3
	*/
	public boolean isGroup()

	/**
	* Return the members of a group address. A group may have zero,
	* one, or more members. If this address is not a group, null
	* is returned. The <code>strict</code> parameter controls whether
	* the group list is parsed using strict RFC 822 rules or not.
	* The parsing is done using the <code>parseHeader</code> method.
	*
	* @return array of InternetAddress objects, or null
	* @exception AddressException if the group list can't be parsed
	* @since JavaMail 1.3
	*/
	public InternetAddress[] getGroup(boolean strict) throws AddressException


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

	10. Support per-session debug output stream (4517686)
	-----------------------------------------------------

	To allow the debugging output for a session to be redirected, we add
	the following methods to Session.

	/**
	* Set the stream to be used for debugging output for this session.
	* If <code>out</code> is null, <code>System.out</code> will be used.
	* Note that debugging output that occurs before any session is created,
	* as a result of setting the <code>mail.debug</code> system property,
	* will always be sent to <code>System.out</code>.
	*
	* @param out the PrintStream to use for debugging output
	* @since JavaMail 1.3
	*/
	public void setDebugOut(PrintStream out)

	/**
	* Returns the stream to be used for debugging output. If no stream
	* has been set, <code>System.out</code> is returned.
	*
	* @return the PrintStream to use for debugging output
	* @since JavaMail 1.3
	*/
	public PrintStream getDebugOut()