Upgrading a Module to Platform 2.4 or newer

Owned by Ian Bacher
Oct 27, 2020

Platform 2.4 introduces a number of upgrades to the main libraries used by the OpenMRS platform, most notably Spring, Hibernate, Liquibase, and Log4J (which migrated to Log4J2, a complete rewrite). As a result of these upgrades, certain functionality that was deprecated in previous versions of these libraries has been entirely removed. For the most part, there are only a small number of changes necessary to modules to support platform 2.4 and these changes should be backwards compatible with versions of OpenMRS back to 1.9, as they take advantage of functionality added in Spring 3.1.

The most common changes needed to update modules to 2.4 are these:

  • Previous versions of Spring used the class org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping to ensure that URLs loaded through Spring annotations were registered with the Spring DispatcherServlet . This means that many modules will have a line like the following in their webModuleApplicationContext.xml file:
<bean class="org.springframework.web.servlet.mvc.annotation.DefaultAnnotationHandlerMapping"/>

These lines should be deleted from the webModuleApplicationContext.xml file. The DefaultAnnotationHandlerMapping class was replaced with RequestMappingHandlerMapping in Spring 3.1 and is loaded by the default OpenMRS context.

  • In previous versions of Spring, the <ref/> element supported an attribute called local to reference beans defined in the same XML document. See the old Spring 1.2 documentation. Support for the local attribute has been removed from Spring 5, but has no meaningful impact on the ability of Spring to load those references. This does, however, mean that <ref/>  elements like the below need to be replaced by replacing the local attribute with the bean attribute:
<ref local="providerSuggestionService"/>
<ref bean="providerSuggestionService"/>


The Liquibase changes should be largely invisible to modules, as almost all previous features continue to be supported in the current version of Liquibase. However, if a module explicitly depends on one of the old Liquibase extensions, this dependency should be removed as these extensions are no longer supported and if on the classpath, will cause OpenMRS to fail to start. A rewritten version of the modifyColumn  extension is available as part of Platform 2.4 and the other extensions are no longer necessary for the new Liquibase version. See this comment for details.

Similarly, the Log4J → Log4J2 upgrade should be largely invisible to modules, especially if they are using SLF4J, which is our preferred method for modules to obtain and use logger instances. In some cases, a module might be changing the logging configuration on-the-fly, e.g., to add a new appender or change logging levels, etc. In those cases, the code will likely need to be completely re-written as the internal architecture of Log4J2 is completely different from Log4J. See the official documentation on compatibility between these versions and this commit for the changes made to core as an example of the kinds of changes necessary.

Finally, there are large changes in the functionality available in Spring and Hibernate and while we did not need to make a substantial number of changes to the modules in the RefApp to support the new versions, modules certainly might be taking advantage of features that the RefApp doesn't use. In those cases, please refer to the Spring 5 migration guide and the Hibernate 5 migration guide for details. In addition, you can look through the commits returned by this GitHub query to see the kinds of changes that were made to upgrade the RefApp modules.