Maven XAR Plugin

Last modified by Vincent Massol on 2021/04/09 18:01

This build tool allows creating XAR files, expanding XAR files, reformatting them and verifying some best practices.

XAR Mojo

To configure it:

  • Register a new Maven Lifecycle in your POM:
    ...
    <build>
      <extensions>
        <extension>
          <groupId>org.xwiki.commons</groupId>
          <artifactId>xwiki-commons-tool-xar-handlers</artifactId>
          <version>...version here...</version>
        </extension>
      </extensions>
    ...
  • Create a Maven POM file with the xar packaging: <packaging>xar</packaging>
  • Put the wiki pages as XML files in src/main/resources by having directories matching space names. For example:

    structure.png

To use it:

  • mvn xar:xar will generate the XAR file

Transformations

It is also possible to perform transformations on the XML files. For example:

Insert a text value

This can work well, for example, to change skin definitions. E.g.:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <transformations>
     <transformation>
       <file>Blog/WebHome.xml</file>
       <xpath>/xwikidoc/object/property/itemsPerPage</xpath>
       <value>100</value>
     </transformation>
     <transformation>
       <artifact>org.xwiki.platform:xwiki-platform-administration-ui</artifact>
       <file>XWiki/XWikiPreferences.xml</file>
       <xpath>/xwikidoc/object/property/colorTheme</xpath>
       <value>ColorThemes.Mint</value>
     </transformation>
   </transformations>
 </configuration>
</plugin>

Manipulate XML elements

Since 9.5RC1 it is possible to remove/replace/insert a complete XML element. Here is an example:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <transformations>
     <!-- Insert the content of file src/xar/transformations/ckeditor.xml
           as child of xwikidoc element in XWiki/XWikiPreferences.xml -->

     <transformation>
       <artifact>org.xwiki.platform:xwiki-platform-distribution-ui-base</artifact>
       <file>XWiki/XWikiPreferences.xml</file>
       <xpath>xwikidoc</xpath>
       <action>INSERT_CHILD</action>
       <xml>src/xar/transformations/ckeditor.xml</xml>
     </transformation>
     <!-- Remove first attachments from XWiki/XWikiPreferences.xml -->
     <transformation>
       <artifact>org.xwiki.platform:xwiki-platform-distribution-ui-base</artifact>
       <xpath>xwikidoc/attachment</xpath>
       <action>REMOVE</action>
     </transformation>
   </transformations>
 </configuration>
</plugin>

Insert Text Content of a File

Since 11.4RC1 it is possible to insert the text of another project file. This works well to insert complex JavaScript, Velocity or CSS files. These files, if they are not named .xml  stay within the same directory and will be ignored unless they are inserted and can thus be edited with an integrated development environment (which brings syntax coloring, auto-completion, reformatting, or validation). Here is an example:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <transformations>
     <transformation>
         <!-- Insert the content of file src/main/resources/MyApp/config.js
               as the value of the property code in the first object of class
               XWiki.JavaScriptExtension of the XML file MyApp/Config.xml -->

       <action>INSERT_TEXT</action>
       <file>MyApp/Config.xml</file>
       <xpath>/xwikidoc/object[className[text()='XWiki.JavaScriptExtension']]/property/code</xpath>
       <content>src/main/resources/MyApp/config.js</content>
    </transformation>
   </transformations>
 </configuration>
</plugin>

Insert an Attachment

Since 11.4RC1 it is possible to insert the content of another project file as an attachment in Base64 encoding just as XWiki would do it in an XML file of a XAR. You can use this to insert files with the same name edited somewhere else. Doing so, it also updates the filesize attribute. Here is an example:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <transformations>
     <transformation>
       <!-- Insert the content of file src/main/resources/MyApp/testcolors.xls
             as the attachment of the page TestDocumentList of the space MyApp -->

      <action>INSERT_ATTACHMENT_CONTENT</action>
      <file>MyApp/TestDocumentList.xml</file>
      <xpath>/xwikidoc/attachment[/filename[text()='testcolors.xls']]</xpath>
      <content>src/main/resources/MyApp/testcolors.xls</content>
    </transformation>
   </transformations>
 </configuration>
