Composite Components

A composite component is any Facelets markup file that lives inside a resource library. If the file starRating.xhtml is in the library bookshelf, a page declares the namespace xmlns:bs="jakarta.faces.composite/bookshelf" and writes <bs:starRating .../>. The library name is whatever follows jakarta.faces.composite/, the tag name is the file name without the extension, and no tag library descriptor is needed. Inside the file two sections describe the component: cc:interface is the contract the page author sees, and cc:implementation is the markup that is built when the tag is used.

Faces offers three ways to package a reusable piece of a view. They differ in how much they build and how much Java they need:

The page on Facelets tag files and tag libraries and the page on custom components and renderers describe the other two; this page stays with composites. The architecture page explains the component tree they plug into (the component tree).

Source: Jakarta Faces 4.1 specification, 3.6.1.3 How does one make a composite component? and Jakarta EE Tutorial: Composite Components

The Bookshelf catalogue shows each book as a small card. The markup for one card is the same everywhere it appears, so it is a composite component. The file is src/main/webapp/resources/bookshelf/bookCard.xhtml:

A page uses it like any other component:

The CatalogueBean is the request-scoped bean of the data tables page, reduced to the one method this page needs; it uses the Book record and BookService introduced there (see the data used on that page):

Source: Jakarta EE Tutorial: Composite Components and Jakarta Faces 4.1 VDL: cc:attribute

The card in the repeat rendered, on Mojarra, as <article id="shelf:j_idt5:0:card" class="book-card"> for the first book, ...:1:card for the second and so on, and as <article id="shelf:plain" class="book-card"> for the card outside the repeat (MyFaces produced the same shape with j_id_7 in place of j_idt5). Because the composite is a naming container, its id is prefixed by the form and, inside ui:repeat, by the row index, exactly as for any other component.

The specification (sections 3.6.1.3 and 10.3.3.1) allows two ways to tell Facelets where composite components are.

The namespace form. A namespace that starts with jakarta.faces.composite/ is taken to mean "a composite library"; the rest of the string is the library name. The runtime looks for a resource library of that name, so the file is found at:

The library name must not contain a / or characters that are illegal in a library name. If it does, the specification says that in the Development project stage an informative message is placed in the page and logged, and in other stages it is only logged. Library versions and locale-specific variants follow the resource handling rules (a sibling page covers them); a composite is found the same way as any other resource.

The tag library form. A Facelets tag library descriptor may contain a composite-library-name element. The namespace in that same descriptor can then be any URI, which is useful for a stable, company-owned name that survives moving the files:

The descriptor is registered with the context parameter jakarta.faces.FACELETS_LIBRARIES (the page on tag files and tag libraries covers the other ways a descriptor is found):

Source: Jakarta Faces 4.1 specification, 10.3.3.1 Declaring a composite component library for use in a Facelet page and facelet-taglib 4.1 schema (composite-library-name)

