Extending Faces: Wrappers, Factories and Listeners

The table lists what a project can replace or observe, the base class or interface to extend, the element of faces-config.xml that registers it, and where this section treats it. A *Wrapper class implements the whole type by delegating to the wrapped instance, so a subclass overrides only what it changes.

Source: Jakarta Faces 4.1 specification, 11.3.7 Delegating Implementation Support and 11.3.6 Configuration Impact on Jakarta Faces Runtime

Section 11.3.7 of the specification requires the runtime to support decoration for every artifact that has a wrapper class. The list names about three dozen types, from Application and ViewHandler to VisitContext and ViewDeclarationLanguage, and says "among others". The mechanism has three parts.

Three consequences follow, and all three were observed on Mojarra and on MyFaces.

Wrappers also work in code, outside the registration mechanism: new ResourceWrapper(resource) in a handler, or the FacesContextWrapper created by a factory in the architecture page, is the same decorator used by hand.

The first complete example is the one the specification itself uses: a ViewHandler that changes how the locale is calculated and delegates everything else.

The ViewHandler is the application’s object for everything about a view that is not the view’s content: it derives the view id from the request path (deriveViewId), restores or creates the view (restoreView, createView), renders it (renderView), builds the URLs of actions, redirects, bookmarks, resources and WebSocket channels (getActionURL, getRedirectURL, getBookmarkableURL, getResourceURL, getWebsocketURL), answers which view declaration language handles a view (getViewDeclarationLanguage), manages the protected views (addProtectedView, getProtectedViewsUnmodifiable, removeProtectedView), and calculates the locale, character encoding and render kit id (calculateLocale, calculateCharacterEncoding, calculateRenderKitId). ViewHandlerWrapper (since Faces 1.2) delegates all of them.

The Bookshelf catalogue is offered in English and Spanish. The handler below lets a lang request parameter choose the locale, remembers the choice in the session, and otherwise leaves the decision to the wrapped handler. The parameter is checked against the locales that the application declares as supported, so an arbitrary value never reaches the session.

It is registered in WEB-INF/faces-config.xml, next to the locales it validates against:

The page that shows the result prints #{facesContext.viewRoot.locale}. The runs below used curl-style requests with a cookie jar: a GET with ?lang=es and then a POST of the form without the parameter.

The same outcome on Mojarra and on MyFaces. Three details matter when you write a ViewHandler decorator.

The wrapper is the right tool for the cases the ViewHandler was designed for: a different way to compute the locale, a different URL scheme (getActionURL, getBookmarkableURL), a global pre- or post-processing of rendering (renderView), extra protected views. It is not the place for per-request business logic, and it must be thread-safe: one instance serves every request.

Source: API: ViewHandlerWrapper, ViewHandler and specification 11.3.7, the YourViewHandler example

