COMPATIBILITY NOTES =================== Angus Mail 2.0.3 release ------------------------------ -- Angus Mail 2.0.3 -- - Server Identity Check performed by SSL endpoint identification algorithm The mail..ssl.checkserveridentity session property now uses the SSLParameters::setEndpointIdentificationAlgorithm on the SSLSocket. This is the recommended replacement for directly calling the "sun.security.util.HostnameChecker". Setting the endpoint identification algorithm parameter on the SSLSocket will make the X509ExtendedTrustManager assigned to the SSLSocket responsible for verifying the hostname instead of SocketFetcher class from Angus Mail. X509ExtendedTrustManager implementations are able to inspect that the mail..ssl.checkserveridentity session property was set by using the checkServerTrusted method which takes a socket parameter. The implementation must cast the given socket to a SSLSocket and then get the endpoint identification algorithm from the SSLParameters. If the value is non-null and non-empty then the mail..ssl.checkserveridentity session property is true. Implementations of X509ExtendedTrustManager can use this detail to alter the behavior of the hostname verification. TrustManager or X509TrustManager implementations are not able to disable this checking as they don't have direct access to the connected SSLSocket. X509ExtendedTrustManager implementations or SSLSocket implementations are able to alter or completely disable hostname checking. In previous releases of Angus Mail, a custom X509ExtendedTrustManager or a custom SSLSocket was able to disable verification at the socket level but could not disable hostname verification in Angus Mail provided by mail..ssl.checkserveridentity session property. This behavior has been relaxed in Angus Mail 2.0.3, where even though the mail..ssl.checkserveridentity session property was set to true the hostname verification may be disabled by a X509ExtendedTrustManager implementation, SSLSocketFactory implementation, or a SSLSocket implementation. For behavioral compatibility with previous release, where a custom X509ExtendedTrustManager, SSLSocketFactory, or a SSLSocket must not disable hostname checking, the session property "mail..ssl.hostnameverifier" must be set to an instance of a javax.net.ssl.HostnameVerifier or the session property "mail..ssl.hostnameverifier.class" must be set to a known alias name or a fully qualified class name of a javax.net.ssl.HostnameVerifier implementation. This javax.net.ssl.HostnameVerifier class will verify hostname independently of the mail..ssl.checkserveridentity session property. The recommended value for "mail..ssl.hostnameverifier.class" in this specific case is "MailHostnameVerifier". This verifier may not be as comprehensive as the "sun.security.util.HostnameChecker" could fail with false negatives. Using a 3rd party HostnameVerifier is a viable alternative in that case. For strict behavioral compatibility with previous release, where a custom X509ExtendedTrustManager, SSLSocketFactory, or a SSLSocket must not disable hostname checking or hostname checking unexpectedly failing, the "mail..ssl.hostnameverifier.class" session property to "legacy" which will attempt reflective access to the "sun.security.util.HostnameChecker" and will fallback to the "MailHostnameVerifier" in the event the "sun.security.util.HostnameChecker" is inaccessible. Using this value may result in reflective access warnings depending on the JDK in use. The was the exact behavior in the previous release of Angus Mail 2.0.3. The previous Angus Mail release did not perform endpoint identification which means the "mail..ssl.checkserveridentity" session property should be set but, is not required to be set to "false" in this case to disable newer RFC validation rules for hostname checking. - MailHandler public methods no longer hostile to invalid arguments Public methods that are contractually owned by MailHandler are no longer hostile to invalid input such as zero and null. When invalid or out of range values are used the MailHandler will use the same default that the LogManager would have chosen during creation. This allows bean style configurators to remove properties from the MailHandler without knowing the valid defaults for each property. -- Angus Mail 2.0.0 -- - Java package and java module names changed To different this project from its origin and match current maven coordinates and project name, java package and module names were renamed to start with "org.eclipse.angus.mail.". The same applies to supported property names. -- Angus Mail 1.1.0 -- - Server Identity Check is enabled by default RFC 2595 specifies addition checks that must be performed on the server's certificate to ensure that the server you connected to is the server you intended to connect to. This reduces the risk of "man in the middle" attacks. To disable these checks, set the "mail..ssl.checkserveridentity" property to "false". -- Angus Mail 1.0.0 -- The Angus Mail is the direct successor of the Jakarta Mail and implements Jakarta Mail 2.1 Specification. This version provides NO support for previous versions of the Jakarta Mail specification. -- Jakarta Mail 2.0.0 -- The Jakarta Mail 2.0 specification is the successor of the Jakarta Mail 1.6 specification. Except new package namespace - jakarta.mail there are no changes. -- Jakarta Mail 1.6.x -- The Jakarta Mail 1.6 specification is fully compatible with the JavaMail 1.5 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 Jakarta Mail specification, or that use features specific to the implementation. This note summarizes potential compatibility issues with this release of the Jakarta Mail API. -- Jakarta Mail 1.6.4 -- - Jakarta Mail is the new name for JavaMail. - NTLMv2 supported by default. Jakarta Mail now supports the newest NTLMv2 authentication protocol by default for any servers that support the NTLM authentication mechanism. All recent Microsoft Exchange servers support NTLMv2, but if this causes compatibility problems it can be disabled by setting the property "mail..auth.ntlm.v2" to "false". - Protocol providers now always loaded using ServiceLoader and config files The changes in Jakarta Mail 1.6.2 to use ServiceLoader introduced an incompatibility with some commonn use cases. To resolve that incompatibility, the load order for providers has changed to: 1. Non-default providers available as services. 2. Providers configured via javamail.providers. 3. Providers configured via javamail.default.providers. 4. Default providers available as services. An implementation-specific @DefaultProvider annotation is used to mark the providers included with Jakarta Mail (#4 above), and should not be used by applications. -- JavaMail 1.6.3 -- - Maven coordinates for JavaMail changed. JavaMail has moved to the Eclipse Foundation as part of the EE4J project, and will be included in the Jakarta EE specification. The Maven coordinates for JavaMail are now: - com.sun.mail:jakarta.mail - complete JavaMail jar file - jakarta.mail:jakarta.mail-api - API jar file for compiling only When updating dependencies to use JavaMail 1.6.3 or newer, the artifactId will need to be changed as above. The APIs are otherwise compatible. - Java module system name changed. Experimental support for the Java platform module system was added in the previous release using the name "java.mail" for the API module (mailapi.jar). In this release the name of that module is changed to "jakarta.mail". -- JavaMail 1.6.2 -- - Protocol providers now loaded using the java.util.ServiceLoader mechanism. All the protocol providers included with JavaMail, as well as third party providers, can use the Service Loader mechanism to configure the provider, instead of using the META-INF/javamail.default.providers or META-INF/javamail.providers file. These JavaMail provider configuration files are only read if the ServiceLoader fails to find a provider that supports the requested protocol. This may have the effect of changing the order in which providers are loaded, which should only be an issue if multiple providers support the same protocol name. -- JavaMail 1.6.1 -- - com.sun.mail.util.logging no longer included in mailapi.jar. If you're using mailapi.jar and depend on the com.sun.mail.util.logging classes, you'll need to include the logging-mailhandler.jar file in your application class path. -- JavaMail 1.6 -- - Public API updated to use generics Methods in the following classes have been updated to use generics. This change should be binary compatible but may require source code changes in applications. javax.mail.Multipart javax.mail.Part javax.mail.Service javax.mail.internet.InternetHeaders javax.mail.internet.MimeBodyPart javax.mail.internet.MimeMessage javax.mail.internet.MimePart javax.mail.internet.ParameterList - JDK 1.7 or newer required The JavaMail reference implementation now requires JDK 1.7 or newer. It is expected that the large majority of users are already using JDK 1.7 or newer. - MailDateFormat changes The following changes to MailDateFormat may impact applications: * parse(String) now throws a ParseException on invalid input instead of returning null, to conform to the DateFormat contract * the following methods now throw UnsupportedOperationException to prevent tampering with MailDateFormat's internals: get2DigitYearStart applyLocalizedPattern applyPattern set2DigitYearStart setDateFormatSymbols - method added to UIDFolder interface The UIDFolder interface has a new getUIDNext() method. Any classes implementing the UIDFolder interface will need to add this method. The IMAPFolder class implements the UIDFolder interface and has provided this method for some time. - YoungerTerm, OlderTerm, and ModifiedSinceTerm fall back to local searching In general, SearchTerms that are not understood by the IMAP provider or not supported by the IMAP server fall back to doing local searching. The IMAP-specific YoungerTerm, OlderTerm, and ModifiedSinceTerm were instead throwing an exception if the server didn't support the extension that the search term depended on. This has been fixed to fall back to doing the search locally. This behavior can be changed by setting the property "mail.imap.throwsearchexception" to "true" to cause an exception to be thrown if the server can't perform the search. -- 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..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 "mail.from" nor "mail.host" properties have been set. The System 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..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..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.