Skip to content

v2.0.0-modules.md

Latest commit

 

History

History
121 lines (93 loc) · 6.39 KB

v2.0.0-modules.md

File metadata and controls

121 lines (93 loc) · 6.39 KB
Raw

Migrating to 2.0 — the module split

GraphCompose 2.0 splits the single graph-compose jar into per-concern modules so an engine-only consumer no longer pulls PDFBox, POI, zxing, and the template families. This guide covers the dependency change and the API changes 2.0 makes — the retired deprecated APIs, the .v2 package rename, and the BusinessTheme removal are all listed below. The ### Removed / ### Public API sections of the changelog carry the exhaustive detail; the rationale is ADR 0016.

TL;DR — rendering PDF? Nothing changes

graph-compose is still the drop-in default. It is now an empty wrapper over graph-compose-core + graph-compose-render-pdf, so a 1.x caller who bumps the version keeps rendering PDF with no code and no dependency change.

One version for everything. All graph-compose* modules share a single version — pin one version and use it for every module you depend on, and upgrade them together. (The independently-versioned graph-compose-fonts and graph-compose-emoji add-ons are the only exceptions; see Which artifact now?.)

<dependency>
  <groupId>io.github.demchaav</groupId>
  <artifactId>graph-compose</artifactId>
  <version>2.0.0</version>
</dependency>

You only need to change your dependencies if you want a leaner tree, or if you reached a built-in template through the single jar (see the one break).

Which artifact now?

You want Depend on Change from 1.x
PDF out of the box (the 1.x behaviour) graph-compose none — same coordinate
Batteries-included (PDF + templates + fonts + emoji) graph-compose-bundle now also carries templates + emoji
A lean engine, bring your own backend graph-compose-core new — the renamed root coordinate
Built-in CV / cover-letter / invoice / proposal presets add graph-compose-templates new — opt-in, not in graph-compose
DOCX export add graph-compose-render-docx POI is no longer in the engine
PPTX export add graph-compose-render-pptx split out of the DOCX artifact
Consumer layout/visual test helpers add graph-compose-testing (test scope) unchanged coordinate

All 2.0 coordinates share the graph-compose version. graph-compose-fonts and graph-compose-emoji keep their own version lines, as they have since 1.8.0 / 1.9.0.

The one break: templates

The built-in presets (com.demcha.compose.document.templates.**) moved into the opt-in graph-compose-templates artifact, and the graph-compose wrapper does not bundle them. If your 1.x code called a preset through the single jar —

ModernInvoice.create(theme).compose(session, spec);   // needs graph-compose-templates in 2.0

— add the artifact (the package names are unchanged, so imports stay the same):

<dependency>
  <groupId>io.github.demchaav</groupId>
  <artifactId>graph-compose-templates</artifactId>
  <version>2.0.0</version>
</dependency>

Or depend on graph-compose-bundle, which includes it. This is the only dependency-level source break in the split — PDF compatibility was kept as the priority.

MissingBackendException — the lean-core signal

graph-compose-core on its own renders nothing until a render backend is on the classpath. Asking it to build a PDF throws MissingBackendException, whose message names the artifact to add:

No fixed-layout render backend on the classpath: add the
io.github.demchaav:graph-compose-render-pdf artifact (or the
io.github.demchaav:graph-compose-bundle aggregate, or another provider
implementation) to render, rasterize, or measure a document.

Depend on graph-compose (or graph-compose-bundle) instead of graph-compose-core and the PDF backend is already present. See the troubleshooting entry.

Removed deprecated APIs

2.0 also retires the @Deprecated(forRemoval) surface carried through the 1.6–1.9 line. Every entry has a canonical replacement that already exists in 1.x, so migrate the call sites before you upgrade:

Removed Replacement
DocumentSession.builder() DocumentSession.dsl()
DocumentDsl.text() DocumentDsl.paragraph()
DocumentSession.metadata(PdfMetadataOptions) and the matching watermark / protect / header / footer PDF-typed overloads the canonical metadata(DocumentMetadata) / watermark(DocumentWatermark) / protect(DocumentProtection) / header(DocumentHeaderFooter) / footer(DocumentHeaderFooter) overloads
linkOptions() on the document nodes and inline runs linkTarget() (read the external URI from ExternalLinkTarget.options())

The PDF option types (PdfMetadataOptions and friends) still exist for advanced PdfFixedLayoutBackend.builder() configuration — only the session-level shortcuts are gone.

Other 2.0 API changes

Beyond the deprecated surface above, 2.0 makes the breaking changes below. None affects plain PDF rendering; they touch template authoring and one package rename.

Change Migration
The layered template packages dropped their .v2 suffix — …document.templates.<family>.v2.* → …document.templates.<family>.* for cv, coverletter, invoice, proposal. Update imports only; behaviour and rendering are unchanged.
BusinessTheme removed, with its DocumentPalette / SpacingScale / TextScale / TablePreset companions. Author with explicit DocumentColor / DocumentTextStyle values, or a template BrandTheme. The token bundle lives on only as a styling helper inside the examples module.
The classic (pre-layered) CV and cover-letter presets removed. Use the layered templates.cv.* / templates.coverletter.* stack on BrandTheme — the single template surface now.
Font.adjustFontSizeToFit(...) removed (engine-internal). No action — text auto-sizing is resolved by the layout compiler.

Reference