Skip to content

build(render-docx): bring the PDF backend so the DOCX module works on its own - #722

Merged
DemchaAV merged 1 commit into
2.5-devfrom
build/docx-dependency-smoke
Sep 23, 2026
Merged

DemchaAV merged 1 commit into
2.5-devfrom
build/docx-dependency-smoke

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Why

An application depending on graph-compose-core + graph-compose-render-docx could not
export a Word document. Opening a DocumentSession resolves a font-metrics provider, and
graph-compose-render-pdf is the only artifact that publishes one; the DOCX module declared
it at test scope, for its own suite. So the application failed before any export:

com.demcha.compose.document.exceptions.MissingBackendException: No fixed-layout render
backend on the classpath: add the io.github.demchaav:graph-compose-render-pdf artifact ...

The README documented this as "not sufficient on its own", the release smoke scenario for
DOCX adds the PDF backend by hand to get past it, and the class javadoc said the opposite —
that the one artifact was all a DOCX consumer needed. With session.buildDocx(...) on the
2.5 line, adding the DOCX module and calling it is the path a caller will take first.

What changed

graph-compose-render-pdf is a runtime dependency of graph-compose-render-docx,
the way graph-compose-render-pptx already brings it (at compile scope). Runtime rather
than compile, so nothing compiles against the PDF backend through the DOCX module. There is
no working DOCX export without it — a session cannot open — so no consumer loses anything,
and one that declared it by hand resolves the same version.

The README says so, with the 2.4.x instruction kept for those versions; the package map, the
MissingBackendException troubleshooting entry and the class javadoc follow. The README
also notes what the dependency tree showed: POI logs through the Log4j API and prints one
ERROR Log4j API could not find a logging provider. line without a provider — a notice, not
a failure — and log4j-to-slf4j at the matching version routes it. That bridge is
documented, not added: a library should not choose its consumers' logging binding.

Verification

Three consumer applications, built outside the reactor against the installed
2.5.0-SNAPSHOT artifacts, each opening a session and exporting through the session's
convenience methods:

consumer depends on result Apache POI XMLBeans PDFBox
DOCX alone core, render-docx exports 5.5.1, poi-ooxml-lite 5.3.0 3.0.8 (via render-docx, runtime)
PDF + DOCX core, render-pdf, render-docx exports 5.5.1, poi-ooxml-lite 5.3.0 3.0.8
PDF + PPTX + DOCX core, render-pdf, render-pptx, render-docx exports 5.5.1, poi-ooxml-lite 5.3.0 3.0.8

No tree carries poi-ooxml-full beside the lite schemas, and every tree resolves one version
of each — the three office backends share one schema set.

The defect was reproduced before the fix, not assumed: the DOCX-alone consumer with the PDF
backend excluded — the classpath the old test scope produced — fails at create() with the
MissingBackendException above. The Log4j bridge was checked the same way: the notice
appears once without it and not at all with it.

./mvnw -B -ntp clean verify over the eight-module gate → BUILD SUCCESS (core 815,
render-pdf 337, render-docx 248, testing 5, render-pptx 140, templates 127, qa 1788).
./mvnw -B -ntp test -f examples/pom.xml93 tests, BUILD SUCCESS.

Lane: build — render-docx/pom.xml and documentation. No API change.

Notes for review

The release smoke scenario scripts/release-smoke/s8-core-render-docx still declares the PDF
backend by hand. That is left as it is: the harness runs against a published version, and
for 2.4.1 the declaration is still needed. Once 2.5.0 is the version under test it becomes
redundant, and can be removed to make the scenario prove what this change makes true.

The consumer applications themselves are not committed: they run against installed
snapshots, which is what the release smoke harness exists to do against published versions.

… its own

Opening a DocumentSession resolves a font-metrics provider, and
graph-compose-render-pdf is the only artifact that publishes one. The DOCX
module declared it at test scope, so an application depending on
graph-compose-core + graph-compose-render-docx failed at create() with
MissingBackendException before it could export anything — while the
class javadoc said that one artifact was all a DOCX consumer needed.

The PDF backend is now a runtime dependency of the DOCX module, the way
the PPTX module already brings it: nothing compiles against it through
this module, and an application that declared it by hand resolves the
same version.

Checked with three consumer applications built outside the reactor
against the installed artifacts — DOCX alone, PDF + DOCX, and
PDF + PPTX + DOCX. Each exports, and each resolves one Apache POI
(5.5.1, poi-ooxml-lite), one XMLBeans (5.3.0) and one PDFBox (3.0.8).

The README, the package map, the troubleshooting entry and the class
javadoc now say so, and the README notes the one-line Log4j notice POI
prints without a logging provider and the bridge that routes it.
@DemchaAV
DemchaAV merged commit 6d2fafc into 2.5-dev Sep 23, 2026
12 checks passed
@DemchaAV
DemchaAV deleted the build/docx-dependency-smoke branch September 23, 2026 11:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant