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