This document tells you how to convert a plugin that runs in version 4.x of JIRA, so that it will run in version 5.0 of JIRA.
Please refer also to the plugin developer notes for JIRA 5.0, which are updated with each beta release.
The most important changes for plugin developers are:
These changes are detailed in Java API Changes in JIRA 5.0.
In addition to the above changes, a number of concrete/abstract classes have been converted to interfaces.
Because of these changes, it is unlikely that you will be able to create a single artefact (JAR file) that is compatible with both JIRA 5.x and JIRA 4.x.
We recommend that you create a separate branch in your plugin's version control system (VCS) for JIRA 4.x compatibility, and convert "trunk" to JIRA 5.0 compatibility.
Since a number of concrete/abstract classes have been converted to interfaces, you may receive an error similar to the following if you attempt to run your JIRA 4.x-compatible plugin in JIRA 5.0.
1 2java.lang.IncompatibleClassChangeError: Found interface name.of.interface, but class was expected
For example,
1 2java.lang.IncompatibleClassChangeError: Found interface com.atlassian.jira.issue.link.IssueLinkType, but class was expected
If you do receive an error like this, then you need to recompile your plugin against JIRA 5.0 to ensure that your plugin utilises the new interface implementations in JIRA 5.0.
The OSUser changes are likely to be have the biggest effect throughout your plugin.
The "Crowd Embedded" library was introduced in JIRA in 4.3.
At that time the old OSUser API was also maintained as a parallel API that could be used for user management. Existing plugin points (for example, IssueTabPanel
) that had dependencies on OSUser were left alone for binary compatibility with JIRA 4.2.
Because of this, it is possible to do much of your migration from OSUser to Crowd Users while compiling against JIRA 4.3 or 4.4. This allows those with "large" plugins to take a more gradual approach to the migration.
Note: Following all the steps below is primarily recommended for those with a large code base, where a gradual migration is preferred. For many small to medium-sized code bases, it is probably simple enough to just branch and move straight to JIRA 5.0 without the pre-migration on JIRA 4.4.
If you wish to maintain a JIRA 4.2 or lower compatible branch:
import com.opensymphony.user.User;
with import com.atlassian.crowd.embedded.api.User;
If you only wish to maintain a JIRA 4.3 or higher compatible branch:
import com.opensymphony.user.User;
with import com.atlassian.crowd.embedded.api.User;
In JIRA 5.0 we have separated the Java API away from the internal implementation in order to help maintain a predictable compatibility policy. See Java API Policy for JIRA.
You can change your dependency to "jira-api" instead of "jira-core"/"atlassian-jira" to ensure you only use API classes.
Rate this page: