{"type":"doc","content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Background","type":"text"}]},{"type":"paragraph","content":[{"text":"The current OpenMRS Reference Application runs smoothly on the ","type":"text"},{"text":"Java 21 runtime","type":"text","marks":[{"type":"strong"}]},{"text":". However, most of our ","type":"text"},{"text":"community-supported modules","type":"text","marks":[{"type":"strong"}]},{"text":" cannot be compiled with Java 21.","type":"text"}]},{"type":"paragraph","content":[{"text":"As we plan for the next major release—","type":"text"},{"text":"OpenMRS Platform 3.0.0","type":"text","marks":[{"type":"strong"}]},{"text":"—we've identified that upgrading to ","type":"text"},{"text":"Spring 6","type":"text","marks":[{"type":"strong"}]},{"text":" and ","type":"text"},{"text":"Hibernate 6","type":"text","marks":[{"type":"strong"}]},{"text":" requires us to ","type":"text"},{"text":"drop support for Java 8","type":"text","marks":[{"type":"strong"}]},{"text":" and adopt a Java version ","type":"text"},{"text":"17","type":"text","marks":[{"type":"strong"}]},{"text":" or higher. Since migrating to any newer Java version involves similar effort, and ","type":"text"},{"text":"Java 21","type":"text","marks":[{"type":"strong"}]},{"text":" is the latest Long-Term Support (LTS) version, we've decided it's best to move directly to ","type":"text"},{"text":"Java 21","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"After discussions with the community, we've outlined the following ","type":"text"},{"text":"migration plan","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"OpenMRS Core","type":"text","marks":[{"type":"strong"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add ","type":"text"},{"text":"support for Java 21","type":"text","marks":[{"type":"strong"}]},{"text":" while continuing to support ","type":"text"},{"text":"Java 8","type":"text","marks":[{"type":"strong"}]},{"text":", ensuring backward compatibility during the transition.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"OpenMRS Modules","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Each module will be reviewed individually to determine whether to:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Update the module","type":"text","marks":[{"type":"strong"}]},{"text":" to support Java 21, or","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Deprecate the module","type":"text","marks":[{"type":"strong"}]},{"text":" and migrate its functionality to a more modern or consolidated alternative.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For modules that will be updated to support Java 21, the following steps will be taken:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Update the base platform version","type":"text","marks":[{"type":"strong"}]},{"text":" to ","type":"text"},{"text":"2.7.0","type":"text","marks":[{"type":"strong"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add Java 21 support","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b472cf14-ccdc-44d2-95ec-f59ca557970c"}},{"type":"strong"}]},{"text":" while retaining Java 8 compatibility where possible.","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"b472cf14-ccdc-44d2-95ec-f59ca557970c"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"With the release of ","type":"text"},{"text":"Platform 3.0.0","type":"text","marks":[{"type":"strong"}]},{"text":", perform a full migration to Java 21 and create a ","type":"text"},{"text":"Java 8-compatible branch","type":"text","marks":[{"type":"strong"}]},{"text":" (2.8.x) for legacy support.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Migration Guide for modules","type":"text"}]},{"type":"paragraph","content":[{"text":"We hope that this migration guide will help you solve some issues you will face while adding support for Java 21. However, as each module is different ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Update the Module to Platform 2.7.0","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Java 21 support begins with OpenMRS Platform 2.7.0, so the first step is to update your module’s platform version to 2.7.0. After updating, try compiling the module using Java 8. You may encounter a few errors — here’s how to address some common ones.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Common Issues and Solutions","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":" ","type":"text"},{"text":"1. Compile Errors Due to Removed Deprecations","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Some previously deprecated classes and interfaces may have been removed as part of the upgrade. To find replacements, check the OpenMRS documentation or core repository.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"If you're using: ","type":"text"},{"text":"org.openmrs.module.web.extension.AdministrationSectionExt","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"This class has been moved from ","type":"text"},{"text":"core","type":"text","marks":[{"type":"strong"}]},{"text":" to the ","type":"text"},{"text":"legacyui module","type":"text","marks":[{"type":"strong"}]},{"text":". To resolve this, add the following dependency in your module's ","type":"text"},{"text":"pom.xml","type":"text","marks":[{"type":"code"}]},{"text":":","type":"text"}]},{"type":"codeBlock","content":[{"text":" \n org.openmrs.module\n legacyui-omod\n ${legacyUiVersion}\n provided\n ","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"2. org.hibernate.AssertionFailure: Unable to locate referenced entity mapping in Tests","type":"text"}]},{"type":"paragraph","content":[{"text":"If you encounter this error during testing, it likely means that Hibernate is unable to detect certain entity classes. You need to explicitly register the OpenMRS packages in your module’s ","type":"text"},{"text":"TestingApplicationContext.xml","type":"text","marks":[{"type":"code"}]},{"text":" by adding them to the ","type":"text"},{"text":"sessionFactory","type":"text","marks":[{"type":"code"}]},{"text":" bean configuration.","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n \n \n classpath:hibernate.cfg.xml\n classpath:test-hibernate.cfg.xml\n \n \n \n \n \n \n \n \n org.openmrs\n \n \n","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":4},"content":[{"text":"3. Getting a prompt for a username and password when running some tests.","type":"text"}]},{"type":"paragraph","content":[{"text":"In some cases, you may be prompted for a ","type":"text"},{"text":"username and password","type":"text","marks":[{"type":"strong"}]},{"text":" when running tests, especially when the test class uses ","type":"text"},{"text":"@DirtiesContext","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph"},{"type":"mediaSingle","attrs":{"layout":"center","width":476,"widthType":"pixel"},"content":[{"type":"media","attrs":{"width":476,"alt":"Screenshot from 2025-05-02 11-56-33.png","id":"259225bb-196f-498f-a2b9-77953f6d6df8","collection":"contentId-443514897","type":"file","height":160}}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"To avoid this prompt, add ","type":"text"},{"text":"@SkipBaseSetup","type":"text","marks":[{"type":"code"}]},{"text":" to the test class. With ","type":"text"},{"text":"@SkipBaseSetup","type":"text","marks":[{"type":"code"}]},{"text":", you may also need to manually load ","type":"text"},{"text":"INITIAL_XML_DATASET_PACKAGE_PATH","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"EXAMPLE_XML_DATASET_PACKAGE_PATH","type":"text","marks":[{"type":"code"}]},{"text":" for some tests.","type":"text"}]},{"type":"paragraph"},{"type":"codeBlock","content":[{"text":"@Before\npublic void setupDatabase() throws Exception {\n initializeInMemoryDatabase();\n authenticate();\n executeDataSet(INITIAL_XML_DATASET_PACKAGE_PATH);\n executeDataSet(EXAMPLE_XML_DATASET_PACKAGE_PATH);\n executeDataSet(XML_DATASET_PACKAGE_PATH);\n}","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":4},"content":[{"text":"4. Tests are not running","type":"text"}]},{"type":"paragraph","content":[{"text":"If mvn clean install completes without running any tests, it may be due to the use of maven-parent-openmrs-module in your pom.xml. To fix this, remove the block referencing the parent module.","type":"text"}]},{"type":"codeBlock","content":[{"text":"// Remove this\n\n org.openmrs.maven.parents\n maven-parent-openmrs-module\n 1.1.1\n","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: ","type":"text","marks":[{"type":"strong"}]},{"text":"Adding support for Java 21","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Switch your Java version to 21","type":"text","marks":[{"type":"strong"}]},{"text":" and try compiling the module. There are a few known issues when adding support for Java 21.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Source option X is no longer supported. Use 8 or later","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"This happens when the ","type":"text"},{"text":"maven-compiler-plugin","type":"text","marks":[{"type":"code"}]},{"text":" is configured with a ","type":"text"},{"text":"source","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"target","type":"text","marks":[{"type":"code"}]},{"text":" version lower than Java 8. Update your ","type":"text"},{"text":"pom.xml","type":"text","marks":[{"type":"code"}]},{"text":" to set the compiler plugin to use Java 8.","type":"text"}]},{"type":"codeBlock","content":[{"text":"\n org.apache.maven.plugins\n maven-compiler-plugin\n \n 1.8\n 1.8\n \n","type":"text"}]},{"type":"paragraph"},{"type":"heading","attrs":{"level":4},"content":[{"text":"java.lang.reflect.InaccessibleObjectException errors","type":"text"}]},{"type":"paragraph","content":[{"text":"These errors occur due to ","type":"text"},{"text":"strong runtime encapsulation","type":"text","marks":[{"type":"strong"}]},{"text":" introduced in modern Java versions (Java 17+).","type":"text"}]},{"type":"paragraph","content":[{"text":" ","type":"text"},{"text":"Avoid using ","type":"text","marks":[{"type":"strong"}]},{"text":"argLine","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text","marks":[{"type":"strong"}]},{"text":"--add-opens","type":"text","marks":[{"type":"code"}]},{"text":" flags","type":"text","marks":[{"type":"strong"}]},{"text":" to bypass these errors, it's a temporary workaround and not a proper solution.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Update outdated dependencies ","type":"text","marks":[{"type":"strong"}]},{"text":"to versions that support modern Java.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If a dependency is ","type":"text"},{"text":"deprecated or no longer maintained,","type":"text","marks":[{"type":"strong"}]},{"text":" consider replacing it.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text","marks":[{"type":"strong"}]},{"type":"hardBreak"},{"text":"Replace ","type":"text"},{"text":"PowerMock","type":"text","marks":[{"type":"code"}]},{"text":" (which relies on deep reflection) with ","type":"text"},{"text":"Mockito.mockStatic","type":"text","marks":[{"type":"code"}]},{"text":", which is supported in recent versions of Mockito.","type":"text"}]},{"type":"paragraph"},{"type":"paragraph"},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Epic: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://openmrs.atlassian.net/jira/polaris/projects/OMRS/ideas/view/3970978?selectedIssue=OMRS-341"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"Talk Discussion: ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://talk.openmrs.org/t/planning-java-21-migration-for-openmrs-modules/45713?u=wikumc"}},{"text":" ","type":"text"}]},{"type":"paragraph"}],"version":1}