Migrate from wcm.io Maven aem-global-parent 1.4.x to 1.5.x

If you are updating the io.wcm.maven:io.wcm.maven.aem-global-parent dependency in the parent POM of your project to a version 1.5.x you have to do some manual steps described in this article. Some are mandatory, some are optional (but recommended anyway).

Mandatory: Define dependencies for OSGi annotations

A couple of dependencies defined by OSGi and the Sling project should be available in every Maven Build because they provide annotations like @Component and @SlingServlet helping you define OSGi components and services in a convenient way. Up to 1.4.18 those where defined as dependencies directly in aem-global-parent.

But these versions are depending on the AEM version you are using, and the versions of the OSGi bundles deployed to it. Thus the version definition of these dependencies were moved to the AEM Dependencies POMs, and you have to define them (without version number) in your project’s parent POM.

Add to your parent POM:

<dependencies> <!-- OSGi bundle and versioning annotations --> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.annotation.bundle</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.annotation.versioning</artifactId> <scope>provided</scope> </dependency> <!-- OSGi DS and metatype annotations --> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.component.annotations</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.metatype.annotations</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.apache.sling</groupId> <artifactId>org.apache.sling.servlets.annotations</artifactId> <scope>provided</scope> </dependency> </dependencies>

You also have to make sure to update to at least these version of the AEM dependencies POM depending on your AEM major version and service pack level:

  • io.wcm.maven:io.wcm.maven.aem-dependencies 6.4.0.0002

  • io.wcm.maven:io.wcm.maven.aem-dependencies 6.4.8.0003

  • io.wcm.maven:io.wcm.maven.aem-dependencies 6.5.0.0003

  • io.wcm.maven:io.wcm.maven.aem-dependencies 6.5.6.0001

  • io.wcm.maven:io.wcm.maven.aem-dependencies 6.5.7.0001

  • io.wcm.maven:io.wcm.maven.aem-cloud-dependencies 2020.12.4676.20201216T130744Z-201201.0000

With version 1.5.0 we have also removed a couple of managed dependencies deprecated a long while ago. If you still use them you have to define them manually (or better: get rid of them):

  • org.apache.felix:org.apache.felix.scr.annotations - Use OSGi annotations instead

  • com.google.code.findbugs:annotations - Use com.github.spotbugs:spotbugs-annotations instead

  • com.google.code.findbugs:jsr305 - Use org.jetbrains:annotations instead

Optional: Switch to individual OSGi artifacts

AEM applications usually need some OSGi core and compendium packages at compile time. In the past, it was the usual approach to define a dependency to osgi.core and osgi.cmpn which included everything that was defined for a major OSGi version. But that does not necessarily match to what is really deployed in the AEM instance, as not all bundles are updated to the latest OSGi spec at the same time, and some are not present at all.

Thus it is recommended to remove all these dependency definitions like:

  • org.osgi:osgi.core or org.osgi:org.osgi.core

  • org.osgi:osgi.cmpn or org.osgi:org.osgi.compendium

And instead add the individual OSGi artifacts as required (only pick what you need, all versions are defined in the AEM Dependencies POMs):

<dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.framework</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.resource</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.component</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.metatype</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.cm</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.event</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.http</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.http.whiteboard</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.service.log</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.util.converter</artifactId> <scope>compile</scope> </dependency> <dependency> <groupId>org.osgi</groupId> <artifactId>org.osgi.util.tracker</artifactId> <scope>compile</scope> </dependency>

Most times you need not more than one or two of them. Start with adding none of them and see if everyhing compiles, if not add one-by-one. wcm.io Libraries in the latest versions (released in 2021 or later) already define compile-dependencies to them, so you get some of them automatically. Same applies for unit tests with the latest versions of AEM Mocks (since 4.0.0), Sling Mocks (since 3.0.0) and OSGi Mocks (since 3.0.0).

We recommend to define these dependencies with compile scope, although this has no effect on the OSGi bundle. But it is helpful in unit tests when multiple bundles are involved to make sure everything that is required to run in the mocked environment is available in the classpath.

Watch out: File Vault Validation

In version 1.5.2 of aem-global-parent we’ve also updated to the latest version 1.1.6 of Apache Jackrabbit FileVault Maven Plugin which comes with a lot of new and improved validation rules for content packages build with Maven.

It is likely that your existing content packages definitions contain some inconsistencies and your build might fail after updating. We have a separate article helping with this: