Merge properties files with the same path in the merged module instead of overwriting them

[bjorndarri]

Hey there,

I've been working around this issue for quite a while, by using the extra-java-module-info plugin, see https://github.com/codion-is/chinook/blob/main/buildSrc/src/main/groovy/chinook.jasperreports.pdf.modules.gradle.

I figured it was time to see if Claude could help me solve this, which it did.

Below you'll find Claude's analysis and solution.

---

Problem

Several non-modular jars can contain a .properties file at the same path. prepareMergedJarsDir unpacks the jars one after another, so each file overwrites the one before. Only one survives, and which one depends on the order the file system lists nonmodjars.

Frameworks that find registrations through ClassLoader.getResources() silently lose entries. For example, in JasperReports 7 jasperreports and jasperreports-pdf are both automatic modules, and both ship jasperreports_extension.properties. The merged module keeps only one of them, with no warning:

• If the pdf jar's file survives, all of core's extension registrations are lost (components, font families, the resource repository and more). Reporting then breaks in ways that are very hard to trace back to this.
• If core's file survives, the only thing lost is the PDF handler for icon label elements (table header icons).

Which of the two happens can change with nothing more than a version upgrade. On ext4, a directory lists files in an order computed from their names and a per-filesystem seed, so the version in the jar names alone can flip the merge order. Here's what happened when the jar names were created in a fresh directory on the same disk:

JasperReports	listed order	file that survives
7.0.0	core, pdf	pdf's (core registrations lost)
7.0.1	core, pdf	pdf's (core registrations lost)
7.0.6	pdf, core	core's (pdf registration lost)

Fix

• Properties files with the same path are appended together, the way META-INF/services files have been merged since IIORegistry lookup #124. Identical files are kept once.
• For a conflicting key, the value from the jar whose name sorts last wins, and a warning lists the keys (up to 5).
• Jars are merged in name order, so the result is the same on every machine.
• Content is appended byte for byte, so each file's encoding is preserved.

Compatibility

When no keys conflict, the merged file has everything the surviving file had before, plus the entries that used to be dropped. When keys conflict, the jar names now decide the winner instead of file system order, and the build logs it. To keep only one jar's file, use jarExclude("other-lib", "config.properties"), now documented in the user guide.

Tests

• New MergedPropertiesSpec creates two jars with clashing extension.properties files, builds and runs an image, and checks that both sets of keys are visible. It fails on master.
• Full suite: everything passes except two jpackage --type rpm tests, which fail the same way on master on machines without rpmbuild.
• Tested on a JasperReports app, the Codion Chinook demo, without the module-info workaround: the merged jasperreports_extension.properties contains core's 11 registry factories plus the pdf one.