Migrate to OpenMRS Core 3.0.0-SNAPSHOT

[dkayiwa]

Key changes:

• Upgrade Java from 8 to 21
• javax.servlet -> jakarta.servlet namespace migration
• org.apache.commons.lang -> org.apache.commons.lang3
• Jackson 1.x (org.codehaus.jackson) -> Jackson 2.x (com.fasterxml.jackson)
• Hibernate Criteria API -> JPA Criteria API in RestHelperServiceImpl
• Spring 6: CommonsMultipartResolver -> StandardServletMultipartResolver
• Spring 6: PathPatternParser compatibility (remove setPathMatcher after init)
• Hibernate 6: Cache API updates, Query API changes, strict lazy loading
• Remove legacyui-omod dependency (AdminSection extends Extension directly)
• Fix Core 3.0 API removals (Field.getAnswers, setStatus(int,String), etc.)
• Update version patterns in resources/search handlers for Core 3.0
• Fix test datasets for Core 3.0 schema changes (NOT NULL constraints)
• Add -parameters compiler flag for Spring 6 parameter name resolution

Description of what I changed

Issue I worked on

see https://issues.openmrs.org/browse/RESTWS-

Checklist: I completed these to help reviewers :)

• My IDE is configured to follow the code style of this project.

  No? Unsure? -> configure your IDE, format the code and add the changes with git add . && git commit --amend

• I have added tests to cover my changes. (If you refactored
  existing code that was well tested you do not have to add tests)

  No? -> write tests and add them to this commit git add . && git commit --amend

• I ran mvn clean package right before creating this pull request and
  added all formatting changes to my commit.

  No? -> execute above command

• All new and existing tests passed.

  No? -> figure out why and add the fix to your commit. It is your responsibility to make sure your code works.

• My pull request is based on the latest changes of the master branch.

  No? Unsure? -> execute command git pull --rebase upstream master

[dkayiwa]

@wikumChamith i switched to the CLI which behaved in the correct way (iterated until all errors were fixed and tests passed). What do you think about its output? 😊

[wikumChamith]

@wikumChamith i switched to the CLI which behaved in the correct way (iterated until all errors were fixed and tests passed). What do you think about its output?

@dkayiwa, there are some test errors. Otherwise, this looks great :)

[dkayiwa]

Yes iam trying to find out why these errors are only on ci but not locally.

[dkayiwa]

Hibernate 6 changed the SecondLevelCacheStatistics API. The getEntries() method that returned a map of cached collection entries no longer exists in Hibernate 6's statistics API. There's no direct equivalent to inspect individual collection region entries, so those assertions couldn't be ported. The tests still verify the core behavior — that entity cache entries and query cache entries are cleared — just not the collection-level cache entries.

[dkayiwa]

Hibernate 6 is stricter about lazy loading. When the REST framework serializes a ConceptStateConversion, it accesses delegate.getConcept() which returns a lazy-loaded Concept proxy. In Hibernate 5 this proxy could initialize transparently, but in Hibernate 6 accessing the proxy's properties (like concept.names) outside the original Hibernate session throws a LazyInitializationException.

The @PropertyGetter("concept") re-fetches the Concept via ConceptService within an active session, ensuring it's fully initialized before serialization.

The Hibernate.initialize(delegate.getConcept()) approach avoids the extra database round-trip of fetching by UUID. However, if the LazyInitializationException is triggered by the concept's nested lazy collections (like names, descriptions), then Hibernate.initialize() on the concept alone may not be sufficient — it only initializes the top-level proxy, not its child collections. The re-fetch via ConceptService works because that service method loads the concept fully within its own transaction.

[dkayiwa]

Spring 6's PathPatternParser (which replaces the old AntPathMatcher) is stricter about URL patterns. A leading slash in the URI returned by getURI() results in a double slash when the test framework prepends the base path (e.g., /rest/v1/ + /drugreferencemap → /rest/v1//drugreferencemap). PathPatternParser rejects double slashes, causing the request to not match any handler. Removing the leading slash produces the correct path: /rest/v1/drugreferencemap.

[dkayiwa]

In Core 3.0, updateLoginCredential() has a StackWalker security check that restricts which classes can call it — it only allows HibernateUserDAO, UserDAOTest, and UserServiceTest. Our test class PasswordResetController2_2Test is not on that allow-list, so calling updateLoginCredential() would throw a DAOException("Illegal attempt to change user password from unknown caller").

setUserActivationKey() does the same saveOrUpdate but without the caller restriction, since it's specifically designed for setting activation keys (which is exactly what the test does).

The change was necessary because Core 3.0 added a StackWalker-based security check to updateLoginCredential() that only allows calls from HibernateUserDAO,
UserDAOTest, and UserServiceTest. Our test class isn't on that allow-list and would get a DAOException("Illegal attempt to change user password from unknown
caller"). setUserActivationKey() performs the same saveOrUpdate without the caller restriction, and is semantically more correct since the test is specifically
setting an activation key, not updating a password.

[dkayiwa]

