Skip to content

docs: compare JPA cascades with Storm write sets (reference + tutorial)#272

Merged
zantvoort merged 4 commits into
mainfrom
docs/jpa-cascades-vs-write-sets
Jul 15, 2026
Merged

docs: compare JPA cascades with Storm write sets (reference + tutorial)#272
zantvoort merged 4 commits into
mainfrom
docs/jpa-cascades-vs-write-sets

Conversation

@zantvoort

@zantvoort zantvoort commented Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • New reference page JPA Cascades vs Write Sets (docs/jpa-cascades-vs-write-sets.md, sidebar: Resources). Implements the same Owner-Pet-Visit graph in both models and explains the philosophy: cascades travel parent-to-child along mapped collections, write-set discovery follows foreign key fields upward, so insert discovery needs no configuration and delete discovery deliberately does not exist. Includes an action-by-action mapping (persist/merge/remove) and a cascade translation table. Cross-linked from the write-sets reference and the JPA migration guide.
  • New tutorial Persisting object graphs: cascades vs write sets at /tutorials/object-graphs, added to the From JPA series with its hub card.
  • The referenced-entity contract, stated with its rationale in the WriteSet javadoc, the write-sets reference, and both new pages: a write set writes the entities you name, plus the entities your values make necessary. A modified keyed entity held in a foreign key field is not written (a hydrated snapshot is not write intent); pass it as an explicit member.
  • Write-set operation terminology unified on "action" (was "verb") across javadoc, KDoc, docs, and the private enum in WriteSetImpl; the write-set test suite passes (25 tests).
  • Site polish: one gold family (#feeeb0 / #fbbf24 / #f59e0b) across the figure gradients and accents, centered benchmark matrix headers, styled inline code inside tutorial note boxes (previously fell through to Infima's light styling), and the benchmarks page now uses the example pages' clone bar with a "View on GitHub" button.

Notes

  • The write-set snippets use the vararg call shape (writeSet().insert(wolfie, rex, visit)), which does not exist on WriteSet yet; the vararg overloads need to land before the 1.13.0 release ships these pages.
  • The reference pages are docs/-only and appear at /docs/next until the next docs snapshot; the tutorial deploys with the site. Merging around the release keeps the tutorial's /docs/write-sets links from going live before the target pages do.

Verification

  • Full Docusaurus production build passes; both pages render (tabs, editor panels, hub card, series count).
  • storm-core write-set tests pass after the terminology rename (25 tests).
  • Copy checked against site rules: no em dashes, no banned words, JPA treated neutrally (cascade convenience acknowledged; trade-offs stated symmetrically).

…orial

- New reference page under Resources: the same Owner-Pet-Visit graph in
  both models, the direction inversion (cascades travel parent-to-child
  along collections, write set discovery follows FK fields upward), the
  managed-graph vs explicit-operation trade-off stated symmetrically,
  verb-by-verb mapping, and a cascade translation table
- New tutorial at /tutorials/object-graphs in the From JPA series, with
  the hub card and series count
- Cross-links from the write-sets reference and the JPA migration guide

The write-set snippets use the vararg call shape planned for 1.13.0;
the vararg overloads must land before the release ships these pages.
…e note code

- One gold family across the site: the figure gradients, active chips,
  and link hovers all draw from #feeeb0 / #fbbf24 / #f59e0b (code-editor
  syntax tokens keep their own palette)
- Center the benchmark matrix header row; data cells stay right-aligned
- Inline code inside tutorial note boxes previously fell through to the
  Infima defaults and rendered as a light chip; it now uses the same
  dark chip as inline code elsewhere on the page
…minology

- One rule, stated in the WriteSet javadoc, the reference docs, and both
  comparison pages: a write set writes the entities you name, plus the
  entities your values make necessary. An unsaved referenced entity is
  necessary (its dependent cannot be written without its key, and a row
  that does not exist cannot be a stale copy); a keyed referenced entity
  never is: it is the state hydrated when the value was read, and
  treating that snapshot as write intent would silently overwrite newer
  database state
- update/upsert javadoc now state explicitly that a modified referenced
  entity is not written and that changed entities must be passed as
  explicit members
- Rename the write-set operation terminology from verb to action across
  javadoc, KDoc, docs, tutorial pages, and the private Action enum in
  WriteSetImpl (write-set test suite passes: 25 tests)
Replace the inline reproduce-it sentence with the clone bar and
"View on GitHub" button used on the example pages.
@zantvoort zantvoort merged commit 8c2ce28 into main Jul 15, 2026
7 checks passed
@zantvoort zantvoort deleted the docs/jpa-cascades-vs-write-sets branch July 15, 2026 07:20
zantvoort added a commit that referenced this pull request Jul 15, 2026
All seven actions accept entities as varargs next to the canonical
Iterable forms: insert, insertAndFetch, update, updateAndFetch, upsert,
upsertAndFetch and remove. The overloads are default methods delegating
to the Iterable forms; Entity<?> is reifiable, so they are warning-free
without @SafeVarargs. Single-entity and typed single-root overloads
keep winning one-argument resolution in both Java and Kotlin, and an
empty call is a no-op.

The write-sets reference now shows the vararg shape where entities are
enumerated inline, matching the comparison pages shipped in #272.

Fixes #273
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