Describe the bug
UserInterfaceComponentModel.adoc:388-395, specifying UIComponent.visitTree() (spec $3.1.8):
Uses the visit API introduced in version 2 of the specification to perform a flexible and customizable visit of the tree from this instance and its children. Please see the package description for the package jakarta.faces.component.visit for the normative specification.
There is no such package description. api/src/main/java/jakarta/faces/component/visit/ holds no package-info.java — the only one in the whole API is jakarta.faces.component.html — and the generated javadoc's package summary for it carries no description section at all.
So the normative specification for tree visiting is a reference to a blank page. Whatever a visit is required to do is currently spread across the javadocs of UIComponent.visitTree, UIData.visitTree, VisitContext and VisitHint, with nothing at the address the spec gives.
Two independent problems, best fixed separately.
The dangling reference
The spec prose points at a page that has never existed. Rather than writing a package-info.java to justify a sentence written in 2009, point the prose at UIComponent.visitTree and VisitContext, where the normative text already lives.
A package-info.java for jakarta.faces.component.visit remains defensible on its own merits — the VisitContext / VisitCallback / VisitHint / VisitResult interplay has no single home — but that is a documentation improvement, not the fix for the broken reference.
Iterating is observable, and nothing says so
A component which visits its children more than once — UIData and UIRepeat set a row index per row — does so observably: the visited components see the row index change and may act on it, including by loading the data for that row.
Nothing anywhere states this. VisitHint.SKIP_ITERATION's javadoc describes only the mechanism:
Hint that indicates that components that normally visit children multiple times (eg. UIData) in an iterative fashion should instead visit each child only one time.
— and says nothing about why a caller would want it. UIData.visitTree's normative text simply says "Iterate over the rows" without mentioning the hint at all. So the obligation runs the wrong way: the only normative text says iterate, and opting out is left entirely to a caller's discretion.
The statement belongs in VisitHint.SKIP_ITERATION's javadoc, accompanied by guidance rather than a requirement: pass it when the traversal only needs to locate or inspect components; omit it when the traversal must act per row, as decode, validate, update and render do.
Motivating case
eclipse-ee4j/mojarra#5864: an internal traversal which existed only to locate components by client id lost SKIP_ITERATION, so it iterated every UIData on the way. PrimeFaces DataTable treats row iteration as its cue to load, so every postback rendering a lazily loaded table ran its backing query twice.
Both implementations had honoured this for years — PrimeFaces asserts an exact load() count against Mojarra and MyFaces alike — but nothing said they had to, so nothing caught it going wrong.
🤖 Generated with Claude Code (Opus 4.8)
Describe the bug
UserInterfaceComponentModel.adoc:388-395, specifyingUIComponent.visitTree()(spec $3.1.8):There is no such package description.
api/src/main/java/jakarta/faces/component/visit/holds nopackage-info.java— the only one in the whole API isjakarta.faces.component.html— and the generated javadoc's package summary for it carries no description section at all.So the normative specification for tree visiting is a reference to a blank page. Whatever a visit is required to do is currently spread across the javadocs of
UIComponent.visitTree,UIData.visitTree,VisitContextandVisitHint, with nothing at the address the spec gives.Two independent problems, best fixed separately.
The dangling reference
The spec prose points at a page that has never existed. Rather than writing a
package-info.javato justify a sentence written in 2009, point the prose atUIComponent.visitTreeandVisitContext, where the normative text already lives.A
package-info.javaforjakarta.faces.component.visitremains defensible on its own merits — theVisitContext/VisitCallback/VisitHint/VisitResultinterplay has no single home — but that is a documentation improvement, not the fix for the broken reference.Iterating is observable, and nothing says so
A component which visits its children more than once —
UIDataandUIRepeatset a row index per row — does so observably: the visited components see the row index change and may act on it, including by loading the data for that row.Nothing anywhere states this.
VisitHint.SKIP_ITERATION's javadoc describes only the mechanism:— and says nothing about why a caller would want it.
UIData.visitTree's normative text simply says "Iterate over the rows" without mentioning the hint at all. So the obligation runs the wrong way: the only normative text says iterate, and opting out is left entirely to a caller's discretion.The statement belongs in
VisitHint.SKIP_ITERATION's javadoc, accompanied by guidance rather than a requirement: pass it when the traversal only needs to locate or inspect components; omit it when the traversal must act per row, as decode, validate, update and render do.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.Both implementations had honoured this for years — PrimeFaces asserts an exact
load()count against Mojarra and MyFaces alike — but nothing said they had to, so nothing caught it going wrong.🤖 Generated with Claude Code (Opus 4.8)