field.addAnswer(fieldAnswer) → fieldAnswer.setField(field): Core 3.0 removed Field.getAnswers() and Field.addAnswer() (PR #5309, TRUNK-5797). The addAnswer() method no longer exists on the Field class. Instead, since the FieldAnswer entity still has a @manytoone reference back to Field, we set the relationship from the answer side via fieldAnswer.setField(field).

[dkayiwa]

"Null Field - YES" → "Some concept - YES": The display format is " - ". Previously, fieldAnswer.getField() returned null because the relationship was set via field.addAnswer() which populated the field's collection but didn't set the back-reference on the FieldAnswer. Now that we explicitly call fieldAnswer.setField(field), the field is properly set, so the display shows the field's actual name ("Some concept") instead of "Null Field".

[dkayiwa]

The HttpServletResponse.setStatus(int, String) method (status code + reason phrase) was removed in Jakarta Servlet 6.0 (which Core 3.0 uses). Only setStatus(int) remains. The two-argument version was deprecated since Servlet 2.1 because HTTP/2 doesn't support custom reason phrases, and Jakarta finally removed it.

[dkayiwa]

Spring 6 removed CommonsMultipartResolver (which depended on Apache Commons FileUpload). The replacement is StandardServletMultipartResolver, which uses the Servlet 3.0+ built-in multipart support (jakarta.servlet.http.Part).

The maxUploadSize property was removed because StandardServletMultipartResolver doesn't have it — upload size limits are configured in the servlet container's multipart config (e.g., via @MultipartConfig annotation or in web.xml) rather than on the resolver bean.

[dkayiwa]

The SearchConfig constructor uses Validate.notEmpty() from Apache Commons Lang. The migration from commons-lang to commons-lang3 changed the exception type: commons-lang's Validate.notEmpty(null) throws IllegalArgumentException, while commons-lang3's Validate.notEmpty(null) throws NullPointerException (it delegates to Validate.notNull() first for null values).

[dkayiwa]

This controller is a special-purpose endpoint for form resource binary values — it defines its own specific GET and POST handlers and has no use for MainResourceController's generic CRUD methods.

MainResourceController has @RequestMapping("/rest/v1") with handler methods that use {uuid} path variables (e.g. update(String uuid, ...)). FormResourceController1_9 has its own @RequestMapping("/rest/v1/form/{uuid}/resource/{resourceUuid}/value"). When it extends MainResourceController, Spring 6's PathPatternParser sees the inherited handler methods' {uuid} combined with the controller's {uuid} path and rejects the duplicate capture variable — something Spring 5's AntPathMatcher tolerated.

[dkayiwa]

In Core 2.x, NameSupport/AddressSupport always had templates pre-configured (via Spring XML in openmrs-web or legacyui), so getLayoutTemplates() never returned null. In Core 3.0, if legacyui isn't installed, no templates are configured and getLayoutTemplates() returns null — which would cause a NullPointerException on the next line (templates.size()). The null check returns an empty list instead, making the module work gracefully without legacyui.

[dkayiwa]

Core 3.0 removed the Field.getAnswers() method (PR #5309, TRUNK-5797) — the Java collection property on the Field class was removed. The FieldAnswer entity and the field_answer database table still exist, and FieldAnswer still has a @ManyToOne back-reference to Field.

So instead of navigating from the parent side (field.getAnswers()), we now query from the child side using RestHelperService.getObjectsByFields() to find all FieldAnswer objects where field equals the parent — achieving the same result via a database query instead of a collection accessor.

[dkayiwa]

This rationale is no longer accurate — legacyui-omod is now declared as an true provided dependency, so downstream modules are not forced to include it.

[dkayiwa]

The core issue is that Hibernate 6 is stricter about transient references after cascade saves.

In the original code:

1. A new ProgramWorkflowState is created, added to a workflow, and saved via saveProgram() (cascade)
2. After flushSession(), the state is persisted but the in-memory concept and state objects may hold stale references
3. When these are then used to create a ConceptStateConversion, Hibernate 6 rejects them as transient/detached references

The fix extracts the duplicated state-creation logic into a createWorkflowState() helper that does a flush/clear/re-fetch cycle:

• flushSession() — ensures the state is written to the database
• clearSession() — detaches all objects from the persistence context
• Re-fetches the workflow and finds the state from it — returns a clean, managed entity

This gives us properly managed Hibernate entities to use when creating the ConceptStateConversion. The helper also eliminates code duplication — the same state-creation pattern was repeated three times (setUp(), shouldCreateStateConversion(), shouldPurgeStateConversion()).

[dkayiwa]

Spring 6's RequestMappingHandlerMapping uses PathPatternParser by default instead of PathMatcher. When PathPatternParser is active, calling setPathMatcher() has no effect (the pattern parser takes precedence). Since we configured setPatternParser(null) elsewhere to fall back to AntPathMatcher for compatibility, the path matcher is already set at bean initialization time, making this per-request setPathMatcher() call unnecessary.

[dkayiwa]

The layout.name.format global property needs to be set before calling getDefaultLayoutTemplate(). getDefaultLayoutTemplate() delegates to getDefaultLayoutFormat(), which reads this GP to determine which template is the default (e.g., "short"). In Core 2.x, the NameSupport bean had its defaultLayoutFormat field set to "short" via Spring XML (in openmrs-web or legacyui), providing a fallback when the GP was absent. In Core 3.0's test environment, the NameSupport bean's defaultLayoutFormat field isn't set (the webModuleApplicationContext.xml from legacyui isn't loaded by the test framework), so without the GP, getDefaultLayoutFormat() returns null and getDefaultLayoutTemplate() returns
null — causing the test to fail.

[dkayiwa]

Spring 6 removed the single-argument Assert.isTrue(boolean) method. Only Assert.isTrue(boolean, String) remains, requiring a message parameter.