Repository navigation
JLBP-6 is misleading regarding "don’t publish the same classes under multiple Maven IDs" #2456
Description
The current text is
Whether or not you make breaking changes, don’t publish the same classes under multiple Maven IDs; this creates a situation where artifacts have “overlapping classes.” Another best practice, JLBP-5, covers how consumers need to handle such problematic scenarios — don’t create new cases!
However, in practice this is a Maven-only flaw.
Gradle can handle diamon dependency resolution automatically, and Gradle does enable publishers to evolve their libraries with backward compatibility in mind.
For example:
commons-compress-1.0.jar: a single jar with all the compressors (gz, tar, zip)commons-compress-1.0.jar: no classes, just a pom artifact for backward compatibility. It would depend on all the othercommons-compress-*-1.1.jarartifactscommons-compress-base-1.1.jar: base interfaces, no compressor codecommons-compress-tar-1.1.jar: only tar-related classescommons-compress-gz-1.1.jar: only gz-related classes
Gradle enables publisher to declare platform constraint (see https://blog.gradle.org/alignment-with-gradle-module-metadata), so the resolver would automatically resolve the diamond.
With Gradle platform in mind, commons-compress-base:1.1 could add platform constraint on commons-compress:1.1.
It will let Gradle know that if it sees commons-compress on the classpath, it should bump it to at least 1.1.
That fixes diamond dependency.
I've published a reproducer project: https://github.com/vlsi/jarsplit
It works fine with Gradle and it fails with Maven, so it highlights that the bug is Maven tool-related only.
Activity
Suraj8982 commentedon Nov 9, 2025
Hi @vlsi ,
I’d like to take this issue. From the description and the reproducer, it seems the overlapping classes problem is specific to Maven, while Gradle’s module metadata resolves it via platform constraints. I’ll review JLBP-6 and draft a clarification to distinguish Maven-specific limitations from general best practices. Kindly, assign this issue to me.
elharo commentedon Jul 7, 2026
The text is correct as written and this issue can be closed. Publishing the same classes under multiple Maven IDs causes problems with both Gradle and Maven and other tools. It is not unique to Maven. The problems come about in the JVM itself, not in one specific build tool.
vlsi commentedon Jul 8, 2026
The diamond conflict is the only failure mode JLBP-6 cites, and that's exactly where Maven and Gradle differ. Gradle gives users a way to resolve such a diamond automatically (Module Metadata + alignment/capabilities): when the split 1.1 modules are on the graph, the old coordinate is aligned to the empty 1.1 redirect POM, so no class ever appears twice on the resolved classpath. Maven gives users no equivalent. There's no way for a consumer to align or dedupe overlapping classes, so the same layout breaks. My reproducer shows precisely this: it builds and runs under Gradle and fails under Maven.
So the problem isn't inherent to the JVM or to library design. It's that Maven has no user-level mechanism to resolve the diamond, while Gradle does.
The need this unblocks is real. Maintainers of widely-used libraries have asked for exactly this: splitting a monolithic jar into modules while keeping backward compatibility. And they pointed at Maven as the blocker: log4j (https://lists.apache.org/thread/z5vqbh75nsl03sy26xtrxh3fwv1h2kn7) and Guava (google/guava#8079 (comment)). JLBP-6 currently tells all of them "don't", based on a constraint that only holds for Maven consumers.
@elharo , if you see a case where this genuinely breaks under Gradle, please post a concrete build and I'll look at it. My reproducer demonstrates the opposite: unsolvable in Maven, resolved automatically in Gradle.
elharo commentedon Jul 8, 2026
read JLBP-5
vlsi commentedon Jul 8, 2026
The current issue is about JLBP-6
elharo commentedon Jul 8, 2026
I reiterate:
vlsi commentedon Jul 8, 2026
Elliotte, I have read JLBP-5, and I agree with it.
I do not suggest we should violate JLBP-5.
What I raise here is Maven defect that causes JLBP-5 violation.
Please read my example. It triggers JLBP-5 violation with Maven and it runs fine without triggering JLBP-5 in Gradle.