Ajax

The short examples further down (groups, resetValues, h:commandScript, the listener traces and the programmatic behaviour) share one view-scoped bean, jsBean, so that each page stays a few lines. It is scaffolding for the experiments, not a Bookshelf class:

Source: Jakarta Faces 4.1 API: AjaxBehaviorEvent

f:ajax with no event uses the default of the component it is nested in: action for an ActionSource such as a button or a link, valueChange for an EditableValueHolder such as an input (the tutorial). The names are logical, and each component maps them to a DOM event. What the two implementations rendered for the standard components:

Only the browser’s own events are possible beyond the logical ones, and each component accepts a fixed list. getEventNames() of ClientBehaviorHolder returns it. An unsupported name fails when the view is built, not when the user acts: with event="onkeyup" on an h:inputText, Mojarra answered with a 500 whose title read 'onkeyup' is not a supported event for HtmlInputText and listed blur, change, click, dblclick, focus, keydown, keypress, keyup, mousedown, mousemove, mouseout, mouseover, mouseup, select, valueChange, and MyFaces answered 500 with it is not a valid eventName defined for this component. The on prefix is the usual mistake.

The standard components that implement ClientBehaviorHolder (the API documentation lists them) include the input, select and command components, h:form, h:body, h:outputLabel, h:outputLink, h:link, h:button, h:graphicImage, h:panelGrid, h:panelGroup, h:dataTable, h:inputFile and UIWebsocket (the component behind f:websocket, which accepts a nested f:ajax). h:outputText is not one; to make a piece of text clickable, wrap it in an h:panelGroup with event="click":

Source: Jakarta Faces 4.1 API: ClientBehaviorHolder and Jakarta EE Tutorial: Using the event Attribute

The specification defines four keywords for both attributes. They are resolved in the browser: the handler that the server renders still contains the keyword, and faces.ajax.request replaces it with client ids before it sends the request.

The search expression framework of Faces 2.3 adds more (@parent, @namingcontainer, @next, @previous, @child(n), @id(...), custom keywords), and the page on search expressions covers all of them and SearchExpressionHandler. The VDL documentation of f:ajax says the values are search expressions, so any of them is valid here.

Two things happen between the tag and the wire. At render time the tag handler resolves relative and absolute ids to client ids: in the review form, render="@form :messages" was rendered as mojarra.ab(this,event,'action','@form','@form messages') and myfaces.ab(this,event,'action','@form','@form messages',{}), so :messages (absolute, from the view root) became the client id messages of a component outside the form. And when the user clicks, faces.ajax.request resolves the keywords: a button with execute="@form" in a form with the id f sent jakarta.faces.partial.execute=f:boom f on Mojarra and f f:boom on MyFaces, the source’s id and the form’s id. So the source is part of the execute list even when the page names other components (Mojarra sent f:btn f:name for execute: 'f:name', MyFaces f:name f:btn).

That last fact matters for tests written by hand. A request posted with curl whose partial.execute omits the source button was processed by Mojarra without ever invoking the button’s f:ajax listener (the phase trace showed exec=[f:title] and no listener call), while MyFaces invoked it anyway. A raw request that sends the keyword itself (jakarta.faces.partial.execute=@form) fared no better: neither implementation expanded it on the server, so Mojarra processed nothing at all (no setter ran, no message, no error) and MyFaces ran the button’s action without the inputs (the action failed on the null rating). Copy what the browser sends.

The review form of Bookshelf shows a preview as the user fills in the rating. The rating input executes both inputs (they belong together), runs the listener and re-renders the preview and the two field messages. A final button submits the whole form and renders the messages that live outside it.

A change request with reviewer=Ann and rating=4 answered with an update for review:summary containing Ann gives 4 stars and empty updates for the two messages; the phase listener trace showed the request going through all six phases with ajax=true, exec=[review:reviewer, review:rating] and render=[review:summary, review:reviewerMsg, review:ratingMsg]. With rating=9 the response carried the range message in review:ratingMsg, an empty review:summary, and the listener was not called (see The listener and the AjaxBehaviorEvent). The Send button re-renders @form and the absolute :messages, which is why the saved-message appears even though the h:messages component is not inside the form. If :messages were left out of render, the message would be added to the FacesContext of that request, never sent to the browser and lost with the request, which is the most common "my Ajax action does nothing" report.

Source: Jakarta EE Tutorial: Using the execute Attribute and Jakarta EE Tutorial: Receiving an Ajax Response

Both attributes accept a value expression that evaluates to a Collection<String>, for ids that are decided at run time. With a bean method getIds() returning List.of("a", "b"), the markup

was rendered with the handler onblur="mojarra.ab(this,event,'blur','f:a f:b','f:a f:b')" (and the MyFaces equivalent): the collection was evaluated and resolved to client ids when the page was rendered. The expression is therefore evaluated during Render Response of the page that contains the tag, not when the user acts. A literal value is split on spaces.

Source: Jakarta Faces 4.1 VDL: f:ajax and Jakarta EE Tutorial: Using the f:ajax Tag

A component can be updated only if its element exists in the page. The browser replaces the contents of the element whose id matches the update. A component with rendered="false" produces no element, and a later request cannot add it:

Rendering ghost, whose element was absent at the first render, failed on Mojarra with the client error malformedXML and the description During update: f:ghost not found, and the updates after it in the response were not applied (the wrapper stayed empty). MyFaces skipped the unknown element silently and rendered wrapper with its inner text. The portable form is the second one: always render an element that is always in the page (wrapper) and let the conditional content live inside it. The same holds for tables and repeated rows; render the table, not a row that may not exist.

A rendered condition is evaluated on every request, so a component can switch from hidden to visible within the wrapper. Do not render h:head, h:body and the form element casually either: @all is the supported way to replace the document.

Source: Jakarta EE Tutorial: Receiving an Ajax Response and Jakarta Faces 4.1 JavaScript documentation: faces.ajax

The VDL documentation says the method takes an AjaxBehaviorEvent. A method without parameters also worked on Mojarra (listener="#{jsBean.noArg}" ran) and failed on MyFaces with MethodNotFoundException: Method not found: …​JsBean@74b45567.noArg(jakarta.faces.event.AjaxBehaviorEvent) in the partial response. Declare the parameter, even if the method does not use it.

The event gives the source component (event.getComponent()) and the behaviour (event.getBehavior()); the request parameters and the FacesContext are available in the usual way. The listener is the place to change model state and to queue messages, and, via PartialViewContext (Ajax from Java: PartialViewContext and AjaxBehavior), to add render targets that the page did not name.

Source: Jakarta EE Tutorial: Using the listener Attribute and Jakarta Faces 4.1 API: AjaxBehaviorListener

The classic Ajax recipe is a pair of menus, where the second one depends on the first. The author menu executes only itself (default execute="@this"), so the dependent required menu is not validated while the user is still choosing, and renders the book menu:

The year and copies properties are used by the resetValues page below. Choosing William Gibson in a browser changed the book menu to -- book --, Neuromancer, Count Zero. The getBooks() getter is called while the menu is rendered, after the model update of the author, so it sees the new author. That works because the getter is a plain, cheap derivation; a getter that queries a database must be backed by a cached field.

Source: Jakarta EE Tutorial: Sending an Ajax Request

The specification requires every Ajax request to go through a client-side queue so that requests are sent in the order they were initiated: the oldest waiting request is sent next; when it completes (success or error) it leaves the queue, and the next one is sent. The page below has three buttons whose listener sleeps 400 milliseconds on the server and records which button called it; onevent records when the client saw each stage (times are milliseconds since the first click):

Clicking A, B and A immediately one after the other produced, on both implementations (Mojarra shown):

Source: Jakarta Faces 4.1 specification, 13.3.2 Ajax Request Queueing

The begin event of a queued request fires when it leaves the queue and is sent, not when the user clicked, and the three requests ran strictly one after the other, in order, on the server as well. The consequence is useful and dangerous: a double click on a submit button sends two requests (the second after the first finished), so the action runs twice. The queue guarantees order, not idempotence: make the action idempotent, hide or disable the trigger in the begin handler (Events on the Client: onevent and addOnEvent), or use delay.

delay="500" (or {delay: 500} in the JavaScript API) discards a request if another call to faces.ajax.request arrives within that many milliseconds; only the last call is sent. This debounces keystrokes. Three clicks on a button with delay="500" produced one request, whose begin came about 500 ms after the first click:

Source: Jakarta Faces 4.1 VDL: f:ajax

The literal none, or no delay, turns it off. The live search of the first example uses it so that fast typing sends one request per pause rather than one per key.

disabled="true" (or an expression) keeps the behaviour from being rendered. It is the tag-level switch for "Ajax only in some cases": a component whose f:ajax is disabled is rendered without the handler. A disabled f:ajax inside a group had different effects on the two implementations; see Grouping Components.

Source: Jakarta Faces 4.1 specification, 13.3.2 Ajax Request Queueing and Jakarta Faces 4.1 JavaScript documentation: faces.ajax.request

The script is the resource faces.js in the library jakarta.faces (ResourceHandler.FACES_SCRIPT_RESOURCE_NAME and FACES_SCRIPT_LIBRARY_NAME). It is added automatically when the page contains an f:ajax or an h:commandScript, so the usual pages do nothing. You must add it yourself in three situations, with h:outputScript:

