Plugin Repository Metadata

Obsolete This content is no longer current. You can find up to date information here.

This information is for the extra meta data needed outside of the maven structure to enable a filtering servlet to serve up repository information (download counts, multiple categorisation of plugins, version compatability information) leaving maven to deal with the actual repository management / downloading.

The following metadata would be used:

Repository Configuration

There is one of these per repository, the confluence plugin interface is pointed at this file. An example of how it might look is:

<atlassian-repository>
  <product-versions>
    <confluence version="1.0" build="68" />
    <confluence version="1.3-RC1" build="123" />
    <confluence version="1.3-RC2" build="127" />
    <confluence version="1.3" build="155" />
    <!-- this is to be updated with each release -->
  </product-versions>
  <categories>
    <category key="themes">
      <description>xhtml description</description>
    </category>
    <category key="macros">
      <description>xhtml description of this parent category</description>
      <category key="content-macros">
        <description>xhtml description</description>
      </category>
      <category key="formatting-macros">
        <description>xhtml description</description>
      </category>
    </category>
    <category key="license-type">
      <description>xhtml description</description>
      <category key="commerical">
        <description>xhtml description</description>
      </category>
      <category key="freeware">
        <description>xhtml description</description>
      </category>
      <category key="opensource">
        <description>xhtml description</description>
      </category>
    </category>
  </categories>
  <servers>
    <url>http://confluence.atlassian.com/plugin-repository/confluence.action</url>
    <!-- multiple possible for fall back (try in order of entry) -->
  </servers>
</atlassian-repository>

Plugin Configuration

There is one of these for each plugin in the repository.

<atlassian-plugin key="my.plugin.key">
  <product>confluence</product>
  <vendor><!-- current vendor information from atlassian-plugin.xml in the dist - including url, name etc --></vendor>
  <categories>
    <category key="themes" />
    <category key="commerical" />
    <category key="formatting-macros" />
  </categories>
  <description>
    Description of what this plugin does (non version specific) using xhtml.
  </description>
  <plugin-version name="1.0" build="123" date="27-01-2006">
    <product-versions>
      <confluence build="68" working="true" />
      <confluence build="123" working="false" />
      <!-- 127 ommited, means "unknown" functional state -->
      <confluence build="155" working="true" />
    </product-versions>
    <binary>http://path.to/binary.jar</binary>
    <source>http://path.to/source.zip</source>
    <javadoc>http://path.to/docs/javadoc/</javadoc>
    <docs>http://path.to/docs/</dosc>
    <downloads>1</downloads>
    <dependancies>
      <atlassian-plugin key="dependant.plugin.key" />
      <jar>http://path.to/library.jar</jar>
    <dependancies>
    <release-notes>
      <!-- what I changed in this release, new features added etc. -->
    </release-notes>
  </plugin-version>
</atlassian-plugin>

The required elements are as follows (everything else is optional):

• /atlassian-plugin/product (at least one)
• /atlassian-plugin/plugin-version (at least one)
• /atlassian-plugin/plugin-version/binary (only one per plugin-version)

The downloads counter will be incremented by the filtering webapp (defined below) - which may cause a significant amount of file revisions should this file be version controlled.

For the dependancies:

If it is an atlassian-plugin, the dependant will be installed first (unless this is a cycling dependancy - at which point the last in the chain will be installed first) to the location specified in the deploy-to element of the latest plugin version compatable with the client Confluence version. Should no suitable dependant plugin be found then in the repository then the depending plugin will not be installable.

If it is a jar, the jar should be bundled inside of the plugin jar. The classloader for the plugin manager in confluence will have to be changed to look in the following order (using similar dependancy information duplicated in the atlassian-plugin.xml):

1. The plugin jar file directly
2. Any 'jar' resources declared in atlassian-plugin.xml (bundled in the plugin's jar)
3. Any other plugins declared as dependencies in atlassian-plugin.xml (by accessing that plugin's classloader)
4. The default Confluence classloader (WEB-INF/lib/* + WEB-INF/classes)

This will resolve the problem of the two plugins using two different versions of the same library.

Information below here might be superseeded by other pages in this branch

Other problems

All plugins should be made uploadable, David and I have come to the following conclusion of what stops a plugin being uploaded:

1. Component plugins - when uninstalling a component plugin, spring seems not to forget properly so when it goes to access it again the classes appear to have disappeared from underneath it. Also causes problems with upgrading a component plugin as it appears when the plugin tries to register the component again it fails.
2. Plugin class dependencies (eg Utilities) - resolved by the depenancy information above
3. Plugins that use Bandana (XStream) - the classes aren't available when the configuration file is taken from xml > Java, Bandana/XStream will need to be modified to hunt through the plugin classloaders.

A framework where plugins could be "stopped" would be very useful - so when a dependancy is uninstalled all it's dependants are stopped. When starting a plugin it should check its dependancies are started before allowing the depending library to start. Should someone try to reinstall a plugin with a component that has been registered before but the classes are no longer in confluence (eg: upgrading utilities) then confluence should have the component in a deactivated state where it will not start until the server is restarted.

This deactivated state would not be nessessary if a way could be found for confluence to uninstall component plugins fully.

Filtering Webapp

The filtering webapp should access the SVN repository and load all the xml files. It should cache the results and access the repository on client access if it's data is older than the cache timeout threshold. SVN hooks to have the webapp's cache cleared on svn update of the repository directory would also be worth considering.

The webapp exists in the url's mentioned in the <servers ... /> element of the repository.xml configuration file, and is accessed through url?build=123 where 123 is the client's confluence version. Returned is a list of the compatable plugin's and their compatable plugin-version's, with non-functional and unknown versions excluded. If a build number is ommited then all plugins are returned. If the showUnknown=true variable is received then the server should return unknown versions as well as the working ones.