are there any news on the read only mode and the compatibility library?
Hi @jens,
I am pleased to let you know that the compatibility library is available. To use it in you add-on, you will need to do the following steps:
- Add a new dependency with the
compile
scope to your plugin’s pom.xml
file as follows:
<dependency>
<groupId>com.atlassian.confluence.compat</groupId>
<artifactId>confluence-compat-lib</artifactId>
<version>1.2.1</version>
</dependency>
- Import the following OSGi package if you are using
amps
to build the plugin
<Import-Package>
...
com.atlassian.confluence.api.service.accessmode;resolution:="optional",
...
*;resolution:=optional
</Import-Package>
Please note that you must import it as an optional package with resolution:="optional"
. Otherwise, the plugin won’t work in older Confluence versions.
This library provides you the following classes/services to make your add-on conform with read-only mode:
Using the ReadWriteAccessModeCondition in a web-item or web-panel descriptor
This ReadWriteAccessModeCondition
can be used to make a web-item or web-panel definition visible when the access mode is READ_WRITE
(i.e. Confluence is not in read-only mode). For example:
<web-item key="awesomeWebItem" name="AwesomeWebItem" section="system.content.button" weight="150">
<label key="i18n.label.key"/>
<tooltip key="i18n.tooltip.key"/>
<condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.ReadWriteAccessModeCondition"/>
<condition class="com.atlassian.confluence.plugin.descriptor.web.conditions.PagePermissionCondition">
<param name="permission">view</param>
</condition>
<styleClass>customCssStyle</styleClass>
<param name="iconClass">customIconClass</param>
</web-item>
The example above indicates that the awesomeWebItem
is only visible if the user has the VIEW permission on the page and Confluence is not in read-only mode.
Using the ReadWriteAccessModeUrlReadingCondition in a web-resource descriptor
This ReadWriteAccessModeUrlReadingCondition
can be used to make a web-resource definition available for download
when the access mode is READ_WRITE
(i.e. Confluence is not in read-only mode). For example:
<web-resource key="awesome-resources" name="Awesome Resources">
<condition class="com.atlassian.confluence.plugin.descriptor.web.urlreadingconditions.ReadWriteAccessModeUrlReadingCondition">
</condition>
<resource name="awesome-view.js" type="download" location="awesome-view.js"/>
</web-resource>
The example above indicates that the awesome-resources
is only downloadable if Confluence is not in read-only mode.
Using the AccessModeCompatService
If a plugin needs to check the access mode in its logic, you can declare a Spring bean and inject this AccessModeCompatService
component into a class
(preferably in a Service component, XWork action or REST resource) as follows:
<beans:bean id="accessModeCompatService" class="com.atlassian.confluence.compat.api.service.accessmode.impl.DefaultAccessModeCompatService"/>
Notes:
Another alternative is to use the Atlassian Spring Scanner library to look up this class at compile time and inject it to the caller service with the @ClasspathComponent
annotation.
@Component
public class AwesomeContentService {
final AccessModeCompatService accessModeCompatService;
@Autowired
public AwesomeContentService(final AccessModeCompatService accessModeCompatService) {
// your awesome business logic
}
}
Using the annotations: @ReadOnlyAccessAllowed vs. @ReadOnlyAccessBlocked
@ReadOnlyAccessAllowed
The @ReadOnlyAccessAllowed
annotation is used for bypassing read-only check done when a request is served by an XWork action or a REST resource. You can add the annotation to a method, a class or a package.
For example, an action executed by a sysadmin should be bypassed in read-only mode as follows:
@ReadOnlyAccessAllowed
@WebSudoRequired
public class ReIndexAwesomeContentAction extends ConfluenceActionSupport {
@Override
public String execute() throws Exception {
return SUCCESS;
}
}
WARNING:
This annotation must be used for admin actions only or user usage tracking services, e.g. recently viewed, analytics
@ReadOnlyAccessBlocked
Normally, an action that serves a POST/PUT/DELETE request is blocked in read-only mode by default. However, it can be also blocked while serving a GET request if the action is annotated with @ReadOnlyAccessBlocked
as follows:
@ReadOnlyAccessBlocked
public class ViewAwesomeContentAction extends ConfluenceActionSupport {
@Override
public String execute() throws Exception {
return SUCCESS;
}
}
If you have any difficulties while trying to use it, please feel free to let me know. I am glad to help you out.
Lastly, we are in the process of making this library open source. Please stay tuned!