Blame | Last modification | View Log | RSS feed
JavaMail 1.3============(Updated April 1, 2002)Following is a description of the new APIs that are beingintroduced in JavaMail 1.3. The numbers in parenthesesare bug numbers; you can find more information about thebug reports at:http://developer.java.sun.com/developer/bugParade/index.htmlPlease send comments and feedback to javamail@sun.com.Many of these changes expand JavaMail's conformance with Internetstandards, or make JavaMail more tolerant of messages that don'tquite conform to the standards. "Be liberal in what you receiveand conservative in what you send."===================================================================1. Add setSender and getSender methods to MimeMessage (4405115)---------------------------------------------------------------These convenience methods support setting and reading the RFC 822Sender 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, thestandard J2SE "file.encoding" System property is used. This allowsapplications to specify a default character set for sending messagesthat's different than the character set used for files stored on thesystem. This is common on Japanese systems.===================================================================4. Add getDeletedMesageCount method to Folder (4388730)-------------------------------------------------------This convenience method would return a count of the number of deletedmessages 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 tellswhether 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 parseHeadermethod would enforce fewer syntax rules when the strict flag is falseand would enforce more rules when the strict flag is true. If thestrict flag is false and the parse is successful in separating out anemail address or addresses, the syntax of the addresses themselveswould not be checked. (Introducing a new method preservescompatibility 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 AddressExceptionTo allow applications to check the syntax of addresses that might'vebeen parsed with the strict flag set to false, we add a validatemethod./*** 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 AddressExceptionTo control the strict flag when constructing a single InternetAddressobject 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 introducedabove to parse headers in messages. The "mail.mime.address.strict"Session property will control the strict flag passed to the parseHeadermethod. The default is true.===================================================================7. Add mail.mime.decodetext.strict property (4201203)-----------------------------------------------------RFC 2047 requires that encoded text start at the beginning of awhitespace 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* Sessionproperty) controls whether JavaMail will attempt to decode suchincorrectly 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 assumesthat any of CR, LF, or CRLF are valid line terminators in messageparts that contain only printable ASCII characters, even if the part isnot a MIME text type. It's common, especially on UNIX systems, fordata of MIME type application/octet-stream (for example) to really betextual data that should be transmitted with the encoding rules forMIME text. In rare cases, such pure ASCII text may in fact be binarydata in which the CR and LF characters must be preserved exactly. The"mail.mime.encodeeol.strict" System property (NOTE: *not* Sessionproperty) controls whether JavaMail will consider a lone CR or LF in abody part that's not a MIME text type to indicate that the body partneeds to be encoded.===================================================================9. Add isGroup and getGroup methods to InternetAddress (4650952)----------------------------------------------------------------To better support RFC822 group addresses, the following methodswould 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 addthe 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()