Extra XAR entry types

Last modified by Anca Luca on 2024/01/24 11:08

tagAdds extra XAR entry types defining specific installation and upgrade behaviors.
TypeJAR
Category
Developed by

Clément Aubin

Active Installs5
Rating
1 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

Description

Adds extra XAR entry types defining specific installation and upgrade behaviors.

Context

When writing XAR-based extensions, extension developers have the possibility to define specific rules towards the handling of specific XWiki documents : define if a document can be editable, deletable, and how XWiki should act when upgrading the document to a new version of the XAR extension providing it.

These rules are applied by defining a type attribute to specific documents of the XAR provided by the extension, in the file package.xml of this XAR. More information about the type attribute can be found on the XAR Module Specifications page.

In practice, these type attributes are defined within the Maven definition of the extension, using the configuration of the Maven XAR plugin.

Possible XAR entry types

A XAR entry type is defined around 3 concepts :

  • How the page on the wiki is protected when it's installed from that xar:
    • Whether or not it is possible to edit the page on the wiki
    • Whether or not it is possible to delete the page on the wiki
  • The behaviour of the page upon upgrade of the extension (or install of another one): the upgrade type of the entry, as defined here.

In order to allow extension developers to use any combination from these 3 concepts, this extension defines and exposes every combination of these 3 concepts as XAR entry types. 

The name of an entry types defined by this extension matches the following pattern : <editable>-<deletable>-<upgradeType>.

  • <editable> can be either edit or noedit if edit is allowed or not
  • <deletable> can be either delete or nodelete if delete is allowed or not
  • <upgradeType> is the lowercased version of the values of the UpgradeType enum. For example :

Examples

  • An entry that should not be editable, not deletable, and should be always upgraded during upgrades, discarding any merge conflicts will have the entry type noedit-nodelete-overwrite.
  • An entry that should not be editable, not deletable, and should be skipped during upgrades will have the entry type noedit-nodelete-skip
  • An entry that should be editable, should not be deletable, and should be overwritten during upgrades will have the entry type edit-nodelete-overwrite

Using this extension

In order to use this extension, simply add it as a dependency to your project :

    <dependency>
     <groupId>org.xwiki.contrib</groupId>
     <artifactId>api-extra-xar-entry-types</artifactId>
     <version>${extraXarEntryTypes.version}</version>
   </dependency>

Upon installation, the extension will detect that it has just been installed, and will register the custom XAR entry types.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Release Notes

v1.0

First release

Dependencies

Dependencies for this extension (org.xwiki.contrib:api-extra-xar-entry-types 1.0):

Tags:
    

Get Connected