Both forms worked on Mojarra and on MyFaces (the page rendered the same rating group with jakarta.faces.composite/bookshelf and with https://bookshelf.example.org/ui). The pre-Jakarta namespaces were still accepted by both: a page that declared xmlns:b="http://xmlns.jcp.org/jsf/composite/bookshelf" rendered the same component. Do not rely on that. The old namespaces are on the list of planned removals for Faces 5.0, and the page on Facelets and XHTML views has a script that migrates them (the old namespaces).

The non-normative walk-through in section 3.6.1.5 of the specification describes the sequence, and what I observed is consistent with it. When the view is built (in Restore View of a postback, and for an initial request just before it is rendered; see the lifecycle page):

The resulting part of the component tree for one composite tag is this (read from the Development-stage error page that Mojarra prints, which dumps the tree, and confirmed by the cc probe in The cc Implicit Object):

Source: Jakarta Faces 4.1 specification, 3.6 Composite User Interface Components and Jakarta Faces 4.1 API: Application.createComponent(FacesContext, Resource)

Where this sits in the request processing lifecycle follows from that: the composite is created while the view is built, so the cc:interface and the tag handlers in cc:implementation (c:if, ui:include, the static structure) are evaluated once per build. The expressions in attribute values are evaluated later, lazily, in the phase that needs them: #{cc.attrs.label} while rendering, #{reviewBean.rating} of an inner input while decoding, validating (Process Validations), updating the model (Update Model Values) and rendering. Inner components take part in the lifecycle exactly like components written directly in the page; the composite does not add a phase.

Inside a composite’s cc:implementation, cc is the current composite component: the UIComponent created for the tag. The specification (change C034, accepted from the JSF 2.0 change log) says that cc is the composite whose markup file contains the expression, relative to the composite markup page in which it appears. Outside a composite it is empty, which the expression language page noted as well. In Java the same object is returned by UIComponent.getCurrentCompositeComponent(FacesContext); the static helpers UIComponent.getCompositeComponentParent(UIComponent) (the nearest composite above a component) and UIComponent.isCompositeComponent(UIComponent) complement it.

The commonly used properties, read in a probe composite (the attribute behaviour in the right-hand column is the subject of the next section):

Source: Jakarta Faces 4.1 specification, 3.6.1.3 How does one make a composite component? and Jakarta Faces 4.1 API: UIComponent

Rendered (the same on Mojarra and MyFaces, ?n=5&d=Z appended for the third card in the second line):

A composite file has at most one cc:interface and at most one cc:implementation, in that order.

The inferred contract has a portability trap. A file that has only cc:implementation, with no cc:interface at all, was rejected by Mojarra 4.1.17 with /resources/bookshelf/noif.xhtml @2,22 <cc:implementation> Unable to find interface for implementation. and rendered by MyFaces 4.1.4. Always write the interface, even an empty one: <cc:interface/> followed by the implementation rendered on both.

Source: Jakarta Faces 4.1 VDL: cc:interface and Jakarta Faces 4.1 VDL: cc:implementation

cc:attribute declares an attribute that the page author may give to the tag. There can be zero or many in cc:interface. Their name is what the page author types; their other attributes are:

The VDL adds that cc:attribute may be nested in another cc:attribute to describe nested properties. It also lists properties that must not be exposed as attributes because the markup-to-property mapping cannot set them: binding, id, inView, parent, rendered, rendererType and transient.

The probe above shows how the attributes behave. The runs on both implementations agreed:

Source: Jakarta Faces 4.1 VDL: cc:attribute and Jakarta EE Tutorial: Attributes of a Composite Component

The review form of Bookshelf needs a way to pick a rating. A set of radio buttons inside a labelled group is accessible without any script, works with a keyboard, and has the right semantics for a screen reader, so the first version is a h:selectOneRadio inside a fieldset. Version 1 uses no Java at all:

The review page uses the component, attaches a range validator to the radio group inside it, and an Ajax update:

Source: Jakarta EE Tutorial: The compositecomponentexample Example Application and Jakarta Faces 4.1 VDL: cc:editableValueHolder

The bean already carries the Bean Validation constraints, the Integer-typed rating, difficulty and the rated method that later versions use. Driven with HTTP (each request is a postback of the view with the field values named below; both implementations gave the same outcome, apart from the message prefix noted in Mojarra and MyFaces Compared):

The Ajax row deserves a note. The render="summary" is evaluated where the f:ajax is written, which is the using page, so the id is resolved from the form and the HTML became mojarra.ab(this,event,'change','review:rating:stars','review:summary') (MyFaces: myfaces.ab('review:rating:stars:0',event,'change','review:rating:stars','review:summary',{})).

A page author using <bs:starRating> cannot name the radio group inside it: its client id is an implementation detail. Yet the author may want a validator, a converter, a listener, or Ajax on it. Faces solves this with attached objects and attached object targets: the composite author names an inner component in cc:interface, and the page author attaches the object to that name with the for attribute. When the tag has been processed, Faces moves each attached object onto the inner component.

Each of the four takes a required name, which the page author’s for refers to, and an optional targets, a space-separated list of ids relative to the composite. Without targets, name is also the id of the inner component. With targets, one name can address several inner components at once (the valueHolder documentation uses two inputs, userid and password, behind the name inputs). cc:clientBehavior adds event, the event name passed to the target’s addClientBehavior(), and default: if true, the page author may omit event on f:ajax, as action is the default event of a command link. The VDL notes that only the first default is used when several are declared.

The tags with a for attribute are listed in their VDL pages: all the converters and validators above, f:validator, f:converter, f:valueChangeListener, f:actionListener and f:setPropertyActionListener. f:ajax has no for; it attaches to the composite through cc:clientBehavior, and f:validateWholeBean has none either.

In the star rating, cc:editableValueHolder name="stars" is what allowed <f:validateLongRange for="stars" minimum="2"/> in the review page, and cc:clientBehavior name="change" event="change" targets="stars" default="true" is what allowed the bare <f:ajax render="summary"/>. A composite that exposes an action source follows below, in Method Attributes and Retargeting.

cc:valueHolder is the right tag when only a converter makes sense, as for an output-only amount. The composite below shows a number in an h:outputText and lets the page author choose how it is formatted:

Source: Jakarta Faces 4.1 VDL: cc:valueHolder and Jakarta Faces 4.1 VDL: f:convertNumber

The first amount rendered €3.50 and the second 3.5 on both implementations. The converters page of this section explains f:convertNumber itself (number conversion).

Three pitfalls of attached objects, all observed:

Source: Jakarta Faces 4.1 VDL: cc:clientBehavior and Jakarta Faces 4.1 VDL: cc:valueHolder

A button inside the composite should call whatever the page author passes as its action. cc:attribute with a method-signature declares such a method attribute, and the four names action, actionListener, validator and valueChangeListener are retargeted automatically (the VDL refers to retargetMethodExpressions()): the method expression the page author wrote is applied to the inner component named by targets, and the method-signature is derived, so any given value is ignored. Any other name with a method-signature just stores a MethodExpression in the component’s attributes for a backing component to call (see Backing Components).

targetAttributeName lets the public name differ from the inner property. The VDL gives the example of a "submit" and a "cancel" button, each retargeted to the action property of its own button. The Bookshelf review buttons do this:

ReviewAudit is a request-scoped bean that implements ActionListener; it is bound through binding and logs which button was used:

Source: Jakarta Faces 4.1 VDL: cc:attribute and Jakarta Faces 4.1 VDL: cc:actionSource

Posting the form (identical on both implementations):

The button ids come from the composite: save and cancel are inside the naming container buttons, so a script or a test posts review:buttons:save, not review:save.

Composites compose. The cc:implementation of one may use another, which makes it the using page for that other composite. For an attached object to reach through both levels, the specification requires that the name of the target, the for of the attached object and the id of the inner component match at every level of the nesting; it does not require support for renaming a target on the way up. Here a composite row adds a label to the star rating and passes the exposed target through:

The row’s id="stars" for the inner bs:starRating, the row’s own cc:editableValueHolder name="stars" and the star rating’s name="stars" all agree, so the page author’s <f:validateLongRange for="stars"/> travels two levels.

The second rule concerns naming containers inside the implementation. A composite is itself a naming container, so ids inside it do not clash with the page. But a h:form, a ui:repeat or another composite inside the implementation is a naming container too, and a target inside it must be named by a client id relative to the top-level component. The specification’s own example is targets="form:button". The Bookshelf quick-note composite wraps its own form:

Source: Jakarta Faces 4.1 VDL: cc:interface (nesting of composite components, naming containers within composite components)

Observed on Mojarra and MyFaces: with review:plot:stars:stars=1 the page showed Plot: Validation Error: Value is less than allowable minimum of '2' (the validator travelled through both composites), with =3 the review was saved, and the quick note with toolongvalue showed quick:note:text: Validation Error: Length is greater than allowable maximum of '5' while the listener bound to send ran. A target that is not a naming container failed differently: a first attempt that wrote targets="sub:button" for a button inside an h:panelGroup id="sub" (not a naming container, so the client id is just button) made Mojarra throw java.lang.IllegalArgumentException: sub while the view was built, whereas MyFaces rendered the page without complaint. Use h:form, ui:repeat or a composite, or drop the prefix.

The tag in the using page may contain content, and cc:implementation decides where it goes. The VDL defines four tags:

renderFacet writes the facet content in place; insertFacet hands it to an inner component that has its own facet slot for it, such as the footer of h:panelGrid or the header of h:dataTable. The Bookshelf panel uses all of them:

Source: Jakarta Faces 4.1 VDL: cc:insertChildren, cc:renderFacet and cc:insertFacet

The rendered body (Mojarra; MyFaces produced the same elements without the line breaks) was:

Details worth knowing, all from the runs (Mojarra and MyFaces unless said otherwise):

Most composites need no Java. When one does, for logic that depends on its own attributes, for a validator that must read them, or for a property the markup cannot compute, the composite gets a backing component: a Java class extending UINamingContainer (or any class that implements NamingContainer and is in the family jakarta.faces.NamingContainer), used as the composite root. Faces looks for it in this order, as the javadoc of Application.createComponent(FacesContext, Resource) states: the componentType on cc:interface; a script component; a class named after the library and file; the default UINamingContainer.

The explicit way registers the class with @FacesComponent and names it in cc:interface:

The 4.1 annotation has no other elements. The second way needs no annotation: a class named <library>.<file name> is found by name. A library bookshelf and a file conv.xhtml give a class bookshelf.conv; the class name is lower-case because the file name is, so this is an unusual style:

On both implementations a page with <bs:conv id="c"/> rendered created as bookshelf.conv. Prefer @FacesComponent with a componentType: it survives a rename of the file and uses ordinary Java names.

Source: Jakarta Faces 4.1 API: FacesComponent and Jakarta Faces 4.1 API: Application.createComponent(FacesContext, Resource)

Validation of a composite happens on its inner input components, with the standard rules of the validation page. The tutorial lists the validator tags that can be used with cc:valueHolder and cc:editableValueHolder: f:validateBean, f:validateRegex and f:validateRequired, and any other validator tag with a for attribute works the same way. Four layers were tested on the star rating, and they combine:

Messages need a place. The star rating shows its own <h:message for="stars"/> inside the composite, so every use of the component has the message next to it, and the page can additionally show h:messages. When both are present the same message appears twice, which was visible in the output (the inner message and the list). Choose one place. A page that wants the messages elsewhere can omit the inner h:message and use <h:messages for=...> or a message list, since the client id of the inner input is predictable (review:rating:stars). The messages page covers the rest, and the converters page the for attribute of f:convertNumber and friends, which attaches to a cc:valueHolder in the same way.

The immediate cancel button in reviewButtons is how a composite offers "leave without validating": the lifecycle page explains what an immediate command skips and why (the immediate attribute).

Source: Jakarta EE Tutorial: Validating Composite Component Values and Jakarta Faces 4.1 specification, 3.5.6 Bean Validation Integration

Two kinds of f:ajax meet a composite, and they resolve ids from different places.

The page on Ajax covers the attributes of f:ajax, the search expressions and the partial lifecycle in detail.

Source: Jakarta EE Tutorial: Using Ajax with Jakarta Faces Technology and Jakarta Faces 4.1 VDL: f:ajax

cc:extension is deprecated in Faces 4.1 without replacement and is planned for removal in Faces 5.0 (issue 1871 on the 5.0 plan). The VDL gives the reason: the JSR-276 metadata it was meant to carry went dormant, so the tag was never of use. A composite file that contains <cc:extension><meta-info/></cc:extension> loaded on both implementations; MyFaces 4.1.4 logged WARNING: The tag composite:extension is deprecated as of 4.1. and Mojarra 4.1.17 logged nothing about it. Delete the tag.

In the API, ActionSource2AttachedObjectTarget is marked @Deprecated(since = "4.1", forRemoval = true) with the advice to use ActionSourceAttachedObjectTarget instead (a class that exists since 4.1 and, according to its documentation, is the former class with the 2 dropped, because ActionSource2 itself is deprecated). The 4.1 change log lists "Unify ActionSource and ActionSource2" (issue 1832). Application code almost never uses these interfaces; they matter to tool and framework authors.

Source: Jakarta Faces 4.1 VDL: cc:extension and Jakarta Faces 4.1 API: ActionSource2AttachedObjectTarget

Everything else on this page behaved the same. The differences found:

The generated ids and the format of the error pages are implementation details, not contracts.

Source: Jakarta Faces 4.1 specification, Appendix B Change Log, Jakarta Faces 4.1 VDL: cc:extension and Jakarta Faces 5.0 (under development)

JavaServer Faces 2.0: The Complete Reference (Burns and Schalk) and the JSF 2.0 Cookbook (Leonard) cover composite components, including attribute and behaviour retargeting, backing components and Ajax-enabled composites, so the concepts on this page are the ones they introduce and the model has not changed. What has changed is the surface. Their examples use the javax.faces packages, the JSF 2.0 namespace http://java.sun.com/jsf/composite/<library>; and, where a bean is needed, @ManagedBean. Today the namespace is jakarta.faces.composite/<library>, the package is jakarta.faces, and the bean is a CDI @Named bean.

Facelets Essentials (Aranda and Wadia) predates composite components: its "composition components" and tag files are the Facelets 1.x ancestors, and the reusable-fragment techniques in the book (the ui:composition and ui:decorate family) are covered on the templating page. A composite component is the 2.0 successor, with real attributes, a client id and attached objects. Mastering JavaServer Faces (Dudney et al.) talks about the Composite design pattern, which describes the component tree (a component made of components), and is a different thing from the cc: feature of the specification. Both ideas meet in the composite component, but the book’s pattern chapter has no cc:interface. The JSP-based books (Mann, Dudney, Jacobi and Fallows) build reusable components as Java classes with JSP tag handlers, which Faces 4 no longer supports; the current replacement for the simple cases is a composite component, and for renderer-level control the custom component with a Facelets tag, on the page about custom components.