fix: avoid loading UserRole members during JSON Patch apply [DHIS2-21852]

[netroms]

Summary

PATCH /api/userRoles/{uid} (JSON Patch) hydrated the entire lazy UserRole.members collection even for scalar-only patches, making a one-column update cost O(members) time and allocation. Production trace: ~4s wall / ~707 MB alloc for a role with ~320 members, where the useful work was one UPDATE userrole.

Root cause

JsonPatchManager.apply serializes the live Hibernate entity twice: valueToTree invokes every @JsonProperty getter (including UserRole.getUsers(), which iterates the lazy members set), and handleCollectionUpdates then re-invokes every schema collection getter. The serialized users data is thrown away: UserRole has no setUsers, and the metadata importer ignores non-owner properties on UPDATE.

Fix

Skip collection properties that are non-owner and not referenced by any patch path, in both serialization passes:

• valueToTree uses a per-call mapper copy with a @JsonFilter mixin bound to the entity class only (excluded getters are never invoked; nested objects serialize unchanged; fast path when nothing is excluded).
• handleCollectionUpdates skips excluded properties before safeInvoke.

Owner collections (e.g. authorities) always stay serialized, since omitting them would clear them on import UPDATE. Non-owner collections referenced by patch paths behave exactly as before. This also covers other fat inverse collections (e.g. UserGroup members) without per-entity special cases.

Performance

A/B on the platform-perf DB (~250k users), both images built from the same base commit, PATCH replace /description, Gatling sequential:

Role size	baseline p50	baseline max	patched p50	patched p95
0 members	28 ms	33 ms	19 ms	22 ms
2,000 members	263 ms	295 ms	21 ms	25 ms
83,334 members	10,833 ms	14,151 ms	18 ms	21 ms

Patched latency is independent of membership size (~600x at 83k members). SQL statement log confirms the userrolemembers hydrate query is gone and membership rows are unchanged after PATCH. GET is unaffected.

Testing

• JsonPatchManagerTest: new invariant test asserting Hibernate.isInitialized(role.getMembers()) stays false after a scalar patch apply; owner-collection (authorities) preservation; /users-path parity. 13/13 green.
• UserControllerTest: PATCH description on a role with users returns 200, description updated, users retained on GET.
• New UserRolesPerformanceTest Gatling simulation (used for the numbers above; no calibrated thresholds yet, asserts 100% success).

JIRA: DHIS2-21852

AI Assisted

[jbee]

I don't like how the mechanics of the filtering work. We have a constant hard coded into a jackson mapping filter as well as into a @JsonFilter annotation on a mixin thing. Way to complicated and entangled to be flexible or extendable for other cases. I think we should keep this simple and just hard code this as explicit and hard-coded as we can make it ideally just being in one place.

As I understand this approach it also means you cannot patch the excluded property even if targeted explicitly. If that is the case maybe we should throw an exception if the user request does attempt such a patch?

[david-mackessy]

• great to have a perf test cover this 👍
• i'd be a little worried about unknown side effects of this given it applies system-wide for all PATCHes
• the outcome seems good & this could have benefits in other unknown n+1s too
• does PUT in UserRoleController have the same issue?

[netroms]

Follow-up on system-wide PATCH side effects

Thanks — valid concern given this sits in JsonPatchManager used by all metadata PATCH.

Extra coverage added

• Integration (JsonPatchManagerTest): scalar apply must not initialize inverse collections on OrganisationUnit (children/users), User (userGroups), and UserGroup.managedByGroups; owner collections still present (User.userRoles, UserGroup.users, DataElementGroup.members, existing UserRole.authorities).
• Web-api (JsonPatchSideEffectControllerTest): HTTP PATCH name/firstName on OU / UserGroup / User leaves children/users/userGroups unchanged; PATCH replace /users on UserRole does not drop membership.

Skip rules (unchanged for collections; non-persisted props)

• Collections: only isCollection && !isOwner && path not referenced is omitted. Owner collections always serialize (omitting them would clear on import UPDATE). Note UserGroup.users is owner, so it is not skipped; the new test asserts members still round-trip on name PATCH.
• Non-persisted properties (e.g. OrganisationUnit.leaf) are also omitted when unreferenced, because derived getters can force-init inverse collections and defeat the lazy-member skip.

PUT /userRoles/{uid} — different code path
PUT does not go through JsonPatchManager. AbstractCrudController.putJsonObject deserializes the request body and calls importMetadata(UPDATE) only. The lazy members hydrate bug was PATCH-only (doPatch → jsonPatchManager.apply → valueToTree / handleCollectionUpdates). UserRoleController does not override PUT/PATCH.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
1 Accepted issue

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud