View Parameters and View Actions

View parameters and view actions are ordinary parts of the request processing lifecycle (see the six phases). The part that surprises people is the first one. On an initial (non-postback) request Faces normally skips straight to Render Response, because there is no submitted data to process. The Jakarta Faces specification (section 2.2.1, Restore View) makes one exception: if the view declares metadata with children (view parameters, view actions or f:event listeners), Faces builds a view that contains only the metadata, and the remaining phases run over it. Without metadata the request goes straight to Render Response.

The diagram is the route of the Bookshelf detail page developed below. Three consequences follow, and each is demonstrated in the sections of this page:

Source: Jakarta Faces 4.1 specification, 2.5.5 View Parameters and 2.2 Standard Request Processing Lifecycle Phases

Both tags are children of f:metadata, which must be a direct child of f:view (in a view without an explicit f:view the implicit one is enough) and must be in the page itself or in a template client, never in the template. The placement rules, the template slot that lets every page declare its own metadata, and the silent failure when the block sits in a template are explained in the core tags page; they are not repeated here. If a parameter or an action seems to be ignored, check that first. One portability rule matters when the page uses a template: the block must go in a slot that the template places directly inside its f:view (the ui:insert name="metadata" pattern of that page), not in the content slot. MyFaces 4.1.4 rejected an f:metadata placed inside the content ui:define of a template client with the error Parent UIComponent ... should be instance of UIViewRoot, while Mojarra 4.1.17 accepted it; the examples on this page are standalone views, where the problem does not arise.

The page below is the one the rest of this section dissects. A book is addressed by its ISBN, the parameter must be present and must have 13 digits, the book is loaded by a view action, an unknown ISBN produces a real 404 and a malformed address a real 400.

FacesContext and ExternalContext are injected with @Inject (supported since Faces 2.3). The two error pages are ordinary Servlet error pages declared in web.xml; they can be Facelets views:

(error/bad-request.xhtml has the same shape.) Requesting the page with curl -i gave the following, identically on Mojarra 4.1.17 and MyFaces 4.1.4:

The 404 page came back with status 404 and the Facelets content of not-found.xhtml, so a Faces view works as a Servlet error page (error pages in general: the exception handling page). The sections that follow explain each ingredient: f:viewParam, f:viewAction, Missing Entities: Sending a Real 404 and Malformed Addresses: a Real 400.

Source: Jakarta Faces 4.1 VDL: f:viewParam, VDL: f:viewAction and API: ExternalContext

f:viewParam creates a UIViewParameter in the view’s metadata. UIViewParameter extends UIInput, so everything a text field can have (a converter, validators, required, messages, value change listeners) is valid on it. What makes it different is where the value comes from: the request parameter whose name is given by name, on the query string of a GET or in the body of a POST. It is "bi-directional": it reads the parameter into the model on a request and writes the model value back into links when the page is rendered (Bookmarkable Links: h:link, h:button and includeViewParams).

f:viewAction creates a UIViewAction, a component that implements ActionSource. It is "a light-weight front-controller": a method that runs when a view is requested, with the view parameters already applied, and whose return value goes to the navigation system just like the outcome of a command button. It exists so that you do not need a preRenderView listener (View Action, preRenderView or @PostConstruct?) to initialise a page.

The command components submit forms. A bookmarkable link is a plain GET link whose address is computed when the page is rendered (the specification calls it preemptive navigation). h:link renders an a element and h:button a button that sets window.location. Both take an outcome, which is resolved with the navigation system, and parameters from nested f:param. The catalogue page links to the detail page:

The rendered markup, on both implementations:

(MyFaces adds ;jsessionid=... to the path when the first request has no session cookie.) Parameter values are URL-encoded: a f:param value a b&c rendered as isbn=a+b%26c, and the fragment attribute appends #top. An outcome that matches nothing (outcome="nosuchview") rendered no link: Mojarra, in every project stage except Production, printed the text with the message "This link is disabled because a navigation case could not be matched" and logged JSF1090, MyFaces printed the text only (see the project stage effects).

includeViewParams="true" adds the target view’s own view parameters to the link, using the values the current model holds. It removes the repetition of f:param for "stay on this page but change one thing" links. The detail page declares an isbn and a lang parameter, and links to itself:

For detail-links.xhtml?isbn=9780441013593&lang=en Mojarra rendered:

MyFaces produced the same parameters, with a different parameter order in some links. The rules from the specification: explicit f:param values win; a view parameter with a value expression contributes the value of that expression, converted back to a string with the converter’s getAsString, which is why the converter shown earlier has a real getAsString; a view parameter without a value expression contributes its local value (its own, or that of the same-named view parameter of the current view). Two related warnings:

Source: Jakarta Faces 4.1 VDL: h:link, VDL: h:button and Jakarta Faces 4.1 specification, 2.5.6 Bookmarkability

The rules for outcomes themselves (implicit navigation, navigation cases, faces-redirect) are the subject of the navigation page; its GET navigation section covers h:link and h:button from the navigation side.

A form that changes data should end with a redirect to a GET address, not render a page directly. If the POST renders the page, the browser’s address bar shows the form’s URL, reloading the page asks the user whether to resubmit the form (and, if the user agrees, saves the review twice), and the bookmarkable address of the result is lost. The standard fix is POST-Redirect-GET (PRG): the POST does its work, answers 302 with the address of the result, and the browser follows it with a GET. View parameters and view actions are what makes the GET half work.

The review form is a page of its own, addressed by the book it is about. It uses the portable view parameter described earlier (@ViewScoped bean, required only on the initial request):

