Please polish the content I am providing below and include it in JIRA 4.4.4 release notes (or perhaps rather summarise it with a sentence or two and link to a separate page with more details).

As described in JRA-26239, we decided to break backward compatibility in JIRA 4.4.4 release with respect to a piece of the API related to mail handling (which, as far as we know, is not used often).

Incompatibilities

JIRA 4.4.4 includes a dependency on atlassian-mail version 1.25 which is not 100% backward compatible with atlassian-mail 1.24 included in previous releases of JIRA.

JRIA 4.4.4 also ships with javamail 1.4.4, which we cannot guarantee is 100% compatible with javamail 1.4.1 (shipped with previous releases of JIRA).

Hence, there are two significant points to note as a result of these changes:

• The com.atlassian.mail.server.MailServer.getSession() method returns objects of the javax.mail.Session class rather than alt.javax.mail.Session
• The classes from mockobjects-j1.3-j2ee1.3.jar are no longer exported (i.e. made available) to Atlassian version 2 plugins. This jar is no longer distributed with JIRA.

Potential Impact and Solution

• We believe that very few (if any) 3rd party plugins will be affected by the two changes mentioned above and that such plugins will be broken as a result of these changes.
  
  • If your plugin uses the com.atlassian.mail.server.MailServer.getSession() method, doing either of the following should be sufficient to get it working with JIRA 4.4.4:
    • Recompile your plugin against 4.4.4
    • Use a higher level class like MailQueueItem.
      
      
  • If your plugin depends on mockobjects-j1.3-j2ee1.3.jar (which is highly unlikely and could be considered questionable), we encourage you to either:
    • Remove this dependency or
    • If it is not possible to remove this dependency, bundle this jar with the plugin.

According to the changelog for javamail (http://www.oracle.com/technetwork/java/javaee/changes-220864.txt), we believe that these changes should not negatively impact current plugins. On the contrary, many bug fixes and compatibility improvements in this new version of javamail should make existing JIRA mail handlers more robust.

Rationale

JIRA 4.4.4 comes with substantial mail logging improvements and capabilities, which should be valuable to customers and support personnel troubleshooting problems related to incoming and outgoing mail.

Part of this feature work required the need to upgrade both the atlassian-mail and javamail libraries to the versions mentioned above. The anticipated small negative impact resulting from these upgraded libraries led us to believe that there was little or no business justification for supporting their older versions.