Upgrading a Module to Platform 2.4 or newer
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 SpringDispatcherServlet
. This means that many modules will have a line like the following in theirwebModuleApplicationContext.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 calledlocal
to reference beans defined in the same XML document. See the old Spring 1.2 documentation. Support for thelocal
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 thelocal
attribute with thebean
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.