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