COMPATIBILITY NOTES
			===================

		    Jakarta Mail API ${mail.version} release
		    ------------------------------

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.<protocol>.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.<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
	"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.<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.