The old names do not exist any more. Requesting jsf.js from jakarta.faces.resource/ and javax.faces.resource/jsf.js returned 404 on both implementations, and window.jsf is undefined; ResourceHandler.JSF_SCRIPT_LIBRARY_NAME and JSF_SCRIPT_RESOURCE_NAME are deprecated for removal in the API documentation.

Source: Jakarta EE Tutorial: Loading JavaScript as a Resource and Jakarta Faces 4.1 specification, 13.1 JavaScript Resource

faces.ajax.request(source, event, options) sends the request:

The default execute is @this, the default render is @none. The request is always a POST to the form’s action URL (or to the hidden jakarta.faces.encodedURL field’s value, if present); the header is Faces-Request: partial/ajax; the parameters sent are jakarta.faces.ViewState, jakarta.faces.partial.ajax=true, jakarta.faces.source and, when the view uses the client window, jakarta.faces.ClientWindow; plus the execute and render lists, resetValues, and the extra parameters. The JavaScript documentation adds that a form with enctype="multipart/form-data" is sent through a hidden inline frame instead of XMLHttpRequest with the same parameters, and that the begin, complete and success events are emulated for it (this was not run on this scratch application).

From a browser, that request carried (Mojarra):

The return false keeps the button from also submitting the form normally. Two calls within delay milliseconds sent only the second, with its own options, on both implementations. Ids in the options are client ids of the rendered page (f:name, because the form is a naming container), written out in full; the keywords work too. The f:ajax tag generates calls like this one: Mojarra writes mojarra.ab(this,event,'action','@form','f:out',{...}) and MyFaces myfaces.ab(this,event,'action','@form','f:out',{}), thin wrappers of faces.ajax.request that are implementation internals and must not be called by application code.

Source: Jakarta Faces 4.1 JavaScript documentation: faces.ajax and Jakarta EE Tutorial: Using JavaScript API in a Facelets Application

Source: Jakarta Faces 4.1 JavaScript documentation: faces and Jakarta Faces 4.1 JavaScript documentation: faces.util

h:commandScript is the component for "call the server from a script". It renders a JavaScript function with the given name; calling the function (with an optional object of extra parameters) sends an Ajax request that behaves like a command button’s: the action and actionListener of the component run, and execute and render apply. The attributes (VDL documentation): name (required), autorun, action, actionListener, execute, render, resetValues, onevent, onerror, immediate, rendered, binding and id. It is a command component; it is not among the ClientBehaviorHolder implementations that the API documentation lists, so there is no f:ajax to nest in it, and its own execute, render and onevent attributes do that job.

Calling refreshReviews({tag: 'A'}) and bookshelf.refreshStock({tag: 'B'}) from the console updated out to refreshed:start:A and refreshed:start:B on both implementations. A name without a period is declared with var; a namespaced name is assigned (bookshelf.refreshStock = function...), so on Mojarra the namespace object must already exist (MyFaces rendered a myfaces.reserveNamespace('bookshelf.refreshStock') call before the assignment). The function takes extra parameters from an object argument.

Two quirks were observed. MyFaces escaped an underscore in the name (name="bookshelf_refresh" became the function bookshelf_5Frefresh), so calls to the name you wrote failed; use names without underscores. With autorun="true", the function is called when the page has loaded; on Mojarra the load event object is passed as the parameter object, so the request also carried isTrusted=true, a harmless extra parameter. autorun is a one-shot at load. Polling is better done with setInterval calling the function, or with the WebSocket push page for server-initiated updates.

Source: Jakarta Faces 4.1 VDL: h:commandScript and Jakarta EE Tutorial: Using Ajax with Facelets

FacesContext.getPartialViewContext() gives the object. Its methods (API documentation): isAjaxRequest(), isPartialRequest(), isExecuteAll(), isRenderAll(), getExecuteIds(), getRenderIds() (a mutable Collection), getEvalScripts() (a mutable List), getPartialResponseWriter(), processPartial(PhaseId) and isResetValues(). The two mutable collections let a listener change what the response contains. The listener below saved a title, added a panel outside the form to the render list and asked the browser to run a script:

Source: Jakarta Faces 4.1 API: PartialViewContext

The page asked only for out. The response contained updates for f:out and stats and an <eval>document.getElementById('stats').dataset.saved = 'yes';</eval>; in the browser, stats read saved=1 and had data-saved="yes" on both implementations. (The order of eval and the view state element differs: Mojarra writes eval after the view state, MyFaces before.) The id added to the render list is a client id. Never build a script for getEvalScripts() from user input: it is executed in the page, so a title concatenated into it is cross-site scripting.

