Fix #2214: document that UIData row iteration during a tree visit is observable - #2216
Open
BalusC wants to merge 1 commit into
Open
Fix #2214: document that UIData row iteration during a tree visit is observable#2216BalusC wants to merge 1 commit into
BalusC wants to merge 1 commit into
Conversation
…observable UIComponent.visitTree()'s spec prose pointed at a package description for jakarta.faces.component.visit that has never existed, so the "normative specification" for tree visiting was a blank page. Point it at UIComponent.visitTree() and VisitContext, where the text already lives. Separately, nothing stated that a component visiting its children per row does so observably: the visited components see the row index change and may load that row's data. VisitHint.SKIP_ITERATION documented only the mechanism and UIData.visitTree said "iterate over the rows" without mentioning the hint, so the only normative text ran one way and opting out was left to a caller's discretion. Both now say so, descriptively. Documentation only, no behaviour change. Mojarra and MyFaces already behave this way; see eclipse-ee4j/mojarra#5864 for what happens when a traversal that only locates components loses the hint. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only, no behaviour change.
The dangling reference
UIComponent.visitTree()'s spec prose pointed at a package description forjakarta.faces.component.visitthat has never existed — there is nopackage-info.javathere — so the "normative specification" for tree visiting was a blank page. It now points atUIComponent.visitTree()andVisitContext, where the text already lives.No
package-info.javawas added. It remains defensible on its own merits, but once the two javadocs below are complete there is no normative text left homeless.Iterating is observable
Nothing stated that a component which visits its children per row does so observably: the visited components see the row index change and may act on it, including by loading that row's data.
VisitHint.SKIP_ITERATIONdocumented only the mechanism and said nothing about why a caller would want it;UIData.visitTreesaid "iterate over the rows" without mentioning the hint at all. So the only normative text ran one way — iterate — and opting out was left entirely to a caller's discretion.Both now say so, phrased descriptively rather than normatively. Mojarra and MyFaces already behave exactly this way and PrimeFaces asserts an exact
load()count against both, so no implementation has to change to remain conformant; a spec reader can now rely on what was previously only convention.Motivating case
eclipse-ee4j/mojarra#5864: an internal traversal which existed only to locate components by client id lost
SKIP_ITERATION, so it iterated everyUIDataon the way. PrimeFacesDataTabletreats row iteration as its cue to load, so every postback rendering a lazily loaded table ran its backing query twice. Nothing said the hint had to be honoured, so nothing caught it going wrong.Closes #2214
🤖 Generated with Claude Code (Opus 4.8)