[evanchooly]

Documents the listener changes from MorphiaOrg/morphia#4432, #4431 and #4429 for 3.0.

Changes

• life-cycle-methods is rewritten:
  • annotated methods, on the entity or an @EntityListeners class;
  • the per-event listener interfaces, with a table of which ones get the Document (PostPersistDocumentListener, PreLoadListener, PostLoadDocumentListener);
  • the one-interface-per-event rule, type arguments, and the lambda caveat;
  • configured global listeners (morphia.listeners and MorphiaConfig.listeners(...));
  • why leaving the Document out is cheaper;
  • @PreLoad ordering for constructor-built entities such as records.
• The DigitalSigner example is fixed. It signed the Document in @PrePersist, where it's still empty, so it signed nothing. It now signs the encoded document in a PostPersistDocumentListener. The claim that @PrePersist can return a replacement Document is gone too; return values were never used.
• configuration gains a morphia.listeners section, linking to the details.
• migrating gains a 3.0 entity-listeners section:
  • the mapping from the old EntityListener methods to the new interfaces;
  • the removal of Mapper.addInterceptor, getListeners() and hasListeners();
  • what UpgradeToMorphia30 migrates, and what it marks for a person;
  • the @PreLoad ordering change.
• The 3.0 complete-morphia-config.properties is synced with the one generated on morphia's master. That adds morphia.listeners, and also the existing morphia.decode-session-cache-size, which the docs copy was missing.

Checked

hugo builds. The new sections' anchors and the #global-listeners cross-link resolve. The javadoc links use the same ++javadoc/...++ form as the existing pages, which render it the same way.

[Copilot]

🟡 Changes recommended

The lifecycle documentation omits the EntityListener interface requirement for annotated-only listeners and the no-argument-constructor requirement for entities whose callbacks come solely from @EntityListeners.

2 open issues

• Require EntityListener implementation for annotated listeners · New
• Require a no-argument constructor for @​EntityListeners classes · New

What changed in this PR

Updates the Morphia 3.0 documentation for the new lifecycle listener interfaces and configuration-based registration.

Changes:

• Rewrites lifecycle guidance, including document access, callback ordering, and the corrected signing example.
• Adds listener migration guidance and global listener configuration instructions.
• Synchronizes the complete configuration example with the listener and decode-session cache settings.

File	Description
content/​morphia/​3.0/​migrating.md	Explains listener API migration, removed methods, and recipe limitations.
content/​morphia/​3.0/​life-cycle-methods.md	Documents listener interfaces, registration, timing, and examples.
content/​morphia/​3.0/​examples/​complete-morphia-config.properties	Adds listener and decode-session cache settings.
content/​morphia/​3.0/​configuration.md	Introduces global listener configuration and links to lifecycle guidance.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the lifecycle-listener documentation, configuration, and migration updates.

No open issues 🎉

2 resolved since last review

• Require a no-argument constructor for @​EntityListeners classes
• Require EntityListener implementation for annotated listeners

_{Review effort: Balanced}