JIRA 7.0 - Platform changes
This page covers the platform changes for JIRA 7.0. These include upgrades to bundled components, like the plugin framework, SAL, etc.
The changes are part of a larger set of developer changes to JIRA for 7.0. You should also read Preparing for JIRA 7.0 for an overview of the release, as well as JIRA 7.0 - Platform changes and JIRA 7.0 - General changes.
The risk level indicates the level of certainty we have that things will break if you are in the "Affected" column and you don't make the necessary changes.
|Spring upgrade||7.0||HIGH||Add-ons that use Spring classes where a version range is not explicitly set|
||7.0||HIGH||Add-ons that bundle the org.osgi.core library|
|Servlet API upgrade||7.0||HIGH||Add-ons that import servlet api classes where a version range is not explicitly set|
||7.0||HIGH||Add-ons that bundle the plugin-license-storage-lib library|
|SAL upgrade||7.0||MEDIUM||Add-ons that look up a login URL|
|7.0||MEDIUM||Any add-on that uses guava functionality|
|7.0||MEDIUM||Add-ons using soy as template renderer|
|SpringDM replaced by Eclipse Gemini||7.0||LOW||Add-ons that use
|bndlib changes||7.0||LOW||See details below|
JIRA 7.0 will include a new version of the Atlassian Plugins Framework, which includes an upgrade of Spring from version 2 to 3. In this upgrade, if your add-on uses Spring classes and you have not explicitly set a version range, your add-on will not load. This is because BND, a tool that generates manifests for OSGi bundles at compile time, will generate an import statement for Spring with the version range "[2.5,3)" (this reads as "greater than or equal to 2.5, but less than 3"). Your add-on will try to find the relevant Spring packages, but will limit its search to that range (i.e. versions less than 3). The package that is supplied is now version 3, so the search will fail.
To fix this, you must explicitly add a version range. We suggest "2.5," which reads as "greater than or equal to 2.5," removing the upper bound of 3. The complete import statement will look something like this:
If you know the exact packages that are required by your add-on, you should list them out explicitly rather than relying on a wildcard expression.
org.osgi.core library incompatibility
JIRA 7.0 will include a new version of the Atlassian Plugins Framework, which will not work when classes from
org.osgi.core are redefined. Classes in
org.osgi.core are redefined when an add-on bundles the
org.osgi.core library. This will cause a version mismatch and class-loading issues. To fix this, your add-on will need to import the
org.osgi.core library from JIRA instead of bundling it (see LinkageError).
Servlet API upgrade
JIRA 7.0 will expose a newer version of the Servlet API, version 3.0. As with the Spring upgrade described above, the add-on manifest may prevent the loading of the servlet API with version 3.0.
To fix this, you must explicitly add a version range. We suggest "2.5," which reads as "greater than or equal to 2.5," removing the upper bound of 3.0. The complete import statement will look something like this:
plugin-license-storage-lib library no longer supported
If your add-on bundles the
plugin-license-storage-lib library from the Universal Plugin Manager (UPM), your add-on will not work with JIRA 7.0. This library has been deprecated for a while, and won't work with JIRA 7.0.
To fix this, you will need to use UPM's
licensing-api module instead. Follow the instructions in this tutorial: Tutorial: Adding licensing support to your add-on to do this. Note, use the versions provided by the application for the import packages; don't specify a version range for the import packages.
You will also need to remove references to the old
Atlassian Shared Access Layer (SAL) will be upgraded in JIRA 7.0. The API changes are:
com.atlassian.sal.api.auth.LoginUriProviderhas had methods removed and a replacement added.
com.atlassian.sal.api.page.PageCapabilitieshas been removed.
com.atlassian.sal.api.page.PageCapabilityhas been removed.
The OSGi version will also be increased to 3.0. If your add-on has declared a maximum version of less than 3.0 in its manifest file, it will not load in JIRA 7.0. To fix this, we recommend that you remove the upper limit for SAL (this will also help your add-on to avoid this type of problem in future).
Guava library upgrade
Guava will be upgraded 18.0 in JIRA 7.0. Guava is a utility library, provided by Google, that allows for operations on collections, etc. If your add-on depends on functionality that is provided by Guava, then you may need to make changes to your add-on.
Soy Renderer upgrade from 2.x to 4.1.2
The Atlassian Soy Template Renderer has been upgraded to version 4.1.2. This is a major upgrade of the soy compiler with many useful features including:
- Strict autoescaping mode — This security feature helps avoid accidental double-escaping. It does this by identifying fragments which are already safe, so they are not escaped again. This means that you should be able to remove most
noAutoescapedeclarations in your templates.
- Strongly-typed template parameters — Writing types for your soy template parameters is not mandatory, but you can now do so, if you want to.
- Exception backtraces now include template calls — Enough said, better exceptions are always a win!
- Support for custom data converters in Tofu — You won't be using this feature yet, although Atlassian Soy currently uses it internally.
Other changes in this version of the Soy Template Renderer:
- Soy template compilation is now stricter, with regards to templates passing in required parameters to sub-templates. If you don't need a required parameter, just mark it as optional.
- The internal Soy compiler is no longer exposed through OSGi. Atlassian Soy has its own APIs, which you should be using and is there to shield consumers from changes to the underlying compiler. From now on, you'll need to use these public APIs instead.
toStringfunction, which helps to bridge the gap in breaking changes to 3.x. This function calls
toStringon the object passed in as a parameter. In 3.x, POJOs no longer call
toStringwhen printing the object, and show a JSON string representation instead.
helpUrlfunction, which lets you to retrieve the helpUrl for a given key. This works on both client and server and is CDN friendly. It is currently backed by the SAL API.
- Soy caches no longer expire and the Closure Templates compiler now uses stackless exceptions for flow control. Both of these changes should improve performance.
The API has been split in this release. Previously, the
soy-template-renderer-apiartifact depended on the plugin framework and web resources, even though it could be consumed from a non-plugin framework environment. All parts of the API which are only related to the Atlassian plugin deployment have now been moved to the
soy-template-renderer-plugin-apiartifact. No classes have been deleted in the process so the API remains binary compatible. You may run into a problem when the product upgrades to 3.3.0 — some consumers may need to add the following additional dependency to function correctly:
|Error / Error message||Action / Explanation|
|"template aui.toolbar.splitButton: Call to 'aui.toolbar.dropdownInternal' is missing required param 'text'."||Upgrade to AUI 5.6.11.|
|"template jiraIntegration.templates.fields.stringField: Call to 'aui.form.textField' is missing required param 'id'"||Upgrade to JIRA Integration Plugin 1.5.9.|
|"<SOME TEMPLATE>: Call to '<SOME SUB TEMPLATE>' is missing required param '<SOME PARAM>'."||You are hitting the strictness changes in the soy compiler.
Check your template for the problem.
|"java.lang.ClassCastException: java.lang.Long cannot be cast to java.lang.Integer from a custom soy function"||Your custom function shouldn't be assuming a specific type of number.
Cast to Number and call the appropriate method to get an int or long.
|Enums are no longer comparing with strings||
Bug in 3.0.0 release, fixed in 3.0.3.
|"java.lang.IllegalAccessException: Class com.atlassian.soy.impl.data.AccessorSoyValueProvider can not access a member"||Bug in 3.0.0 release, fixed in 3.0.3.|
Printing a Java object in a template no longer calls the
|The JSON representation of the object will be output.|
SpringDM replaced by Eclipse Gemini
JIRA 7.0 will include a new version of the Atlassian Plugins Framework, which uses Eclipse Gemini rather than SpringDM to perform dependency injection over OSGi. This should be mostly transparent to add-ons, however plugins which use
org.springframework.osgi.context.BundleContextAware to inject the
org.osgi.framework.BundleContext should instead use
org.eclipse.gemini.blueprint.context.BundleContextAware. The two classes are API-identical, so the only required changes should be updating the import in the Java source and your OSGi
Import-Package (if manually managed).
JIRA 7.0 will include a new version of the Atlassian Plugins Framework, which uses a newer version of
bndlib for automatic manifest generation (primarily to support JDK 8). This new version of bndlib will now add tildes to the end of any duplicate packages it finds — you will notice messages like this at startup:
"missing requirement [112.0] osgi.wiring.package; (&(osgi.wiring.package=org.codehaus.jackson.annotate~)". The safest way to resolve this is to make your plugin a transformerless plugin, however you can also carefully audit your imports to fix it. See this issue for details: PLUG-1131.