Submitting the form answered 302 Location: /bookshelf/detail.xhtml?isbn=9780441013593 on both implementations. The following GET (with the same session cookie) showed the h:messages text "Thanks, your review was saved." above the book, and a second GET did not: the flash keeps the message for exactly one redirect. setKeepMessages(true) is the call that makes this work; without it the message is lost with the POST request. The URLEncoder.encode of the ISBN keeps an unexpected character from breaking the outcome.

What the redirect buys is visible when it is omitted. A variant whose action returned "detail?isbn=" + isbn (no faces-redirect) answered the POST with status 200 and rendered the detail view inside the POST response, but the title and author were empty: the view action and the view parameter of the target view do not run for a navigation inside a postback, so the book was never loaded. Do not forward to a view that depends on view parameters; redirect. The flash and the other PRG details (how long messages survive, flash scope beans) are the subject of the flash and PRG page.

Never build a redirect target from request data without checking it. A return value or a externalContext.redirect(url) whose URL comes from a parameter (?next=...) is an open redirect: restrict it to your own view ids, as the example does by fixing the path and encoding the single parameter.

Source: Jakarta Faces 4.1 API: Flash and Jakarta EE Tutorial: Introduction to Jakarta Faces Technology

A page for ?isbn=9780000000000 that renders an empty template with status 200 is a "soft 404": crawlers index it, monitoring sees healthy requests and users see a broken page. The view action is the right place to detect it, because it runs after the parameters are in the model and before anything is rendered. ExternalContext has two methods for it:

BookDetailBean.load() above uses the first and calls facesContext.responseComplete() immediately after it. The call is not optional:

So the lifecycle must be told that the response is finished. A real-world detail page with a database lookup does exactly this once.

The second option renders the Faces view with status 404 and so lets the page explain what happened and offer a way forward (a search box, a link to the catalogue) with the full template:

That variant answered status 404 with the page’s own content on both implementations. Choose by who reads the page: the container error page is simplest and consistent across the application; a status plus your own content is friendlier but must be written for each page. Either way the status is what a crawler and a monitoring system read.

Three cautions:

Source: Jakarta Faces 4.1 API: ExternalContext and Jakarta Servlet 6.1 specification, 9.5 Error Handling

A parameter that fails conversion or validation is a client error, but because the view action does not run for it, the lifecycle falls through to Render Response and the page is rendered with status 200 and, at best, a message. To answer with the right status, check FacesContext.isValidationFailed() where code still runs: a preRenderView listener, which belongs to Render Response and so runs even when phases 4 and 5 were skipped. BookDetailBean.rejectInvalid() above does it, and the table in A Complete Example: the Book Detail Page shows the result: 400 for a missing, empty or malformed ISBN on both implementations.

isValidationFailed() is true after any conversion or validation failure in the request, which on a page with only metadata means a view parameter. If the page also has a form, restrict the listener to the initial request with !facesContext.isPostback() or give it an if-like guard in code, otherwise a failed form validation would turn into a 400.

For pages where the user can fix the problem (a search page with a typed-in filter), do not send an error: render the page with the messages, and make sure the messages are readable (Messages). The decision is between "this address is wrong" (4xx) and "the input is wrong" (a form message).

The old-book.xhtml example in Navigation From a View Action is the whole technique: a view with a f:viewParam for the old parameter and a view action that returns the new address as an outcome, answered with a redirect. Typical uses are renamed pages, merged pages and addresses that carried an internal id before the application switched to ISBNs. The redirect is a temporary one (302 in the run); a permanent redirect (301) is a web server or filter concern. Remember the MyFaces session detail described in that section, and give the old view a trivial body: the user never sees it.

Read the parameter without view parameters. A CDI bean can inject the request parameter with @ManagedProperty (the Faces annotation, with @Inject) or the whole map with @RequestParameterMap:

mp.xhtml?isbn=9780441013593, a page with no metadata at all, printed isbn=9780441013593 title=Dune on both implementations, and @PostConstruct saw the parameter, unlike with f:viewParam. The price is that there is no conversion, no validation, no messages, no includeViewParams and no page metadata, so Faces does not run the lifecycle for the request (it goes straight to Render Response); use it for simple read-only pages, and keep f:viewParam where you need the features. Sending a 404 from @PostConstruct is awkward, because the bean is created in the middle of expression evaluation.

Source: Jakarta Faces 4.1 API: ManagedProperty and API: RequestParameterMap

OmniFaces. The OmniFaces library (see the OmniFaces page) has several tools in the same area. From its documentation (OmniFaces 5.5.5; the following was not run for this page):

The snippet combines the sendError example of the o:viewParamValidationFailed showcase page with the tags above; the tag also has sendRedirect and message attributes in the OmniFaces VDL. Declare the o prefix as in the OmniFaces documentation for your version.

Path-style addresses. f:viewParam reads request parameters only: /book/9780441013593 carries no parameter. Such addresses are usually produced with a URL-rewriting filter or a server rewrite rule in front of the FacesServlet; the extensionless mapping covered by the project setup page only removes the .xhtml suffix. OmniFaces @Param(pathIndex = ...) and FacesViews read path segments (its documentation); this page only used query parameters.

Source: OmniFaces showcase: @Param, viewParam, viewAction and viewParamValidationFailed

The examples of this page were run on both implementations in the same scratch application, except where the text names one. Differences found:

These are the findings of one run on one machine with one scratch application; the causes of the MyFaces differences were not investigated and some may be bugs rather than design. If portability matters, use a @ViewScoped bean, relax required on postbacks, always call responseComplete(), and create the session before redirecting from a view action.

Faces 5.0 is under development (milestone 5.0.0-M9 at the time of writing) and is not described here.

The books of the section’s bibliography that discuss view parameters and bookmarkable URLs (the JSF 2.0 books by Burns and Schalk and by Leonard) were written before Faces 2.2:

These points rest on the dates and scope of the books in the concept table of the section’s source specification; I did not re-read the books for this page.