Confluence Conveyor Library - Atlassian Plugins

This library allows plugins to 'convey' users to another location when they access built-in actions.

Details

Name	Confluence Conveyor
Current Version	0.5.0
JavaDoc API

Maven 2

Dependency XML

<dependency>
  <groupId>org.randombits.confluence<groupId>
  <artifactId>confluence-conveyor</artifactId>
  <version>0.5.0</version>
</dependency>

Repository XML

<repository>
  <id>atlassian-m2-contrib</id>
  <name>Atlassian Maven 2 Contributor Repository</name>
  <url>https://maven.atlassian.com/contrib</url>
  <snapshots>
    <enabled>false</enabled>
  </snapshots>
</repository>

Instructions

Overriding the built-in XWork actions is a bit tricky. There are methods for overriding actions by defining them in the atlassian-plugin.xml file. However, you will find that random plugin installations, JDK upgrades or Confluence versions will disable your overrides.

The solution was to build a library which lets you explicitly override actions in a reliable manner. We use it in the Scaffolding Plugin. The best thing is probably to look at that plugin's source code and emulate it. Essentially, there are three steps:

1. Add the 'confluence-conveyor' library as a dependency in your project's pom.xml file.

<dependency>
    <groupId>org.randombits.confluence</groupId>
    <artifactId>confluence-conveyor</artifactId>
    <version>0.5.0</version>
</dependency>

You will also need the 'contributors' maven 2 repository in your repository list:

<repository>
    <id>atlassian-m2-contrib</id>
    <name>Atlassian Maven 2 Contributor Repository</name>
    <url>https://maven.atlassian.com/contrib</url>
    <snapshots>
        <enabled>false</enabled>
    </snapshots>
</repository>

2. Add the ConveyorListener to your atlassian-plugin.xml file. This kicks off the code which lets you override the existing action.

<listener name='Action Conveyor' class='org.randombits.confluence.conveyor.ConveyorListener' key='actionConveyor'>
    <description>Sets up the action conveyor for this plugin.</description>
</listener>

3. Add a 'conveyor-config.xml' file to the root of your plugin resources - the same location as 'atlassian-plugin.xml' is located. This is where you specify what actions you want to override. You can also specify new actions and packages if you wish - I prefer to have all my XWork definitions in one place, so I put them all in 'conveyor-config.xml'. However, you can leave the non-override actions in atlassian-plugin.xml if you wish - both options work fine.

The main difference between conveyor-config.xml and standard XWork is that there are new elements which let you explicitly override an existing package and/or action. This is helpful because it means you won't accidentally override an existing action, it has to be explicit. Also, when overriding, you can choose to only override specific sections, or action responses, which means it is less likely to break with future versions of Confluence where new actions have been added, new responses changed, or even different action classes used.

Here is a simple example of 'conveyor-config.xml':

<?xml version="1.0"?>

<conveyor-config>
    <package-override name="pages" namespace="/pages">
        <!-- Overrides the standard 'editpage' action completely -->
        <action-override name="editpage" class="foo.bar.MyEditAction" method="doDefault">
            <interceptor-ref name="defaultStack"/>
            <result name="success" type="velocity">/templates/myplugin/editpage.vm</result>
            <result name="error" type="velocity">/templates/myplugin/error.vm</result>
        </action-override>

        <!-- Overrides the 'docreatepage' action, only replacing the 'cancel' result -->
        <action-override name="docreatepage" inherit="true">
             <result name="cancel" type="redirect">/alternate/cancel/location.action</result>
        </action-override>

        <!-- Adds a new action to the /pages namespace -->
        <action name="newaction" class="foo.bar.NewAction">
             <result name="success" type="velocity">/templates/myplugin/new.vm</result>
        </action>    

    </package-override>

    <!-- Adds a whole new package to confluence, as you would in atlassian-plugin.xml -->
    <package name="myPackage" extends="default" namespace="/plugins/myplugin">
        <default-interceptor-ref name="defaultStack"/>

        <action name="myaction" class="foo.bar.MyAction">
            <result name="success" type="velocity">/templates/myplugin/myaction.vm</result>
        </action>    
    </package>
</conveyor-config>

There are two new elements above:

a) <package-override> - explicitly overrides an existing package. Any existing actions from that package will continue to work as per-usual, unless explicitly overridden with the <action-override> element.
b) <action-override> - explicitly overrides an existing action. If you wish to keep most of the original action definition, but override specific results or other values, specify 'inherit=true' (see the 'docreatepage' example above). Otherwise, the new definition will completely replace the existing one.

As indicated by the example, you can add new <action> elements into either <package-override> or <package> definitions. The library will not let you accidentally override an existing package or action without using <package-override> or <action-override> explicitly.

Also, be aware that currently there is no good way to manage the situation where two separate plugins try to override the same action. The library will check for an existing override and bail with an error in the log file, but so far I haven't come up with a good way to determine who 'wins'. It will probably require an administration screen which allows admins to choose. But for the moment, it's whichever plugin Confluence decides to load first which wins.