</plugin>

Documents types

Since 10.3

It's possible to indicate in the pom.xml the type of a each document. That way the package.xml will be generated automatically but will take into account information it cannot really deduce from the documents XML files.

      <plugin>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
       <configuration>
         <entries>
           <entry>
             <document>Main.WebHome</document>
             <type>home</type>
           </entry>
           <entry>
             <document>Some.Demo.Page</document>
             <type>demo</type>
           </entry>
           <entry>
             <document>MyApplication.MyConfiguration</document>
             <type>configuration</type>
           </entry>
         </entries>
       </configuration>
     </plugin>

Since 12.7 You can provide the option <defaultEntryType>myEntryType</defaultEntryType> in the configuration of the plugin. When defined, the default enty type will be applied to every entry not being overridden through the <entries>...</entries> list in the plugin configuration.

You should only provide one <document> per <entry>. For example, the following configuration will not work :

  <entries>
   <entry>
     <document>MySpace.MyPage1</document>
     <document>MySpace.MyPage1</document>
     <type>demo</type>
   </entry>
 </entries>

Instead, you should write :

  <entries>
   <entry>
     <document>MySpace.MyPage1</document>
     <type>demo</type>
   </entry>
   <entry>
     <document>MySpace.MyPage2</document>
     <type>demo</type>
   </entry>
 </entries>

Format & Verify Mojo

12.3RC1There are 4 types of pages that can be defined using regexes:

  • Technical Pages: This is the default. It means pages must be hidden and not have any default language set.
  • Content Pages: These are pages having content and that can have translations. These pages must not be hidden and must have a non-empty default language (so that the XWiki search return results for them when the English language is selected in language facet for example). Example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
     <configuration>
       <contentPages>
         <contentPage>.*/Space[1-9]*/WebHome\.xml</contentPage>
       </contentPages>
     </configuration>
    </plugin>
  • Translatable Pages: These are technical pages but that can have translations. It means pages must be hidden and have a non-empty default language. When not specified it defaults to .*/.*Translations\.xml, which corresponds to XWiki platform's best practice for naming wiki translation pages. Override example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
     <configuration>
       <translatablePages>
         <translatablePage>.*/Translations\.xml</translatablePage>
       </translatablePages>
     </configuration>
    </plugin>
  • Visible Technical Pages: These are technical pages but that must be visible but that shouldn't return results in Search. For example, home pages of applications. They must not be hidden but they must have their default language set to empty. Example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
     <configuration>
       <visibleTechnicalPages>
         <visibleTechnicalPage>.*/Space/WebHome\.xml</visibleTechnicalPage>
       </visibleTechnicalPages>
     </configuration>
    </plugin>

Format Mojo

Older documentation for versions < 12.3RC1.

To use the mojo:

  • mvn xar:format will perform some cleaning of your XML files, namely:
    • Indent lines (using 2 space characters)
    • Set author, contentAuthor, creator and attachment authors to be xwiki:XWiki.Admin
    • Set version to be 1.1
    • Set minorEdit to be false
    • Remove any content of the defaultLanguage element unless the document has translations, or it's marked as a translatablePage or it's marked as a contentPage (see above).
    • Remove any content of the comment element
    • Add any missing license header by using the license defined in xwiki-commons-tool-verification-resources JAR. License headers will be checked if the formatLicense configuration parameter is set to true:
      <plugin>
       <groupId>org.xwiki.commons</groupId>
       <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
       <version>${commons.version}</version>
       <configuration>
         <!-- Add missing license headers by default -->
         <formatLicense>true</formatLicense>
       </configuration>
      </plugin>
    • Technical pages are marked hidden. Same for translatable pages.
    • 10.8+ Remove any date, creationDate, contentUpdateDate or attachment date fields, regardless if they have empty values or not. This is done because it's causing confusion for users to install pages that are created in 2005/2009/etc. so we should avoid committing dates on git that users might end up installing.
      • Can be disabled for individual pages with either -Dxar.dates.skip.documentList=Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc. (system property) or <skipDatesDocumentList>Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc.</skipDatesDocumentList> (plugin configuration parameter).
      • Can be disabled for all pages in the xar with either -Dxar.dates.skip=true (system property) or <skipDates>true</skipDates> (plugin configuration parameter).
    • 13.3+ Forces the XML version to be 1.1

