Preparing for Confluence 5.9
This documentation is intended for Confluence developers who want to ensure that their existing plugins and add-ons are compatible with Confluence 5.9, and to learn about the new features for developing add-ons in Confluence 5.9.
Please watch the Development Releases page for pre-release versions of Confluence 5.9 that you can use for testing purposes. This page will be updated as further EAP development releases are available.
What's changing in Confluence 5.9?
Permission requirement changes
We've made some minor changes to the permissions required to perform certain actions in Confluence:
- Plugins need view permission to create, edit, and delete content – Previously, the space view permission wasn't required for actions on content (page, blog post, comment, attachment).
Getting ready for Plugins 4 and SOY update
As part of upgrading Confluence to Atlassian Platform 3 we've been working hard updating some of the libraries in Confluence Core. Most notably Atlassian Plugins version 4 (but also Atlassian REST 3, Applinks 5, Trusted Apps 4 and SAL 3).
We've also upgraded Soy to 3.x in Confluence. There are implications in these changes that you should be aware of.
Changes and implications so far
|JDK8 as a minimum runtime and compile requirement||Confluence 5.9.x will neither run nor compile on JDK less than 8.|
|Confluence no longer supports Tomcat 6||Confluence 5.9.x will not run on Tomcat 6 and below. You'll need to specify tomcat7x <containerId> in Amps Configuration.|
|Servlet API upgrade (3.0.1)||Confluence 5.9.x will not run on servlets less than 3.
May affect add-ons that import servlet api classes where a version range is not explicitly set
|Plugins framework (4.0.5)||The way confluence transforms and loads plugins. API separate from core. Plugin lifecycle changes.|
|Atlassian Template Renderer (2.0)||Does not support velocity 1.5 anymore. 1.6 only. Switched defaults for @HtmlSafe|
|Spring upgrade to 4.1.x (In Plugins Framework)||Plugins can use Spring 4.1.6
Affected are add-ons that use Spring classes where a version range is not explicitly set.
Addons which use @Deprecated code from the spring <=4 are affected.
||Add-ons that bundle the org.osgi.core library|
|SAL upgrade (3.0.2)||Add-ons that look up a login URL.|
|Atlassian Trusted Apps (4.1.0)||
There's a possibility of breaking changes for plugins that were using older versions of trustedapps
Soy Renderer upgrade from 2.x to 3.x
|Add-ons using soy as template renderer|
|REST 3.0 upgrade||With version 3.0.0 of atlassian-rest XSRF protection is enabled by default. Opt-out is default instead of opt-in.
Some resources might suddenly start requiring XSRF checks even if they
|Amps 6.0.8||There's a new version of AMPS in use, which requires Maven 3.2|
|SpringDM replaced by Eclipse Gemini||Add-ons that use
|bndlib changes||See details below|
The changes in detail
Below are details of each change and how to handle them if you have issues running your plugin with the Plugins 4 branch, or find any existing issues with the Soy Upgrade.
We may add more detail to this page in future. Please check back regularly to ensure you have the latest information.
Confluence includes version 4.0.5 of Atlassian Plugins framework.
Detailed upgrade guide can be found here: https://ecosystem.atlassian.net/wiki/display/PLUG/Atlassian+Plugins+4.0+Upgrade+Guide
Confluence will include a new version of the Atlassian Plugins Framework, which includes an upgrade of Spring from version 2 to 4.1.x. If your add-on uses Spring classes, we recommend using imports of the form
org.osgi.core library incompatibility
Confluence 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 Confluence instead of bundling it (see LinkageError).
Servlet API upgrade
Confluence will run on a newer version of the Servlet API, version 3.0.1. As with the Spring upgrade described above, the recommended OSGi import is of the form
Many Confluence artifacts do NOT pull servlets-api as their transitive dependency now.
If you're developing something which implements Servlet-API, please, make sure to use a provided-scoped dependency on a
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 Confluence. This library has been deprecated for a while, and won't work with Confluence.
To fix this, you'll 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'll also need to remove references to the old
Atlassian Shared Access Layer (SAL) will be upgraded in Confluence. 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 won't load in Confluence. 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).
Soy plugin has been upgraded from version 2.x to 3.x. Existing plugin incompatibilities have already been fixed and released.
This bump in version includes the removal of some legacy APIs as well as a stricter compiler of soy templates. The compiler is stricter than the old compiler so some templates which were previously allowed may start to have compilation errors. It's possible to write templates which are compatible with both versions. Below are some of the common errors which may occur as part of the upgrade and how to fix them.
Missing required param
This is due to the strictness change in the soy compiler. the parameter on the sub template is defined as required but you are not providing it to the call. You must either mark the parameter on the sub template as optional or pass in a value for the parameter.
ClassCastException: java.lang.Long cannot be cast to java.lang.Integer
This is due to a change in the soy compiler where it represents numbers as longs where it previously represented them as integers. This exception is most likely coming from a custom soy function you've written. Cast to a Number instead and call .intValue() or .longValue().
This is due to the deprecation of user instantiated SanitizedHtml object, which is used to tell soy to not sanitise the given content.
REST Upgrade 3.0
With version 3.0.0 of atlassian-rest XSRF protection is enabled by default. It's possible to opt-out of XSRF protection for a rest method by using the com.atlassian.annotations.security.XsrfProtectionExcluded annotation as provided Atlassian annotations (versions >= 0.9 – but please use a version >= 0.12). There should not be many situations where the XsrfProtectionExcluded annotation will be needed. Here's an example of using the XsrfProtectionExcluded annotation.
SpringDM replaced by Eclipse Gemini
Confluence 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).
Confluence 5.9.x 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 can be more restrictive about what instructions are valid. For many plugins, the tool calculates correct imports automatically, and yours should specify an
<instructions> element in your pom with
If this doesn't work, either due to issues with tools as detailed above, or because of other specific requirements imposed by some libraries or reflective code, adding additional instructions should follow these guidelines:
- Always put wildcard imports (such as
javax.servlet.*) after non-wildcard imports (such as
- Put more specific wildcards (such as
javax.servlet.*) before less specific wildcards (such as
Don't put instructions in both the pom and
atlassian-plugin.xml. Using the pom is preferred, if you have instructions in
atlassian-plugin.xml for legacy reasons. Don't put additional instructions in the pom, but rather move all instructions to the pom.
How can you be prepared?
- Test your plugins against latest available public version of confluence (Currently 5.8.9) as well as against our 5.9 EAP release. You should be aware that there may be a situation where you'll need to maintain two versions of your plugin: one for pre 5.9.x, and one for post 5.9.x versions of Confluence because of breaking changes.
Please make sure to specify proper ranges for supported Confluence versions.
For easier migration to a Confluence 5.9.x-compatible set of dependencies, please, import our
This should provide your project a set of dependency-management fully compatible with the corresponding version of Confluence.
- Tomcat7 is the minimum version of Tomcat required to run Confluence 5.9.x. This also means that the minimum Servlets version is 3.0.1.
- Confluence 5.9.x requires running on JDK8 (won't run on JDK7 and below).
- We strongly advise that you make your plugins transformless.
Take a look at the following repository if you need more information about making this change: https://bitbucket.org/atlassian/atlassian-spring-scanner/overview
If you encounter any issues, create an issue so we can look into it.
The globals listed below will be replaced with one or more individual AMD modules.
Status updates removal
From Confluence 5.9, we're removing the Status Updates feature. This includes the ability to:
- Update your status
- See other people's status' via their profile or the User Status List macro.
This will impact your add-on if it interacts with the User Status List macro.
Changes to the dashboard
In this release we've made some big changes to the dashboard, including adding a great new sidebar. Plugins that insert items into the dashboard may find that the location of their items has changed.
atl.dashboard.left, which previously appeared on the left side of the dashboard below the site welcome message, is deprecated. Plugins should use
system.dashboard.button, where the Create space and Invite user buttons appear, is still positioned at the top right of the dashboard but buttons are now rendered without icons and collapse into an ellipsis menu.