Extension Maven Plugin

Last modified by Thomas Mortagne on 2023/03/02 11:02

Various extension-oriented mojos for Maven builds.

WAR Mojo

Generate a complete extension descriptor (.xed file) for all the jars packaged in a WAR (next to each one) as well as for the WAR itself (in /META-INF/).

To execute it:

      <plugin>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-extension-plugin</artifactId>
       <executions>
         <execution>
           <goals>
             <goal>war</goal>
           </goals>
         </execution>
       </executions>
     </plugin>

Register Mojo

Generate complete extension descriptor (.xed file) for the current artifact in /META-INF/.

      <plugin>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-extension-plugin</artifactId>
       <executions>
         <execution>
           <goals>
             <goal>register</goal>
           </goals>
         </execution>
       </executions>
     </plugin>

XIP Mojo and extension

Generate a xip package (a zip file containing extensions formatted like the local extensions repository) containing the dependencies of the current project by default. It's mostly used in conjunction with xip extensions as a packaging tool.

To use it:

      <packaging>xip</packaging>

If you don't use the right parent you might also need to register the xip packaging in your pom:

  <build>
   <extensions>
     <!-- Needed to add support for the "xip" packaging -->
     <extension>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-extension-plugin</artifactId>
       <version>${commons.version}</version>
     </extension>
   </extensions>
 </build>

Don't hesitate to use the coreExtensions option to indicate a set of dependencies you don't want to include in your XIP (because they are expected to always be there in the target XWiki version).

Example

For example if you want to package a XIP package for an already released extension (in this example org.xwiki.contrib.mediawiki:mediawiki-xml) you would generally create in an empty folder a pom.xml file similar to the following:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <parent>
   <groupId>org.xwiki.platform</groupId>
   <artifactId>xwiki-platform-distribution</artifactId>
   <!-- The version of XWiki where the extension is planned to be installed -->
   <version>14.5</version>
 </parent>
 <groupId>groupid</groupId>
 <artifactId>package</artifactId>
 <packaging>xip</packaging>
 <properties>
   <!-- It's expected for some enforcer rules to fail with a dependency that was not designed to be built with this version of XWiki -->
   <xwiki.enforcer.skip>true</xwiki.enforcer.skip>
 </properties>
 <dependencies>
   <!-- The extension to package along with its dependencies-->
   <dependency>
     <groupId>org.xwiki.contrib.mediawiki</groupId>
     <artifactId>mediawiki-xml</artifactId>
     <version>1.13.5</version>
   </dependency>
 </dependencies>
 <build>
   <pluginManagement>
     <plugins>
       <plugin>
         <groupId>org.xwiki.commons</groupId>
         <artifactId>xwiki-commons-tool-extension-plugin</artifactId>
         <version>${commons.version}</version>
         <configuration>
           <coreExtensions>
             <!-- We exclude what is already in the WAR -->
             <coreExtension>
               <groupId>org.xwiki.platform</groupId>
               <artifactId>xwiki-platform-distribution-war-dependencies</artifactId>
               <version>${platform.version}</version>
               <type>pom</type>
             </coreExtension>
           </coreExtensions>
         </configuration>
       </plugin>
     </plugins>
   </pluginManagement>
 </build>
</project>

You will generally use exactly the same pom with two differences:

  • the version of XWiki in which you plan to install your extension (in <parent>)
  • the <dependencies> you want to include in your XIP package (and you might need to add <type>xar</type> if that extension is of type XAR)

and execute

  mvn package

Dependency tree Mojo

To resolve and print a dependency tree according to Extension Manager specification you can use the dependency-tree Mojo.

It's generally used directly on the command line and than configured in a pom. The Mojo has been introduced in XWiki 15.2 but it can be used anywhere if you indicate explicitly the version of the Maven plugin in the command line.

The following example use the 15.2-SNAPSHOT version of the plugin to resolve the dependency tree of the current module for the target XWiki Standard WAR in version 14.10.5.

  mvn org.xwiki.commons:xwiki-commons-tool-extension-plugin:15.2-SNAPSHOT:dependency-tree -DcoreExtensions=org.xwiki.platform:xwiki-platform-distribution-war-dependencies:14.10.5

It's recommended to always indicate a target WAR and its version to get more accurate results and much faster resolutions (it can take take a very long time for a big dependency tree if the core extension have to be resolved too).

Common parameters

All the Mojos above share a list of parameters. Some of them are described here.

coreExtensions

It's possible to resiter extensions (and either Maven dependencies) as core extensions so that they are taken into account when resolving extensions.

  <build>
   <pluginManagement>
     <plugins>
       <plugin>
         <groupId>org.xwiki.commons</groupId>
         <artifactId>xwiki-commons-tool-extension-plugin</artifactId>
         <version>${commons.version}</version>
         <configuration>
           <coreExtensions>
             <!-- What constitutes the XWiki Standard WAR -->
             <coreExtension>
               <groupId>org.xwiki.platform</groupId>
               <artifactId>xwiki-platform-distribution-war-dependencies</artifactId>
               <version>${platform.version}</version>
               <type>pom</type>
             </coreExtension>
           </coreExtensions>
         </configuration>
       </plugin>
     </plugins>
   </pluginManagement>
 </build>

disabledComponents

Since XWiki 12.2.

This parameter allows to specify a list of components to unregister from the component manager.
Example of an usage:

<configuration>
 <disabledComponents>
   <disabledComponent>
     <type>com.xpn.xwiki.doc.MandatoryDocumentInitializer</type>
     <role>XWiki.XWikiServerXwiki</role>
   </disabledComponent>
 </disabledComponents>
</configuration>

Note that if the role is not filled or given, the default hint will be used.

Get Connected