Verify Mojo

Older documentation for versions < 12.3RC1.

This is used to fail the build if the XML pages don't conform to the following rules:

  • Verify that the encoding is UTF-8
  • Verify that author, contentAuthor, creator and attachment authors are set to xwiki:XWiki.Admin
  • Verify that the parent field is not empty (except for Main.WebHome). This check became optional (and turned off  by default) in XWiki 11.10.3 & 12.0RC1.
    • To turn if on, set <emptyParentSkip>false</emptyParentSkip> in the POM or pass -Dxar.verify.translationVisibility.skip=false on the Maven command line
  • Verify that version is set to 1.1
  • Verify that comment is empty
  • Verify that minorEdit is set to false
  • Verify that the defaultLanguage is empty for technical documents and visibleTechnicalPages (see above).
  • Verify that the defaultLanguage is not empty for contentPages and translatablePages (see above) and it matches the configured language in the mojo (by default en, it's configurable in the <configuration>, for example <defaultLanguage>fr</defaultLanguage>).
  • (optional) Verify that the XML files contain license headers (if the formatLicense configuration property is set to true).
  • Verify that technical pages, and translatablePages are set as hidden, and that contentPages and translatablePages are set as npot hidden.
  • Verify that defined pages have a specific matching title. For example:
    <plugin>
     <groupId>org.xwiki.commons</groupId>
     <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
    ...
     <configuration>
    ...
       <titles>
         <!-- Verify that all WebPreferences pages have the same title for consistency -->
         <property>
           <name>.*WebPreferences</name>
           <value>\$services\.localization\.render\('admin.preferences.title'\)</value>
         </property>
       </titles>
     </configuration>
    </plugin>
  • Verify that Translations pages (i.e. documents with a XWiki.TranslationDocumentClass xobject) are using the plain/1.0 syntax.
  • New in 10.1RC1 Verify that Translations pages don't have a GLOBAL or USER visibility (USER makes no sense and GLOBAL would require Programming Rights, which is an issue in farm-based use cases). This check can be ignore by using the translationVisibilitySkip configuration option (or xar.verify.translationVisibility.skip on the command line).
  • New in 10.6RC1 Verify that attachments have a mimetype set. If the mimetype is missing then the attachment won't be filterable in the attachment view in Page Index.
  • New in 10.8RC1 Verify that any date, creationDate, contentUpdateDate or attachment date fields are not specified, thus risking to import pages with stale dates.
    • Can be disabled for individual pages with either -Dxar.dates.skip.documentList=Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc. (system property) or <skipDatesDocumentList>Space1.Subspace2.Page1,Space2.Subspace2.Page2,etc.</skipDatesDocumentList> (plugin configuration parameter).
    • Can be disabled for all pages in the xar with either -Dxar.dates.skip=true (system property) or <skipDates>true</skipDates> (plugin configuration parameter).
  • New in 13.1RC1 and 12.10.4 Verify that translated pages don't contain any attachment.
  • New in 13.1RC1 and 12.10.4 Verify that translated pages don't contain any object.

Example usage:

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

To skip the execution of the verify mojo, you can use the property xar.verify.skip with the value true.

UnXAR Mojo

To configure it:

<plugin>
 <groupId>org.xwiki.commons</groupId>
 <artifactId>xwiki-commons-tool-xar-plugin</artifactId>
 <configuration>
   <groupId>...group id of XAR artifact to expand...</groupId>
   <artifactId>...artifact id of XAR artifact to expand...</artifactId>
   <outputDirectory>${project.build.outputDirectory}</outputDirectory>
   <includes>
     <include>Space/Page.xml</include>
      ...
   </includes>
   <excludes>
     <exclude>Space/Page.xml</exclude>
      ...
   </excludes>
 </configuration>
</plugin>

To use it:

  • mvn unxar will expand the XAR file
Tags:
   

Get Connected