In JIRA 5.0 a number of classes related to message handling have been extracted into a JIRA Mail Plugin (JMP) which is bundled with JIRA.
Moreover, there are a number of functional changes around the configuration of incoming mail handlers, including a much better UI and support for a test run (dry run) - the user can test the behaviour of the handler by clicking Test on its configuration UI. As a result, the API has changed too.
JIRA 5.0 (as of RC1, with further changes in RC2) supports a new plugin point: the plugin module. This plugin module is actually defined by the JIRA Mail Plugin. More details on how to use the new module and how to build a handler configuration UI are given in a tutorial: Writing a Custom Message (Mail) Handler for JIRA.
In , the and methods now take an additional argument.
In the case of you should use the new argument to report all problems while initializing the handler.
The context is passed to . It should be used also to report progress (main events) while processing the message by the handler. Additionally, it provides a few of the methods typically used when creating JIRA entities, which transparently honour the mode in which the handler is run. In a production run, they do mutate JIRA. In a test run (when a person is testing the behaviour of the handler by clicking Test on its configuration UI) they create dummy objects.
The instances are now instantiated by an implementation of . The factory shipped with JIRA (as part of JMP) is capable of injecting dependencies into created instances. So we highly recommend switching to a dependency injection strategy for cleaner design and better testability, rather than resorting to the old way of using static calls on the or class. Note also that the class is no longer part of the JIRA API.
The class traditionally used by some handlers has been moved to the JIRA Mail Plugin. The fully qualified names has therefore changed to . Moreover, it has been deprecated.
As we favour composition over inheritance, we encourage plugin developers to directly implement the simple interface and use the methods provided by the JIRA service and manager layer. For example, the newly added .
The same recommendation applies to the , which is a candidate for further changes at any time in the future.
In JIRA 5.0 we simplified the hierarchy of message handling services. Now there is one common super class: .
The above class has 2 descendants:
You should not use or derive from the or classes. We have left these classes in JIRA only to avoid nasty-looking errors in the log while starting up JIRA. An upgrade task in JIRA 5.0 detects all services using this class and changes them to .
Handlers now are treated in the same way regardless of the protocol which was used to fetch the message instance. The files and remain in JIRA only for backward compatibility, allowing administrators to edit built-in mail handlers from the Services page.
You should not modify those files, unless you need to have your handler listed in the Edit Service screen (for FileService and MailFetcherService services).
JIRA 5.0 comes with JavaMail 1.4.4 which also may slightly change the behaviour/capability while parsing messages.
The new plugin module and API do not yet support the following features:
Leaving the static and files and still allowing the user to edit the message service configuration in the old way from the JIRA Services page introduces one inconsistency: Custom mail handlers (plugged using new extension) will not be listed there. We hope to address this inconsistency soon, most probably by removing the capability to edit the mail service configuration and message handler parameters from the Services page. That problem is tracked under JRA-26444.
Message processing services and associated message handlers should generally be configured only from the Incoming Mail administration screen, in the Mail Handlers section.