Migrate content package projects from wcmio-content-package-maven-plugin to Jackrabbit filevault-package-maven-plugin

Problem

Since October 2017, the Apache Jackrabbit project provides an open source implementation of a content package plugin, the Jackrabbit FileVault Package Maven Plugin. This is a successor of the Adobe Content Package Maven plugin (but only of the part for building content packages, omitting the goals for interacting with the package manager HTTP interface).

It is recommended to start new projects only with the Jackrabbit FileVault Package Maven Plugin, and migrate existing projects that use the Adobe Content Package Maven Plugin or the wcm.io Content Package Maven Plugin to this. In both cases this is mainly a drop-in replacement.

This guide documents some special treatments that may be required when migrating a content package Maven project from wcm.io Content Package Maven Plugin to Jackrabbit FileVault Package Maven Plugin.

Solution

Switch plugin definition

Edit all pom.xml with packaging type content-package
Switch plugin definition from io.wcm.maven.plugins:wcmio-content-package-maven-plugin to org.apache.jackrabbit:filevault-package-maven-plugin
Make sure you've updated to wcm.io aem-global-parent 1.2.12 or higher - this contains the latest plugin version and sensible configuration defaults for the Jackrabbit filevault-package-maven-plugin
You should add a new plugin property packageType and set it to:
- application: An application package consists purely of application content. It serializes entire subtrees with no inclusion or exclusion filters. it does not contain any subpackages nor OSGi configuration or bundles.
- content: A content package consists only of content and user defined configuration. It usually serializes entire subtrees but can contain inclusion or exclusion filters. it does not contain any subpackages nor OSGi configuration or bundles.
- container: A container package only contains sub packages and OSGi configuration and bundles. The container package is only used as container for deployment.
- mixed: Catch all type for a combination of the above.
- Hint: For "complete" packages you should switch to container, for sample content packages to content.

In case you have it in you pom you can also remove this definition - the Jackrabbit filevault-package-maven-plugin automatically detectes the jcr_root folder now without this:

<!-- REMOVE THIS - it's no longer required: -->
<resources>
  <resource>
    <directory>jcr_root</directory>
  </resource>
</resources>

Switch to embeddeds for "complete" packages

In most wcm.io-style projects we used a combination of maven-dependency-plugin and two properties dependency-includeGroupIds and dependency-includeArtifactIds to define the list of bundles (defined as maven dependencies) that should be included in the package. This can now be simplified using the embeddeds feature. The migration is optional - this old style also works with filevault-package-maven-plugin. If you want to migrate, follow these steps:

Remove the definition of maven-dependency-plugin with the executions copy-dependencies-by-groupid and/or copy-dependencies-by-artifactid
Remove the property definitions dependency-includeGroupIds and/or dependency-includeArtifactIds

Add a new block like this (adapt it to you need, reusing the group and artifact ids from the parameters dependency-includeGroupIds and/or dependency-includeArtifactIds):

<embeddeds>
  <!-- Example for including all direct or transitive dependencies with these group ids into the package -->
  <!-- Please note: You have to use the full group id, using only parts of it will not match -->
  <embedded>
    <groupId>
      io.wcm,
      my.application.package
    </groupId>
  </embedded>
  <!-- Example for adding some explicit additional Sling artifacts in the package -->
  <embedded>
    <groupId>
      org.apache.sling
    </groupId>
    <artifactId>
      org.apache.sling.models.api,
      org.apache.sling.models.impl
    </artifactId>
  </embedded>
</embeddeds>

Add a configuration property embeddedTarget and set it to the install folder of your application - example:
```
<embeddedTarget>/apps/${content-package-name}/install</embeddedTarget>
```

Configuration property compatibility

Nearly all plugin parameters that are supported by wcm.io Content Package Maven Plugin are also supported by Jackrabbit FileVault Package Maven Plugin. Except these:

acHandling: Use property accessControlHandling instead (also acHandling is still supported as alias). Requires filevault-package-maven-plugin 1.0.1 or higher.
thumbnailImage: Requires filevault-package-maven-plugin 1.0.1 or higher. aem-global-parent 1.2.12 sets the default value to META-INF/vault/definition/thumbnail.png.
filterSource: This property exists, but has not default value. aem-global-parent 1.2.12 sets the default value to META-INF/vault/filter.xml.
subPackages/*/generateFilter: Use subPackages/*/filter property instead
embeddeds/*/generateFilter: Use embeddeds/*/filter property instead

The new default values for filterSource and thumbnailImage are different than those used by the wcm.io plugin. If you relied on the old ones you have to update your project. The new values are better compatible with AEM/Sling IDE integration for Eclipse.