Migration Guide
Total Page:16
File Type:pdf, Size:1020Kb
MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 1 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 SUMMARY 1 INTRODUCTION ...................................................................................................................................................... 4 2 HOW TO UPGRADE FROM DIGITAL EXPERIENCE MANAGER 7.1 TO 7.2 ..................................... 5 2.1 Code base review and potential impacts .................................................................. 5 2.2 Deployment scripts/procedure review ....................................................................... 5 2.3 Test environment migration ............................................................................................ 5 3 RENDER FILTER CHANGE .................................................................................................................................... 6 3.1 Render Filters priority is now a Float instead of an Integer ............................. 6 3.1.1 Impact on the migration to Digital Experience 7.2............................................... 6 4 CUSTOM IMPLEMENTATIONS OF USERS AND GROUPS PROVIDERS ........................................... 7 5 CODE THAT NEEDS TO BE UPGRADED ........................................................................................................ 8 5.1 Overridden jmix:list’s hidden.header views need to be upgraded ................ 8 5.2 Apache PDFBox was upgraded to version 2.0.3 with API changes ............... 8 5.3 osgi:list interface needs to be changed ..................................................................... 8 5.4 Interface of ExternalUserGroupService.setConfiguration changed............... 9 5.5 Interface UserGroupProviderConfiguration changed ......................................... 9 5.6 Log4j dependencies in modules ................................................................................... 9 5.7 Methods that implement JCRReferenceDecorator.getContextualizedNode() need to catch the exceptions ................. 10 5.8 Dropped dependencies ................................................................................................... 10 6 MODULE DEPLOYMENT .................................................................................................................................... 21 © 2002 – 2017 Jahia Solutions Group SA Page 2 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 6.1 What’s new ............................................................................................................................ 21 6.2 Cluster deployment ........................................................................................................... 21 6.3 digital-factory-data/modules deployment changed ......................................... 21 6.4 Auto start mode for new modules dropped ......................................................... 22 6.5 Transitive dependencies automatically RESOLVED ............................................ 22 6.6 Tools OSGi console now for troubleshooting purposes only........................ 23 6.7 Module definition / imports now being processed when bundles are RESOLVED 23 6.8 Default OSGi state of a stopped bundle is now INSTALLED instead of RESOLVED 24 6.9 Explicit imports package are not modified to "optional" anymore. ........... 24 7 NEW MODULE BEHAVIOUR ............................................................................................................................. 26 7.1 Legacy WAR modules support is dropped............................................................. 26 8 NEW SEARCH BEHAVIOUR ............................................................................................................................... 27 9 INFRASTRUCTURE CHANGES .......................................................................................................................... 28 9.1 MySQL users need to upgrade their JDBC driver ................................................ 28 9.2 New network port needs to be opened .................................................................. 28 9.3 Support for JBoss EAP 6.2 discontinued. JBoss EAP 6.4 now officially supporte 28 9.4 Minimum version of Maven is now 3.3 .................................................................... 29 9.5 A new license is required to start Digital Experience Manager 7.2............. 29 9.6 OSGi SSH console .............................................................................................................. 29 © 2002 – 2017 Jahia Solutions Group SA Page 3 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 1 INTRODUCTION Before considering migrating to Digital Experience 7.2, please be aware of some product modifications that might impact the current codebase of both your custom modules or deployment scripts. This guide aims to provide a comprehensive checklist, as well as concrete examples of things to consider before migrating an environment. Should you have more questions, the Jahia team will be happy to assist you! Please get in touch with your account manager or our support team. © 2002 – 2017 Jahia Solutions Group SA Page 4 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 2 HOW TO UPGRADE FROM DIGITAL EXPERIENCE MANAGER 7.1 TO 7.2 2.1 CODE BASE REVIEW AND POTENTIAL IMPACTS Please read this guide carefully, it will guide you through the product’s improvements and changes, and highlight the potential impact to your codebase and environments. Even though it not necessary to upgrade all your modules to inherit from org.jahia.modules:jahia-modules:7.2.0.0 right away, it can be a good test for you to recompile your modules to target that version. It will give you a good indication of the interface changes that might impact your project. 2.2 DEPLOYMENT SCRIPTS/PROCEDURE REVIEW Digital Experience Manager 7.2 introduces brand new features such as a cluster module deployment and a new underlying OSGi platform (Apache Karaf 4.0.7). Please take the time to review the “Module deployment” section since the new behavior is likely to have an impact on your current deployment procedures and scripts. 2.3 TEST ENVIRONMENT MIGRATION It is essential that a dry run is performed on a test environment before migrating to Digital Experience Manager 7.2 in production. In the unlikely event that one of your modules isn’t behaving the same way as before, you may need to upgrade it. This guide will help you understand the necessary steps. © 2002 – 2017 Jahia Solutions Group SA Page 5 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 3 RENDER FILTER CHANGE 3.1 RENDER FILTERS PRIORITY IS NOW A FLOAT INSTEAD OF AN INTEGER The priority of Render Filters is now a Float variable, instead of the Integer. Filters extending the abstract AbstractFilter class won’t be affected by that change. However, modules that implemented RenderFilter directly will experience a ClassCastException or a NoSuchMethodError at runtime. 3.1.1 Impact on the migration to Digital Experience 7.2 It is best to extend AbstractFilter to avoid such problems in the future. However, a quick fix for classes extending RenderFilter is to re-create the setter and getter applying the priority of type Float. © 2002 – 2017 Jahia Solutions Group SA Page 6 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 4 CUSTOM IMPLEMENTATIONS OF USERS AND GROUPS PROVIDERS Please refer to the section “Interface of ExternalUserGroupService.setConfiguration changed” to make sure that your LDAP provider or any other user provider remains compatible with Digital Experience Manager 7.2. © 2002 – 2017 Jahia Solutions Group SA Page 7 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 5 CODE THAT NEEDS TO BE UPGRADED 5.1 OVERRIDDEN JMIX:LIST’S HIDDEN.HEADER VIEWS NEED TO BE UPGRADED The content of list.hidden.header.jsp changed in the default module to reflect the new Render Chain behaviour. Any project that overrides this view needs to reflect these new changes in overriden view. A project that does not declare a list.hidden.header.jsp file won’t require changes. 5.2 APACHE PDFBOX WAS UPGRADED TO VERSION 2.0.3 WITH API CHANGES PDFBox was upgraded to version 2.0.3 to benefit from its security patches. This migration might involve some API changes that need to be taken into account if used inside a project. Apache PDFBox provides migration guidelines that can be reviewed. 5.3 OSGI:LIST INTERFACE NEEDS TO BE CHANGED In order to prevent osgi:list from falling into a dead lock (osgi:list waits for the Spring context, the Spring context waits for the osgi:list tag to return), the interface of osgi:list in the context of a Spring file needs to be updated by adding the availability="optional" parameter. © 2002 – 2017 Jahia Solutions Group SA Page 8 / 29 MIGRATION GUIDE DIGITAL EXPERIENCE MANAGER 7.2 5.4 INTERFACE OF ExternalUserGroupService.setConfiguration CHANGED Custom implementations of an LDAP provider or any External and Group providers might use the setConfiguration() method which has been removed from the ExternalUserGroupService interface. Please refer to the new implementation of the LDAP provider to ensure your existing implementation is compatible. 5.5 INTERFACE UserGroupProviderConfiguration CHANGED Custom implementations of the external user/group provider, which supply custom UI for provider configuration (like our LDAP module) and which implement UserGroupProviderConfiguration interface in the module, will have to add a new method implementation: String getProviderClass(). 5.6 LOG4J DEPENDENCIES IN MODULES Internal Log4j classes are no longer exposed to modules in