COMPAT.txt revision 726
19557f192d37cd54a1a090a8a26d9d47265e4413Aki Tuomi COMPATIBILITY NOTES
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi ===================
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi JavaMail(TM) API ${mail.version} release
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi ------------------------------
316cbe323513a0f20d1cf519fe9405e231d633e2Aki TuomiThe JavaMail 1.5 specification is fully compatible with the JavaMail
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi1.4 specification, with the exceptions listed below.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki TuomiIn addition, changes in the implementation may impact
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomiapplications that depend on behavior beyond what is defined by the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki TuomiJavaMail specification, or that use features specific to the reference
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomiimplementation. This note summarizes potential compatibility issues
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomiwith this release of the JavaMail API.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi-- JavaMail 1.5.4 --
17fbd200b78112bd0d89e89598aa01cea72a74e5Martti Rannanjärvi- Idlemanager.watch no longer throws IOException
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The IdleManager.watch method was declared to throw IOException,
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi but never actually threw it. The declaraction has been changed,
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi which will cause a source incompatibility for code expecting to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi catch IOException when calling the watch method.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi-- JavaMail 1.5.3 --
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- Date search terms result in wrong greater-than SEARCH commands for IMAP
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The IMAP SentDateTerm and ReceivedDateTerm greater-than comparison
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi was actually doing a greater-than-or-equal-to comparison. This
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi has been fixed in the 1.5.3 release, but programs that accidentally
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi relied on the old behavior may get different results.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- Authenticator is now synchronized
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The call to the Authenticator's getPasswordAuthentication method
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi is now synchronized so that the state stored in the Authenticator
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi is safe if multiple threads try to use the Authenticator
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi simultaneously. If the application's getPasswordAuthentication
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi method blocks, it will prevent other threads in the same
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi Session from using the Authenticator.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi-- JavaMail 1.5 --
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- RFC 2231 parameter encoding/decoding enabled by default
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The System properties "mail.mime.decodeparameters" and
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi "mail.mime.encodeparameters" now default to true instead of false.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi Now that most mailers support RFC 2231, this is expected to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi increase interoperability, although in rare cases, and especially
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi when dealing with older mailers, this may cause problems.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi Parameters may appear encoded, and with a different name,
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi than what the receiver is expecting.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- ContentType.toString and ContentDisposition.toString never return null
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi These methods were previously documented to return null in
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi error cases when the fields of the class were not valid.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi These methods now return an empty string in these cases, to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi be consistent with the general contract of Object.toString.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- additional classes, methods, and fields
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi JavaMail 1.5 adds classes to existing packages, methods to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi existing classes, and fields to existing classes. All of
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi these changes have the potential to break source compatibility
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi for applications using the JavaMail API.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- JDK 1.5 or newer required
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The JavaMail reference implementation now requires JDK 1.5
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi or newer. It is expected that the large majority of users
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi are already using JDK 1.6 or newer.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- protected fields in final classes in javax.mail.search made private
c147bff818798a979d93537f72f5c1f68f5d5ba8Aki Tuomi Some of the final classes in the javax.mail.search package
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi contained protected fields. Since these classes were final
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi and couldn't be subclassed, the "protected" access qualifier
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi had no effect. These fields are now private. It's hard to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi imagine how this change could impact any applications other
a84b413ef72378bbe235a13846fe6a84899eaedcTimo Sirainen than perhaps those using reflection to access these classes.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- MailHandler default attachment filters
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The default used for attachment filters has changed from allow
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi all log records (null) to instead use body filter assigned to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi getFilter(). This is a safer choice as it maintains any
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi existing filter rules when attachments are added.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- MailHandler default 'TO' address recipient
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi If the 'TO' address key is not specified then the local address
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi is used. The previous behavior was to omit the 'TO' address
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi header. This can break configurations that are only sending to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi a set of 'CC' or 'BCC' addresses. To revert this behavior
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi simply specify a 'TO' address key with an empty address value.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- MailHandler intern of error manager, filters, and formatters.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi When MailHandler is created, the error manager, filters, and
c147bff818798a979d93537f72f5c1f68f5d5ba8Aki Tuomi formatters are checked for equality. When equal objects are
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi found they are replaced with a single representation. This
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi allows objects of the same type to share state for improving
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi performance, adding functionality, etc. To revert to the
32340fe8f461f6ae56c4cb3ee8392ba14c9f539aAki Tuomi previous behavior the error manager, filters, and formatters
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi must retain or be wrapped with objects that retain the identity
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi equals and hash code to prevent interning.
32340fe8f461f6ae56c4cb3ee8392ba14c9f539aAki Tuomi-- JavaMail 1.4.4 --
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- authorization ID may be null
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The IMAP and SMTP providers support a
32340fe8f461f6ae56c4cb3ee8392ba14c9f539aAki Tuomi "mail.<protocol>.sasl.authorizationid" property that allows you
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi to specify an authorization ID separately from the authentication
32340fe8f461f6ae56c4cb3ee8392ba14c9f539aAki Tuomi ID that's specified as the user name in properties or in the connect
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi method. The PLAIN authentication method, and some SASL authentication
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi methods support use of the separate authorization ID. In previous
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi releases, if the authorization ID was not specified, it defaulted
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi to the authentication ID (user name). This can cause problems if
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the server doesn't allow an authorization ID even though the SASL
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi method allows specifying one. In this release, if no authorization
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi ID is specified, null is passed to the SASL method. If this causes
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi problems for a SASL method implementation or a server, the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi "mail.<protocol>.sasl.authorizationid" property should be set to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the user name used for authentication.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi-- JavaMail 1.4.3 --
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- SMTPTransport.isConnected behavior changed
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The SMTPTransport.isConnected method uses the SMTP NOOP command
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi to determine if the server is still alive. Because many older
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi servers were broken in various ways, any response (other than
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the 421 "connection timed out" response) was considered a
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi successful response and the server was considered to be still
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi alive. Unfortunately, Microsoft Exchange has a bug that causes
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi it to return a response code of 451 when it times out a connection
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi instead of the expected 421 response code. SMTPTransport.isConnected
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi now considers only a 250 response code to indicate success, per
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the SMTP spec. The old behavior can be restored by setting the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi new mail.smtp.noop.strict property to false.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi-- JavaMail 1.4.2 --
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- mail.smtp.quitwait default changed
c147bff818798a979d93537f72f5c1f68f5d5ba8Aki Tuomi In previous releases, JavaMail would drop the SMTP connection
c147bff818798a979d93537f72f5c1f68f5d5ba8Aki Tuomi to the server immediately after sending the QUIT command.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi This violates the SMTP spec. The property "mail.stmp.quitwait"
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi controls this behavior. In this release the default behavior
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi (if the property isn't specified) has changed so that JavaMail
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi will wait for the response from the server before dropping the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi connection. In some cases, with some servers, this additional
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi wait time may be noticeable.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The MessagingException class, which is the base class for all
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi JavaMail exceptions, has been retrofitted to support the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi exception chaining feature added to the java.lang.Throwable
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi class in J2SE 1.4. The visible impact of this change is that
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the String returned by the getMessage method will only return
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the immediate message for the top level exception, instead of
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi including messages for all nested exceptions.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- connection timeouts no longer use a thread
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi To support connection timeouts in older versions of the JDK,
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi it was necessary for JavaMail to create a thread to make the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi connection, so that it could interrupt and abandon that
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi thread if the connection timeout expired. J2SE 1.4 added
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the ability to specify the connection timeout directly, so
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi JavaMail no longer uses an additional thread for this purpose.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- ByteArrayDataSource now part of javax.mail.util
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The ByteArrayDataSource class, which was previously included
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi in source form in the demo directory, is now a standard part
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi of the JavaMail API in the new javax.mail.util package.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi Applications that are modified to make use of classes in the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi new package, and that also included a copy of the demo version
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi of ByteArrayDataSource, should be careful to avoid potential
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi name conflicts between these two classes.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- mail.SSLSocketFactory.class property no longer supported
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The JavaMail implementation previously used this undocumented
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi property to locate the SSLSocketFactory from which it would
d82c8af717c383d37a836b8d29316a3375803fabTimo Sirainen create SSLSockets when making an SSL or TLS connection. This
d82c8af717c383d37a836b8d29316a3375803fabTimo Sirainen property is no longer used. The standard
d82c8af717c383d37a836b8d29316a3375803fabTimo Sirainen javax.net.ssl.SSLSocketFactory is used instead, which supports
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi a standard way of overriding the choice of default SSLSocketFactory.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi See the SSLSocketFactory javadocs for details. Most applications
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi should never need to override the default SSLSocketFactory.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- Quota class moved from com.sun.mail.imap to javax.mail
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The new Quota APIs in JavaMail are taken directly from the old
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi IMAP-specific classes in the com.sun.mail.imap package. If you've
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi been using these classes, you'll need to update your application
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi to use the new classes in the javax.mail package.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi- getProtocol method removed from com.sun.mail.imap.IMAPFolder
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi The getProtocol method returns an instance of IMAPProtocol.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi This was originally intended to allow applications to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi experiment with extending the IMAP protocol support to use IMAP
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi commands not directly implemented by the IMAP protocol
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi provider. Unfortunately, to safely use the IMAPProtocol
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi object, you need to obey the locking requirements of the
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi IMAPFolder object, and there's no way to do that from outside
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi the IMAPFolder object. The doCommand method was added to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi IMAPFolder to resolve this problem. Now, with the introduction
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi of IDLE support to the IMAP protocol provider, it's critical to
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi obey the locking requirements. To prevent mistakes, the old,
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi unsafe, getProtocol method has been removed. Applications
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi should use the doCommand method for simple IMAP extensions.
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi Use of more complex IMAP extensions may require modification
316cbe323513a0f20d1cf519fe9405e231d633e2Aki Tuomi of the IMAP protocol provider.