The ResourceHandler finds the files of the resources directory (and of META-INF/resources in JARs), answers requests to /jakarta.faces.resource/*, and tracks which scripts and stylesheets a page already rendered. Its methods fall into three groups, and ResourceHandlerWrapper delegates all of them:

A decorator that changes what is served overrides the createResource methods and returns a different, or a wrapped, Resource. ResourceWrapper is the matching wrapper for the Resource object, with getInputStream(), getURL(), getResponseHeaders(), getRequestPath(), getContentType(), getLibraryName(), getResourceName() and userAgentNeedsUpdate. The Bookshelf example adds a cache header to the files of its own library bookshelf and leaves all other resources alone:

With bookshelf/site.css and other/other.css in the resources directory, the stylesheet link in the page is /bookshelf/jakarta.faces.resource/site.css.xhtml?ln=bookshelf (the .xhtml suffix comes from the extension mapping of the FacesServlet), and the responses were:

The header of the decorated resource replaced the implementation’s default on both, and the missing resource still produced a 404 because the decorator returns null unchanged. Three rules keep a resource handler decorator correct:

The resource handling page covers the resource directories, libraries, versioning, the ResourceHandler constants and the jakarta.faces.RESOURCE_EXCLUDES parameter that decide what a request reaches.

Source: API: ResourceHandlerWrapper, ResourceWrapper and specification 11.3.7

The NavigationHandler turns the outcome of an action into a navigation. It has one working method, handleNavigation(context, fromAction, outcome), plus the overload with a toFlowDocumentId for flows. NavigationHandlerWrapper (since Faces 2.2) delegates both. The navigation page explains the algorithm and shows a logging decorator; this page shows the point that matters for extensions: there are two base classes, and they are not interchangeable.

ConfigurableNavigationHandler adds getNavigationCase, getNavigationCases and performNavigation, and Faces' own handler is of this type. Components that need to know the target of an outcome without navigating — h:link, h:button, and every UIOutcomeTarget component — call the configurable methods. A decorator that extends only NavigationHandlerWrapper is a plain NavigationHandler, so the object that Application.getNavigationHandler() returns is no longer configurable. The Bookshelf migration needs the old site’s outcomes (home, books) to keep working while the pages move to catalogue. This is the decorator written the safe way, with the configurable wrapper:

Both buttons action="home" and action="books" answered 302 with Location: /bookshelf/catalogue.xhtml on Mojarra and MyFaces. The plain-wrapper version of the same class (PlainLegacyNavigationHandler extends NavigationHandlerWrapper, constructor taking a NavigationHandler) navigated just as well for buttons, and showed the difference in the links:

On Mojarra the plain wrapper disabled even the link whose outcome was valid; MyFaces tolerated it. The portable rule is therefore: extend ConfigurableNavigationHandlerWrapper, whose constructor takes a ConfigurableNavigationHandler.

The decorator above changes the outcome only in handleNavigation, so the links did not benefit from the alias: the h:link outcome="home" of the same page stayed disabled with the alias handler on Mojarra (and was rendered as plain text without a target on MyFaces), because getNavigationCase still saw home. An alias that must also work for links would have to be applied in getNavigationCase as well (not run here). This is the typical trap of partial decoration: every method the other components call must agree.

Source: API: NavigationHandlerWrapper, ConfigurableNavigationHandlerWrapper and specification 11.3.7

Expression Language evaluates #{features.reviews} by asking a chain of jakarta.el.ELResolver objects, first for the top-level name features (with a null base) and then for the property reviews of whatever the first answer was. Faces builds the chain from the implicit objects, the CDI resolver and its own resolvers; an application adds its resolvers in faces-config.xml or in code, and they are consulted before the bean, list, map and array resolvers. The expression language page explains how the chain works and shows a resolver that exposes build information; this one exposes feature flags, to show what a resolver that handles two levels (the name and then the properties) looks like.

A flag bookshelf.feature.reviews is a system property (set with -Dbookshelf.feature.reviews=true or by the server configuration), and the page asks #{features.reviews}. The resolver reads only the flags it knows, never a property chosen by the page, so a view cannot turn an expression into a read of an arbitrary system property.

Started with -Dbookshelf.feature.reviews=true -Dbookshelf.feature.secret=true, the page rendered true for features.reviews and false for features.secret (set, but not on the whitelist) on Mojarra and on MyFaces. The page without the properties rendered false for both. Notes on writing resolvers:

Source: Jakarta Expression Language 6.0 API: ELResolver and Faces 4.1 specification, 5.6.2 Expression Language Resolution

A PhaseListener is called before and after each phase of the request processing lifecycle. It sees every Faces request, which makes it the right place for cross-cutting behaviour that depends on lifecycle position: timing, auditing, a request id, a per-request setup and clean-up. The interface has three methods: getPhaseId() (the phase it cares about, or PhaseId.ANY_PHASE), beforePhase(PhaseEvent) and afterPhase(PhaseEvent). The specification adds two rules that are easy to forget:

Listeners must be thread-safe: Faces creates one instance of a listener named in faces-config.xml and calls it from every request thread, so a per-request value cannot be a field. The request map is the place for it.

The example gives every Faces request an id. It generates a random UUID in beforePhase(RESTORE_VIEW) — the first moment of the lifecycle — stores it in the request map for the beans and logs, and sends it back in an X-Request-Id response header that a support person can ask the user for.

Every page, postback and redirect response of the example carried an X-Request-Id header (a GET, a POST that answered 200, and a POST that answered 302, on both implementations). The responses that ended in a server error did not: the container discarded the headers when it rendered its error page. As noted in the resource section, requests for resources did not carry it either, because they do not run the lifecycle.

A listener can be attached in four places, and the events and listeners page of this section shows the order in which they run when several are present:

Source: Faces 4.1 specification, 12.3 PhaseListener and API: PhaseListener

A SystemEventListener observes the events that the framework publishes about itself: the application starting (PostConstructApplicationEvent) or stopping (PreDestroyApplicationEvent), a component being added to the tree, a view about to render (PreRenderViewEvent), a validation about to run, and so on. The interface has two methods: isListenerForSource(Object), which says whether this listener wants the events of a given source object, and processEvent(SystemEvent). Listeners that run for every event of a type must therefore check the source cheaply.

The events and listeners page lists all events and their order. This page shows the extension side: how a listener is registered, and the pattern most libraries use, a listener for the application start that does the setup that needs code.

Registration has two forms. In faces-config.xml the system-event-listener element names the listener class, the event class (SystemEvent if omitted) and optionally the source class. In code, Application.subscribeToEvent(eventClass, listener) (or the overload with a source class) subscribes, and unsubscribeFromEvent removes it. The example uses both. ExtensionBootstrap is registered in XML for PostConstructApplicationEvent, with Application as source, and subscribes a second listener in code. The second one adds two defensive headers to each Faces page just before it renders:

At start-up both implementations logged SecurityHeadersListener subscribed for PostConstructApplicationEvent once, and each page response then carried X-Content-Type-Options: nosniff and Referrer-Policy: same-origin. The listener is a demonstration of the mechanism; headers that apply to every response of an application, not only to Faces views, belong in a servlet filter or in the server configuration, and the security page treats the headers a Faces application should send.

Notes that apply to all system event listeners:

Source: API: SystemEventListener, PostConstructApplicationEvent, PreRenderViewEvent and specification 11.3.6, the system-event-listener element

A factory creates the objects that Faces needs per request, per application or per view: the FacesContext, the ExternalContext, the PartialViewContext, the ExceptionHandler, the Flash, the Lifecycle, the RenderKit, the ClientWindow, the Application itself. FactoryFinder.getFactory(name) returns the factory registered under one of the FactoryFinder constants, and every factory type is decoratable in the same way as a handler: the extension class extends the factory, takes the previous factory in its constructor, and delegates to it. The usual shape is a factory that asks the wrapped factory for the object and wraps the result in a wrapper.

The Bookshelf example protects its redirects. Anything that calls ExternalContext.redirect(url) — an action that redirects to a returnTo address, the navigation handler for a faces-redirect=true outcome, a viewAction — goes through that method, so a decorator on the ExternalContext is a single place to refuse redirects that leave the application. A log line in redirect showed that both an action calling redirect directly and a navigation case with <redirect/> end there, on Mojarra and on MyFaces. The decorator allows relative paths and the https URLs of hosts listed in a context parameter, and rejects everything else, in particular absolute URLs to other hosts and the //host form that browsers read as a different host. The allow-list comes from web.xml, not from the code, and holds no secret.

Three buttons of the test page call an action that redirects. The results were the same on Mojarra and MyFaces:

The refused redirect surfaces as an exception, so the exception handling page applies to it: in production an error page, not the stack trace, is what the user should see. A redirect that is produced by user input (a returnTo parameter) should still be validated where it is read; the decorator is the second line of defence, not the first.

Factories can be registered in three ways, and the first two decorate in the same way:

The service-file route was tried with a second ExternalContextFactory in a JAR that had no faces-config.xml at all. Both implementations picked it up, and the decoration order was: the implementation’s factory, then the one from the service file, then SafeRedirectExternalContextFactory from faces-config.xml (that constructor received the service-file factory as the wrapped one). So the configuration file of the application is always the outermost.

Source: Faces 4.1 specification, 11.2.6.1 FactoryFinder, API: ExternalContextFactory, ExternalContextWrapper and FactoryFinder

Everything above is registered in an application configuration resource, a file in the faces-config.xml format. At start-up, before any request, the specification (11.3.2) has Faces build a list of resources in this way: if the context parameter jakarta.faces.CONFIG_FILES exists, its comma-separated, context-relative paths are the list and the search of META-INF is skipped; otherwise every META-INF/faces-config.xml and every file named *.faces-config.xml directly in META-INF (in the JARs of WEB-INF/lib) is added; and the documents supplied by the ServiceLoader service ApplicationConfigurationPopulator are added too (described below). The list is parsed before /WEB-INF/faces-config.xml, which is therefore always last. The order matters because a decorator wraps what was registered before it. The elements used on this page, all taken from the 4.1 schema (web-facesconfig_4_1.xsd), are:

Classes named in these elements need a public constructor of the right shape: no-argument for el-resolver, phase-listener and system-event-listener-class, and the specification says the same for the factories that only replace; one argument of the wrapped type for the decorators. Annotations do not replace these registrations: the annotations of the configuration (@FacesComponent, @FacesConverter, @FacesRenderer, @FacesBehavior and so on) cover components, converters, validators, behaviours and renderers, while handlers, resolvers, listeners and factories are registered only in XML, in service files (factories) or in code, or through the populator service of the next section. The project setup page of this section shows the layout of a project’s faces-config.xml.

Source: Faces 4.1 specification, 11.3.2 Application Startup Behavior, 11.3.6 Configuration Impact on Jakarta Faces Runtime and Jakarta EE Tutorial: Configuring Jakarta Faces Applications

When two libraries decorate the same artifact, the order decides which sees the call first. The specification (11.3.8) defines it. Each configuration resource can have a <name>, and a resource in WEB-INF/lib can declare <ordering> with <before> or <after> (a list of names, or <others/>). WEB-INF/faces-config.xml may instead declare <absolute-ordering>, which lists the other resources by name and overrides every relative ordering. The application’s own WEB-INF/faces-config.xml is always processed last, so its decorators are the outermost, and a decorator registered later wraps those registered earlier.

The experiment used two small JARs, each with a META-INF/faces-config.xml that registers one ViewHandler decorator that logs the class of the handler it wraps. The first JAR is named trace; the second, named audit, asks to be processed after it:

The trace JAR has the same shape with <name>trace</name>, no ordering and its own class. The calls to calculateLocale then travelled through the chain below. The application’s LocaleViewHandler is outermost, the audit JAR (processed after trace) is next, and the trace JAR is innermost, in front of the implementation’s own handler.

The log lines (class of the wrapped object on the right) were:

With <before> in place of <after> in the audit JAR, both implementations produced the order LocaleViewHandler, TraceViewHandler, AuditOrderViewHandler: the ordering elements work as specified on both. The two columns differ in where the implementation’s own CDI helper (ConversationAwareViewHandler) sits in the chain — between two of the application’s decorators on Mojarra, innermost on MyFaces — which is why a decorator must never assume a particular class below it.

Names must be unique: a duplicate <name> among the JARs is a deployment error, and circular <before>/<after> constraints also fail the deployment. Without any ordering element the relative order of the JARs is unspecified and may differ between implementations and between builds, so a library whose decorator has to be inside or outside another one should state it with <ordering>, and an application that needs a definite order of all libraries should use <absolute-ordering> in WEB-INF/faces-config.xml. An <absolute-ordering> that does not contain <others/> ignores every resource it does not list, including the extensions of unlisted libraries; that is rarely what is intended.

Source: Faces 4.1 specification, 11.3.8 Ordering of Artifacts

The specification fixes the contracts, and on the extension points of this page the two implementations agreed in every run. The differences are in the details around them.

The form of a POST also differs, which matters if a script drives the page: MyFaces expects the hidden f_SUBMIT field that its h:form renders, Mojarra does not. A request without it was treated as a non-postback by MyFaces and no action ran.

Source: Faces 4.1 specification, Appendix B Changes Between Releases and the "Since" and "Deprecated" notes of the API pages linked in the sections above

The JSF books consulted for this section treat extension points in two places: a discussion of the design patterns behind JSF (the decorator and observer patterns, in the book of Dudney and colleagues) and a chapter on the non-UI extension points — phase listeners, the view handler, the exception handler, EL resolvers, the factories and the decorator pattern (Burns and Schalk, appendix and later chapters) — with related material on extending the core classes (Mann), custom resource handlers (Leonard) and component resources (Jacobi and Fallows). The concepts hold; the details need correcting.