Migrate from wcm.io Handler 1.x to 2.x

Owned by Stefan Seifert, created
Last updated: Apr 25, 2024
3 min read

Overview

You have an existing AEM application which is using on wcm.io Handler 1.x, and you want to migrate to the latest wcm.io Handler 2.x versions. This includes switching from wcm.io WCM Core Components 1.x to 2.x.

In general, this switch is very easy and should incur no or only very few code changes in your project. Just make sure to update all wcm.io Handler dependencies at the same time to 2.x as most of the OSGi package versions got a major version bump as well.

Update POM dependencies

Update all these dependencies in your POM to latest 2.x version:

Removal of deprecated features

All features that were marked as deprecated in Handler 1.x are removed in Handler 2.x. This should not be any problem if you do not have any references to them. This affects:

  • Handler Commons API

  • Media Handler API

  • Link Handler API

Otherwise the build may fail and you have to use the alternative methods. To get indications what they are, update to latest 1.x versions and follow the instructions in the JavaDocs of each deprecated API part.

Breaking API Changes

The breaking API changes mostly affect the integration between the different Handler modules and no project code. Only if you did deeper integrations or customization in your project you might to apply adjustments:

  • Handler Commons: Removed Generic from class io.wcm.handler.commons.dom.HtmlElement and all it's sub classes. No change in functionality.

  • Media Handler: Removed Generic from classes io.wcm.handler.media.imagemap.ImageMapArea and io.wcm.handler.media.imagemap.ImageMapParser. No change in functionality.

Besides this, @Null/@NotNull annotations where added in the APIs where missing.

Change in default behavior of Media Handler

  • All AEM auto-generated renditions (filenames starting with cq5dam.* or cqdam.*) are ignored by default in the media resolving process (except cq5dam.video.* renditions). So, in most cases the original image is used to create virtual renditions. A new method getIncludeAssetAemRenditionsByDefault in MediaHandlerConfig gives your fine-grained control which auto-generated renditions are considered or not, and you can switch back to the previous behavior to set it to:

    @Override public @NotNull Set<AemRenditionType> getIncludeAssetAemRenditionsByDefault() { return Set.of(AemRenditionType.WEB_RENDITION, AemRenditionType.VIDEO_RENDITION, AemRenditionType.OTHER_RENDITION); }

  • The default image quality for JPEG images is lowered from 98% to 85%. As before, you can overwrite this value in your MediaHandlerConfig. There is new method getDefaultImageQualityPercentage in MediaHandlerConfig which allows you to directly overwrite this value:

    @Override public double getDefaultImageQualityPercentage() { return 0.98d; }

  • The support for the AEM Web-Optimized Image Delivery is enabled by default and is active only on AEMaaCS cloud images. That means wherever possible renditions are generated on the Adobe Edge by the Web-Optimized Image Delivery and not within the Java process. To disable this you can provide this OSGi configuration:

    "io.wcm.handler.mediasource.dam.impl.weboptimized.WebOptimizedImageDeliveryServiceImpl": { "enabled": false }

    • Web-Optimized Image Delivery cannot access custom renditions maybe created for assets (e.g. manual crops). If your project relies on additionally created asset renditions, you have to switch off the Web-Optimized Image Delivery and use the JVM-based rendition rendering to take them into account.

  • SVG Files are served with a Content-Security-Policy header by default. This prevents XSS attacks as SVG files uploaded by authors may contain malicious JavaScript. This is blocked by default (“sandbox” mode). In special use cases this may break existing behavior, e.g. if you use JavaScript to animate loaded SVG images. In this case you can disabled the XSS protection (do this only if you are sure authors do not upload malicious SVG files):