How does the server process only the components in the execute list and write only those in the render list? The specification calls it partial view traversal (section 13.4) and deliberately does not prescribe a strategy: it requires only that UIViewRoot.processDecodes, processValidators and processUpdates call PartialViewContext.processPartial(PhaseId) when the request is a partial one, and that the encoding of an Ajax request goes through the same method. processPartial works on the client ids in getExecuteIds() (for the three execute phases) and getRenderIds() (for Render Response); both collections are filled from the request parameters jakarta.faces.partial.execute and jakarta.faces.partial.render, which faces.js fills with the client ids that the search expressions resolved to (see execute and render). The API for such a walk is UIComponent.visitTree: it takes a VisitContext that carries the ids and a set of VisitHint values, and a callback that is called for every component the visit reaches, which is how a partial phase can run on selected components only. The hints are: VisitHint.EXECUTE_LIFECYCLE says that the visit is part of the execution of a lifecycle phase, SKIP_UNRENDERED visits only the rendered subtrees, SKIP_ITERATION asks components that normally visit their children several times (the iterating ones, such as UIData) to visit them once, and SKIP_TRANSIENT visits only non-transient subtrees. The VisitContext used for a partial request is an implementation class (PartialVisitContext in Mojarra’s com.sun.faces.component.visit and in MyFaces' org.apache.myfaces.component.visit, not part of the API); application code obtains one from VisitContext.createVisitContext(FacesContext, Collection<String> ids, Set<VisitHint> hints) and never names it.

The two shortcuts skip the id-based visit. @all in execute makes isExecuteAll() true and in render makes isRenderAll() true: the first runs the normal full-tree phases and the second renders the whole view, as the update of a single element jakarta.faces.ViewRoot in the response. @none contributes no id, so the visit has nothing to reach; with execute="@none" not even the f:ajax listener ran on Mojarra.

The probe below replays a request’s render ids through the same API an implementation uses. The listener builds a VisitContext from getRenderIds() and visits the view, collecting what a render of those ids would reach:

Hand-made Ajax POSTs (with curl, sending the ids that faces.js would send, such as execute=f for @form) produced the following in found:

So code that reads the id collections must not assume what is in them: after @all the collections hold the keyword on Mojarra and nothing or the view root on MyFaces, the source component may or may not be in execute, and the visit reaches only components that exist and are rendered (a component inside a rendered="false" parent is skipped by SKIP_UNRENDERED). Use isExecuteAll() and isRenderAll() for the whole-view cases. Visiting the tree yourself is the right tool for tooling and diagnostics; to change what an Ajax request renders, add ids to getRenderIds() as the previous section did.

Source: Jakarta Faces 4.1 specification, 13.4 Partial View Traversal, VisitContext API, VisitHint API and PartialViewContext API

To do the same for every Ajax request, decorate the factory: PartialViewContextFactory and PartialViewContextWrapper are the extension points (registered in faces-config.xml). The wrapper below always adds the messages component to the render list, so a page cannot forget it:

Source: Jakarta Faces 4.1 API: PartialViewContextFactory and Jakarta Faces 4.1 API: PartialViewContextWrapper

A page whose button used render="reviewer" only still received <update id="messages"> with Review 1 saved, on both implementations. The component with the id messages must exist in every page that uses the factory (here the id is a client id of a component outside any form); if one lacks it, Mojarra reports a malformedXML error to the client (What Can Be Rendered).

f:ajax is a tag handler around AjaxBehavior. Code can attach the same behaviour, using the id AjaxBehavior.BEHAVIOR_ID and ClientBehaviorHolder.addClientBehavior. A system event listener does it when a component enters the view, and the guard keeps a postback (when the event is published again) from adding it twice:

The input rendered onkeyup="mojarra.ab(this,event,'keyup','@this','f:echo',{'delay':'200'})" on Mojarra and onkeyup="myfaces.ab(this,event,'keyup','f:q','f:echo',{'delay':'200'})" on MyFaces, and typing in a browser updated echo (abc, then abcd) on both. Without the h:outputScript, Mojarra did not load faces.js and the handler failed (Getting faces.js onto the Page). AjaxBehavior has setExecute, setRender, setOnevent, setOnerror, setDelay, setResetValues, setDisabled, setImmediate and addAjaxBehaviorListener, one for each tag attribute. PartialResponseWriter is for the rarer case of a component or a handler that writes its own partial response (startDocument, startUpdate(id), endUpdate(), delete(id), redirect(url), startEval(), startError(name) and so on); the specification asks implementations to use it so that nested CDATA sections are escaped correctly. A custom renderer needs none of this: it is rendered by the normal update machinery.

Source: Jakarta Faces 4.1 API: PartialViewContext and Jakarta Faces 4.1 API: AjaxBehavior