Jakarta Faces

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of the copyright holders or the Eclipse Foundation may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Jakarta Faces 4.0 is based on the following Jakarta specifications:

Jakarta Servlet, version 6.0 https://jakarta.ee/specifications/servlet/

Jakarta Expression Language, version 5.0 https://jakarta.ee/specifications/expression-language/

Jakarta Contexts and Dependency Injection, version 4.0 https://jakarta.ee/specifications/cdi/

Jakarta Bean Validation, version 3.0 https://jakarta.ee/specifications/bean-validation/

Jakarta Tags, version 2.0 https://jakarta.ee/specifications/tags/

Jakarta WebSocket, version 2.0, optional https://jakarta.ee/specifications/websocket/

Jakarta JSON Processing, version 2.1, optional https://jakarta.ee/specifications/jsonp/

JavaBeans™ Specification, version 1.01 https://www.oracle.com/java/technologies/javase/javabeans-spec.html

Therefore, a Jakarta Faces container must support all of the above specifications. This requirement allows faces applications to be portable across a variety of Jakarta Faces implementations.

In addition, Jakarta Faces is designed to work synergistically with other web-related Java APIs, including:

Portlet Specification 1.0, JSR-168 https://jcp.org/en/jsr/detail?id=168

Portlet Specification 2.0, JSR-286 https://jcp.org/en/jsr/detail?id=286

Portlet Specification 3.0, JSR-362 https://jcp.org/en/jsr/detail?id=362

Portlet Bridge Specification, JSR-301 https://jcp.org/en/jsr/detail?id=301

The following documents and specifications of the World Wide Web Consortium will be of interest to Jakarta Faces implementors, as well as developers of applications and components based on Jakarta Faces.

Hypertext Markup Language (HTML), Living Standard https://html.spec.whatwg.org/

Extensible HyperText Markup Language (XHTML), version 1.0 https://www.w3.org/TR/xhtml1/

Extensible Markup Language (XML), version 1.0 (Second Edition) https://www.w3.org/TR/REC-xml/

The class and method Javadoc documentation for the classes and interfaces in jakarta.faces (and its subpackages) are incorporated by reference as requirements of this Specification.

The Facelet tag library for the HTML_BASIC standard RenderKit is specified in the VDLDocs and incorporated by reference in this Specification.

A page author is primarily responsible for creating the user interface of a web application. He or she must be familiar with the markup and scripting languages (such as HTML and JavaScript) that are understood by the target client devices, as well as the rendering technology (such as Facelets) used to create dynamic content. Page authors are often focused on graphical design and human factors engineering, and are generally not familiar with programming languages such as Java or Visual Basic (although many page authors will have a basic understanding of client side scripting languages such as JavaScript).

Page authors will generally assemble the content of the pages being created from libraries of prebuilt user interface components that are provided by component writers, tool providers, and Jakarta Faces implementors. The components themselves will be represented as configurable objects that utilize the dynamic markup capabilities of the underlying rendering technology. When Facelets are in use, for example, Jakarta Faces components will be represented as namespaced tags, which will support configuring the attributes of those components as tag attributes in the page. In addition, the pages produced by a page author will be used by the Jakarta Faces framework to create component tree hierarchies, called “views”, that represent the components on those pages.

Page authors will generally utilize development tools, such as HTML editors, that allow them to deal directly with the visual representation of the page being created. However, it is still feasible for a page author that is familiar with the underlying rendering technology to construct pages “by hand” using a text editor.

Component writers are responsible for creating libraries of reusable user interface objects. Such components support the following functionality:

As will be discussed in Rendering Model, the encoding and decoding functionality may optionally be delegated to one or more Render Kits, which are responsible for customizing these operations to the precise requirements of the client that is initiating a particular request (for example, adapting to the differences between JavaScript handling in different browsers, or variations in the WML markup supported by different wireless clients).

The component writer role is sometimes separate from other Jakarta Faces roles, but is often combined. For example, reusable components, component libraries, and render kits might be created by:

Within Jakarta Faces, user interface components are represented as Java classes that follow the design patterns outlined in the JavaBeans Specification. Therefore, new and existing tools that facilitate JavaBean development can be leveraged to create new Jakarta Faces components. In addition, the fundamental component APIs are simple enough for developers with basic Java programming skills to program by hand.

Application Developers are responsible for providing the server-side functionality of a web application that is not directly related to the user interface. This encompasses the following general areas of responsibility:

Only the latter responsibility is directly related to Jakarta Faces APIs. In particular, the following steps are required to fulfill this responsibility:

Application modules interact with Jakarta Faces through standard APIs, and can therefore be created using new and existing tools that facilitate general Java development. In addition, application modules can be written (either by hand, or by being generated) in conformance to an application framework created by a tool provider.

Tool providers, as their name implies, are responsible for creating tools that assist in the development of Jakarta Faces-based applications, rather than creating such applications directly. Jakarta Faces APIs support the creation of a rich variety of development tools, which can create applications that are portable across multiple Jakarta Faces implementations. Examples of possible tools include:

Tool providers will generally leverage the Jakarta Faces APIs for introspection of the features of component libraries and render kit frameworks, as well as the application portability implied by the use of standard APIs in the code generated for an application.

Finally, Jakarta Faces implementors will provide runtime environments that implement all of the requirements described in this specification. Typically, a Jakarta Faces implementor will be the provider of a Jakarta EE application server, although it is also possible to provide a Jakarta Faces implementation that is portable across Jakarta EE servers.

Advanced features of the Jakarta Faces APIs allow Jakarta Faces implementors, as well as application developers, to customize and extend the basic functionality of Jakarta Faces in a portable way. These features provide a rich environment for server vendors to compete on features and quality of service aspects of their implementations, while maximizing the portability of Jakarta Faces-based applications across different Jakarta Faces implementations.

This package contains top level classes for the Jakarta Faces API. The most important class in the package is FactoryFinder, which is the mechanism by which users can override many of the key pieces of the implementation with their own.

Please see FactoryFinder.

This package contains APIs that are used to link an application’s business logic objects to Jakarta Faces, as well as convenient pluggable mechanisms to manage the execution of an application that is based on Jakarta Faces. The main class in this package is Application.

Please see Application.

This package contains fundamental APIs for user interface components.

Please see User Interface Component Model.

This package contains concrete base classes for each valid combination of component + renderer.

This package contains classes and interfaces defining per-request state information. The main class in this package is FacesContext, which is the access point for all per-request information, as well as the gateway to several other helper classes.

Please see FacesContext.

This package contains classes and interfaces defining converters. The main class in this package is Converter.

Please see Conversion Model.

This package contains an interface for the Composite Component Attributes ELResolver.

Please see Composite Component Attributes ELResolver.

The runtime API for Faces Flows.

Please see FlowHandler.

This package contains classes and interfaces defining lifecycle management for the Jakarta Faces implementation. The main class in this package is Lifecycle. Lifecycle is the gateway to executing the request processing lifecycle.

Please see Request Processing Lifecycle.

This package contains interfaces describing events and event listeners, and concrete event implementation classes. All component-level events extend from FacesEvent and all component-level listeners extend from FacesListener.

Please see Event and Listener Model.

This package contains classes and interfaces defining the rendering model. The main class in this package is RenderKit. RenderKit maintains references to a collection of Renderer instances which provide rendering capability for a specific client device type.

Please see Rendering Model.

Interface defining the validator model, and concrete validator implementation classes.

Please see Validation Model

A standard Jakarta Servlet class required for integration of Jakarta Faces into web applications.

Please see Using Jakarta Faces in Web Applications.

An application that is processing a non-Faces request may use Jakarta Faces to render a Faces response to that request. In order to accomplish this, the application must perform the common activities that are described in the following sections:

The most common lifecycle will be the case where a previous Faces response includes user interface controls that will submit a subsequent request to this web application, utilizing a request URI that is mapped to the Jakarta Faces implementation’s controller, as described in Servlet Mapping. Because such a request will be initially handled by the Jakarta Faces implementation, the application need not take any special steps—its event listeners, validators, and application actions will be invoked at appropriate times as the standard request processing lifecycle, described in the following diagrams, is invoked.

The “Handle Resource Request” box, and its subsequent boxes, are explained in Resource Handling. The following diagram explains the “Execute and Render Lifecycle” box.

The behavior of the individual phases of the request processing lifecycle are described in individual subsections of Standard Request Processing Lifecycle Phases. Note that, at the conclusion of several phases of the request processing lifecycle, common event processing logic (as described in Common Event Processing) is performed to broadcast any FacesEvents generated by components in the component tree to interested event listeners.

Normally, a Jakarta Faces-based application will utilize the Render Response phase of the request processing lifecycle to actually create the response that is sent back to the client. In some circumstances, however, this behavior might not be desirable. For example:

In any of these scenarios, the application will have used the standard mechanisms of the Jakarta Servlet or Portlet API to create the response headers and content. It is then necessary to tell the Jakarta Faces implementation that the response has already been created, so that the Render Response phase of the request processing lifecycle should be skipped. This is accomplished by calling the responseComplete() method on the FacesContext instance for the current request, prior to returning from event handlers or application actions.

The Jakarta Faces implementation must perform the following tasks during the Restore View phase of the request processing lifecycle:

Obtain a reference to the FlowHandler from the Application. Call its clientWindowTransition() method. This ensures that navigation that happened as a result of the renderer for the jakarta.faces.OutcomeTarget component-family is correctly handled with respect to flows. For example, this enables <h:button> to work correctly with flows.

Using Application.publishEvent(), publish a PostAddToViewEvent with the created UIViewRoot as the event source.

In all cases, the implementation must ensure that the restored tree is traversed and the PostRestoreStateEvent is published for every node in the tree.

At the end of this phase, the viewRoot property of the FacesContext instance for the current request will reflect the saved configuration of the view generated by the previous Faces Response, or a new view returned by ViewHandler.createView() for the view identifier.

The purpose of the Apply Request Values phase of the request processing lifecycle is to give each component the opportunity to update its current state from the information included in the current request (parameters, headers, cookies, and so on). When the information from the current request has been examined to update the component’s current state, the component is said to have a “local value”.

During the Apply Request Values phase, the Jakarta Faces implementation must call the processDecodes() method of the UIViewRoot of the component tree. This will normally cause the processDecodes() method of each component in the tree to be called recursively, as described in the Javadocs for the UIComponent.processDecodes() method. The processDecodes() method must determine if the current request is a “partial request” by calling FacesContext.getCurrentInstance().getPartialViewContext().isPartialRequest() . If FacesContext.getCurrentInstance().getPartialViewContext().isPartialRequest() returns true, perform the sequence of steps as outlined in Apply Request Values Partial Processing. Details of the decoding process follow.

During the decoding of request values, some components perform special processing, including:

As described in Common Event Processing, the processDecodes() method on the UIViewRoot component at the root of the component tree will have caused any queued events to be broadcast to interested listeners.

At the end of this phase, all EditableValueHolder components in the component tree will have been updated with new submitted values included in this request (or enough data to reproduce incorrect input will have been stored, if there were conversion errors). In addition, conversion and validation will have been performed on EditableValueHolder components whose immediate property is set to true, as described in the UIInput Javadocs. Conversions and validations that failed will have caused messages to be enqueued via calls to the addMessage() method of the FacesContext instance for the current request, and the valid property on the corresponding component(s) will be set to false.

If any of the decode() methods that were invoked, or an event listener that processed a queued event, called responseComplete() on the FacesContext instance for the current request, clear the remaining events from the event queue and terminate lifecycle processing of the current request. If any of the decode() methods that were invoked, or an event listener that processed a queued event, called renderResponse() on the FacesContext instance for the current request, clear the remaining events from the event queue and transfer control to the Render Response phase of the request processing lifecycle. Otherwise, control must proceed to the Process Validations phase.

As part of the creation of the view for this request, zero or more Validator instances may have been registered for each component. In addition, component classes themselves may implement validation logic in their validate() methods.

During the Process Validations phase of the request processing lifecycle, the Jakarta Faces implementation must call the processValidators() method of the UIViewRoot of the tree. This will normally cause the processValidators() method of each component in the tree to be called recursively, as described in the API reference for the UIComponent.processValidators() method. The processValidators() method must determine if the current request is a “partial request” by calling FacesContext.getCurrentInstance().getPartialViewContext().isPartialRequest() . If FacesContext.getCurrentInstance().getPartialViewContext().isPartialRequest() returns true, perform the sequence of steps as outlined in Partial Validations Partial Processing. Note that EditableValueHolder components whose immediate property is set to true will have had their conversion and validation processing performed during Apply Request Values phase.

During the processing of validations, events may have been queued by the components and/or Validators whose validate() method was invoked. As described in Common Event Processing, the processValidators() method on the UIViewRoot component at the root of the component tree will have caused any queued events to be broadcast to interested listeners.

At the end of this phase, all conversions and configured validations will have been completed. Conversions and Validations that failed will have caused messages to be enqueued via calls to the addMessage() method of the FacesContext instance for the current request, and the valid property on the corresponding components will have been set to false.

If any of the validate() methods that were invoked, or an event listener that processed a queued event, called responseComplete() on the FacesContext instance for the current request, clear the remaining events from the event queue and terminate lifecycle processing of the current request. If any of the validate() methods that were invoked, or an event listener that processed a queued event, called renderResponse() on the FacesContext instance for the current request, clear the remaining events from the event queue and transfer control to the Render Response phase of the request processing lifecycle. Otherwise, control must proceed to the Update Model Values phase.

If this phase of the request processing lifecycle is reached, it is assumed that the incoming request is syntactically and semantically valid (according to the validations that were performed), that the local value of every component in the component tree has been updated, and that it is now appropriate to update the application’s model data in preparation for performing any application events that have been enqueued.

During the Update Model Values phase, the Jakarta Faces implementation must call the processUpdates() method of the UIViewRoot component of the tree. This will normally cause the processUpdates() method of each component in the tree to be called recursively, as described in the API reference for the UIComponent.processUpdates() method. The processUpdates() method must determine if the current request is a “partial request” by calling FacesContext.getCurrentInstance().getPartialViewContext().isPartialRequest() . If FacesContext.getCurrentInstance().getPartialViewContext().isPartialRequest() returns true, perform the sequence of steps as outlined in Update Model Values Partial Processing. The actual model update for a particular component is done in the updateModel() method for that component.

During the processing of model updates, events may have been queued by the components whose updateModel() method was invoked. As described in Common Event Processing, the processUpdates() method on the UIViewRoot component at the root of the component tree will have caused any queued events to be broadcast to interested listeners.

At the end of this phase, all appropriate model data objects will have had their values updated to match the local value of the corresponding component, and the component local values will have been cleared.

If any of the updateModel() methods that were invoked, or an event listener that processed a queued event, called responseComplete() on the FacesContext instance for the current request, clear the remaining events from the event queue and terminate lifecycle processing of the current request. If any of the updateModel() methods that was invoked, or an event listener that processed a queued event, called renderResponse() on the FacesContext instance for the current request, clear the remaining events from the event queue and transfer control to the Render Response phase of the request processing lifecycle. Otherwise, control must proceed to the Invoke Application phase.

If this phase of the request processing lifecycle is reached, it is assumed that all model updates have been completed, and any remaining event broadcast to the application needs to be performed. The implementation must ensure that the processApplication() method of the UIViewRoot instance is called. The default behavior of this method will be to broadcast any queued events that specify a phase identifier of PhaseId.INVOKE_APPLICATION. If responseComplete() was called on the FacesContext instance for the current request, clear the remaining events from the event queue and terminate lifecycle processing of the current request. If renderResponse() was called on the FacesContext instance for the current request, clear the remaining events from the event queue.

Advanced applications (or application frameworks) may replace the default ActionListener instance by calling the setActionListener() method on the Application instance for this application. However, the Jakarta Faces implementation must provide a default ActionListener instance that behaves as described in ActionListener Property.

This phase accomplishes two things:

Jakarta Faces supports a range of approaches that Jakarta Faces implementations may utilize in creating the response text that corresponds to the contents of the response view, including:

Because of the number of possible options, the mechanism for implementing the Render Response phase cannot be specified precisely. However, all Jakarta Faces implementations of this phase must conform to the following requirements:

When each particular component in the component tree is selected for rendering, calls to its encodeXxx() methods must be performed in the manner described in Component Specialization Methods. For components that implement ValueHolder (such as UIInput and UIOutput), data conversion must occur as described in the UIOutput Javadocs.

Upon completion of rendering, but before state saving the Jakarta Faces runtime must publish a jakarta.faces.event.PostRenderViewEvent. After doing so the Jakarta Faces runtime must save the completed state using the methods of the class StateManager. This state information must be made accessible on a subsequent request, so that the Restore View can access it. For more on StateManager, see State Saving Methods.

This phase is only required when the request being processed was not submitted from a previous response, and therefore did not initiate the Faces Request Generates Faces Response lifecycle. In order to generate a Faces Response, the application must first acquire references to several objects provided by the Jakarta Faces implementation, as described below.

When a Faces response is being intially created, or when the application decides it wants to create and configure a new view that will ultimately be rendered, it may follow the steps described below in order to set up the view that will be used. You must start with a reference to a FacesContext instance for the current request.

At a fundamental level, Jakarta Faces is a way to get values from the user, into your model tier for processing. The process by which values flow from the user to the model has been documented elsewhere in this spec, but a brief holistic survey comes in handy. The following description assumes the Jakarta Servlet/HTTP case, and that all components have Renderers.

Jakarta Faces is fully internationalized. The I18N capability in Jakarta Faces builds on the I18N concepts offered in the Jakarta Servlet and Jakarta Tags specifications. I18N happens at several points in the request processing lifecycle, but it is easiest to explain what goes on by breaking the task down by function.

Jakarta Faces introduces a powerful and flexible system for saving and restoring the state of the view between requests to the server. It is useful to describe state management from several viewpoints. For the page author, state management happens transparently. For the app assembler, state management can be configured to save the state in the client or on the server by setting the ServletContext InitParameter named jakarta.faces.STATE_SAVING_METHOD to either client or server. The value of this parameter directs the state management decisions made by the implementation.

This section only applies to pages written using Facelets. Resource Handling is the starting point for the normative specification for Resource Handling. This section gives a non-normative overview of the feature. The following steps walk through the points in the lifecycle where this feature is encountered. Consider a Faces web application that contains resources that have been packaged into the application as specified in Packaging Resources. Assume each page in the application includes references to resources, specifically scripts and stylesheets. The first diagram in this chapter is helpful in understanding this example.

Consider an initial request to the application.

The browser then parses the completely rendered page and proceeds to issue subsequent requests for the resources included in the page.

Now consider a request from the browser for one of those resources included in the page.

This section only applies to pages written using Facelets. The normative specification for this feature is spread out across several places, including the View Declaration Language Documentation for the <f:metadata> element, the javadocs for the UIViewParameter, ViewHandler, and ViewDeclarationLanguage classes, and the spec language requirements for the default NavigationHandler and the Request Processing Lifecycle. This leads to a very diffuse field of specification requirements. To aid in understanding the feature, this section provides a non-normative overview of the feature. The following steps walk through the points in the lifecycle where this feature is encountered. Consider a web application that uses this feature exclusively on every page. Therefore every page has the following features in common.

Consider an initial request to the application.

Consider when the user clicks on a link in the application. The browser issues a GET request with query parameters

Jakarta Faces has a bookmarking capability with the use of two Standard HTML RenderKit additions.

Provided is a component (UIOutcomeTarget) that provides properties that are used to produce a hyperlink at render time. The component can appear in the form of a button or a link. This feature introduces a concept known as “preemptive navigation”, which means the target URL is determined at Render Response time - before the user has activated the component. This feature allows the user to leverage the navigation model while also providing the ability to generate bookmarkable non-faces requests.

Jakarta Faces supports Jakarta Bean Validation. A Jakarta Faces implementation must support Jakarta Bean Validation if the environment in which the Jakarta Faces runtime is included requires Jakarta Bean Validation. Currently the only such environment is when Jakarta Faces is included in a Jakarta EE runtime.

A detailed description of the usage of Jakarta Bean Validation with Jakarta Faces is beyond the scope of this section, but this section will provide a brief overview of the feature, touching on the points of interest to a spec implementor. Consider a simple web application that has one page, written in Facelets, that has several text fields inside of a form. This application is running in a Jakarta Faces runtime in an environment that does require Jakarta Bean Validation, and therefore this feature is available. Assume that every text field is bound to a managed bean property that has at least one Jakarta Bean Validation constraint annotation attached to it.

During the render response phase that always precedes a postback, due to the specification requirements in Validation Registration, every UIInput in this application has an instance of Validator with id jakarta.faces.Bean attached to it.

During the process validations phase, due to the specification for the validate() method of this Validator, Bean Validation is invoked automatically, for the user specified validation constraints, whenever such components are normally validated. The jakarta.faces.Bean standard validator also ensures that every ConstraintViolation that resulted in attempting to validate the model data is wrapped in a FacesMessage and added to the FacesContext as normal with every other kind of validator.

See also Bean Validation Integration.

Jakarta Faces supports Ajax. The specification contains a JavaScript library for performing basic Ajax operations. The library helps define a standard way of sending an Ajax request, and processing an Ajax response, since these are problem areas for component compatibility. The specification provides two ways of adding Ajax to Jakarta Faces web applications. Page authors may use the JavaScript library directly in their pages by attaching the Ajax request call to a Jakarta Faces component via a JavaScript event (such as onclick). They may also take a more declarative approach and use a core Facelets tag (<f:ajax/>) that they can nest within Jakarta Faces components to “Ajaxify” them. It is also possible to “Ajaxify” regions of a page by “wrapping” the tag around component groups.

The server side aspects of Jakarta Faces Ajax frameworks work with the standard Jakarta Faces lifecycle. In addition to providing a standard page authoring experience, the specification also standardizes the server side processing of Ajax requests. Selected components in a Jakarta Faces view can be processed (known as partial processing) and selected components can be rendered to the client (known as partial rendering).

The Jakarta Faces specification contains a type of attached object known as component behaviors. Component behaviors play a similar role to converters and validators in that they are attached to a component instance in order to enhance the component with additional functionality not defined by the component itself. While converters and validators are currently limited to the server-side request processing lifecycle, component behaviors have impact that extends to the client, within the scope of a particular instance component in a view. In particular, the ClientBehavior interface defines a contract for behaviors that can enhance a component’s rendered content with behavior-defined "scripts". These scripts are executed on the client in response to end user interaction, but can also trigger postbacks back into the Jakarta Faces request processing lifecycle.

The usage pattern for client behaviors is as follows:

The first client behavior provided by the Jakarta Faces specification is the AjaxBehavior. This behavior is exposed to a page author as a Facelets <f:ajax> tag, which can be embedded within any of the standard HTML components as follows:

When activated in response to end user activity, the <f:ajax> client behavior generates an Ajax request back into the Jakarta Faces request processing lifecycle.

The component behavior framework is extensible and allows developers to define custom behaviors and also allows component authors to enhance custom components to work with behaviors.

System Events are normatively specified in System Events. This section provides an overview of this feature as it relates to the lifecycle.

System events expand on the idea of lifecycle PhaseEvents. With PhaseEvents, it is possible to have application scoped PhaseListeners that are given the opportunity to act on the system before and after each phase in the lifecycle. System events provide a much more fine grained insight into the system, allowing application or component scoped listeners to be notified of a variety of kinds of events. The set of events supported in the core specification is given in Event Classes. To accomodate extensibility, users may define their own kinds of events.

The system event feature is a simple publish/subscribe event model. There is no event queue, events are published immediately, and always with a call to Application.publishEvent(). There are several ways to declare interest in a particular kind of event.

This feature is conceptually related to the lifecycle because there are calls to Application.publishEvent() sprinkled throughout the code that gets executed when the lifecycle runs.

ResourceHandler defines a path based packaging convention for resources. The default implementation of ResourceHandler must support packaging resources in the web application root or in the classpath, according to the following specification.Other implementations of ResourceHandler are free to package resources however they like.

Resources such as images, stylesheets and scripts use the resource handling mechanism as outlined in Packaging Resources. So, for example:

These entries render exactly the same markup. In addition to using the name and library attributes, stylesheet and script resources can be “relocated” to other parts of the view. For example, we could specify that a script resource be rendered within an HTML “head”, “body” or “form” element in the page.

Every component may be named by a component identifier that must conform to the following rules:

To minimize the size of responses generated by Jakarta Faces, it is recommended that component identifiers be as short as possible.

If a component has been given an identifier, it must be unique in the namespace of the closest ancestor to that component that is a NamingContainer (if any).

While not a property of UIComponent, the component-type is an important piece of data related to each UIComponent subclass that allows the Application instance to create new instances of UIComponent subclasses with that type. Please see Object Factories for more on component-type.

Component types starting with “jakarta.faces.” are reserved for use by the Jakarta Faces specification.

Each standard user interface component class has a standard value for the component family, which is used to look up renderers associated with this component. Subclasses of a generic UIComponent class will generally inherit this property from its superclass, so that renderers who only expect the superclass will still be able to process specialized subclasses.

Component families starting with “jakarta.faces.” are reserved for use by the Jakarta Faces specification.

Properties and attributes of standard concrete component classes may be value expression enabled. This means that, rather than specifying a literal value as the parameter to a property or attribute setter, the caller instead associates a ValueExpression (see ValueExpression) whose getValue() method must be called (by the property getter) to return the actual property value to be returned if no value has been set via the corresponding property setter. If a property or attribute value has been set, that value must be returned by the property getter (shadowing any associated value binding expression for this property).

Value binding expressions are managed with the following method calls:

where name is the name of the attribute or property for which to establish the value expression. The implementation of setValueExpression must detemine if the expression is a literal by calling ValueExpression.isLiteralText() on the expression argument. If the expression argument is literal text, then ValueExpression.getValue() must be called on the expression argument. The result must be used as the value argument, along with the name argument to this component’s getAttributes().put(name, value) method call. For the standard component classes defined by this specification, all attributes, and all properties other than id, parent, action, listener, actionListener, valueChangeListener, and validator are value expression enabled. The action, listener, actionListener, valueChangeListener, and validator attributes are method expression enabled.

In previous versions of this specification, this concept was called “value binding”. Methods and classes referring to this concept are deprecated, but remain implemented to preserve backwards compatibility.

Please consult the javadoc for these methods to learn how they are implemented in terms of the new “value expression” concept.

A component binding is a special value expression that can be used to facilitate “wiring up” a component instance to a corresponding property of a JavaBean that is associated with the page, and wants to manipulate component instances programatically. It is established by calling setValueExpression() (see ValueExpression properties) with the special property name binding.

The specified ValueExpression must point to a read-write JavaBeans property of type UIComponent (or appropriate subclass). Such a component binding is used at two different times during the processing of a Faces Request:

Component bindings are often used in conjunction with JavaBeans that are dynamically instantiated via the Managed Bean Creation facility. If application developers place managed beans that are pointed at by component binding expressions in any scope other than request scope, the system cannot behave correctly. This is because placing it in a scope wider than request scope would require thread safety, since UIComponent instances depend on running inside of a single thread. There are also potentially negative impacts on memory management when placing a component binding in “session” or “view” scopes.

Client identifiers are used by Jakarta Faces implementations, as they decode and encode components, for any occasion when the component must have a client side name. Some examples of such an occasion are:

The client identifier is derived from the component identifier (or the result of calling UIViewRoot.createUniqueId() if there is not one), and the client identifier of the closest parent component that is a NamingContainer according to the algorithm specified in the javadoc for UIComponent.getClientId(). The Renderer associated with this component, if any, will then be asked to convert this client identifier to a form appropriate for sending to the client. The value returned from this method must be the same throughout the lifetime of the component instance unless setId() is called, in which case it will be recalculated by the next call to getClientId().

Components that have been added as children of another component can identify the parent by calling the getParent method. For the root node component of a component tree, or any component that is not part of a component tree, getParent will return null. In some special cases, such as transient components, it is possible that a component in the tree will return null from getParent(). The setParent() method should only be called by the List instance returned by calling the getChildren() method, or the Map instance returned by calling the getFacets() method, when child components or facets are being added, removed, or replaced.

Return a mutable List that contains all of the child UIComponents for this component instance. The returned List implementation must support all of the required and optional methods of the List interface, as well as update the parent property of children that are added and removed, as described in the Javadocs for this method. Note that the add() methods have a special requirement to cause the PostAddToViewEvent method to be fired, as well as the processing of the ResourceDependency annotation. See the javadocs for getChildren() for details.

A convenience method to return the number of child components for this component. [P2-start UIComponent.getChildCount requirements.] If there are no children, this method must return 0. The method must not cause the creation of a child component list, so it is preferred over calling getChildren().size() when there are no children. [P2-end]

Search for and return the UIComponent with an id that matches the specified search expression (if any), according to the algorithm described in the Javadocs for this method.

Return an immutable Iterator over all of the facets associated with this component (in an undetermined order), followed by all the child components associated with this component (in the order they would be returned by getChildren()).

Starting at this component in the view, search for the UIComponent whose getClientId() method returns a String that exactly matches the argument clientId using the algorithm specified in the Javadocs for this method. If such a UIComponent is found, call the invokeContextCallback() method on the argument callback passing the current FacesContext and the found UIComponent. Upon normal return from the callback, return true to the caller. If the callback throws an exception, it must be wrapped inside of a FacesException and re-thrown. If no such UIComponent is found, return false to the caller.

Special consideration should be given to the implementation of invokeOnComponent() for UIComponent classes that handle iteration, such as UIData. Iterating components manipulate their own internal state to handle iteration, and doing so alters the clientIds of components nested within the iterating component. Implementations of invokeOnComponent() must guarantee that any state present in the component or children is restored before returning. Please see the Javadocs for UIData.invokeOnComponent() for details.

The ContextCallback interface is specified as follows..

Please consult the Javadocs for more details on this interface.

Returns the UIComponent instance that is currently being processed.

Returns the closest ancestor component relative to getCurrentComponent that is a composite component, or null if no such component is exists.

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.

Jakarta Faces supports the traditional model of composing complex components out of simple components via parent-child relationships that organize the entire set of components into a tree, as described in Component Tree Manipulation. However, an additional useful facility is the ability to define particular subordinate components that have a specific role with respect to the owning component, which is typically independent of the parent-child relationship. An example might be a “data grid” control, where the children represent the columns to be rendered in the grid. It is useful to be able to identify a component that represents the column header and/or footer, separate from the usual child collection that represents the column data.

To meet this requirement, Jakarta Faces components offer support for facets, which represent a named collection of subordinate (but non-child) components that are related to the current component by virtue of a unique facet name that represents the role that particular component plays. Although facets are not part of the parent-child tree, they participate in request processing lifecycle methods, as described in Lifecycle Management Methods.

Return a mutable Map representing the facets of this UIComponent, keyed by the facet name.

A convenience method to return a facet value, if it exists, or null otherwise. If the requested facet does not exist, no facets Map must not be created, so it is preferred over calling getFacets().get() when there are no Facets.

For easy use of components that use facets, component authors may include type-safe getter and setter methods that correspond to each named facet that is supported by that component class. For example, a component that supports a header facet of type UIHeader should have methods with signatures and functionality as follows:

UIComponentBase provides default implementations for the methods from the jakarta.faces.component.behavior.BehaviorHolder interface. UIComponentBase does not implement the jakarta.faces.component.behavior.BehaviorHolder interface, but it provides the default implementations to simplify subclass implemenations. Refer to Component Behavior Model for more information.

This method attaches a Behavior to the component for the specified eventName. The eventName must be one of the values in the Collection returned from getEventNames(). For example, it may be desired to have some behavior defined when a “click” event occurs. The behavior could be some client side behavior in the form of a script executing, or a server side listener executing.

Returns the logical event names that can be associated with behavior for the component.

Returns a Map defining the association of events and behaviors. They keys in the Map are event names.

Returns the default event name (if any) for the component.

The render-independent characteristics of components are generally represented as Jakarta Bean component properties with getter and setter methods (see Render-Independent Properties). In addition, components may also be associated with generic attributes that are defined outside the component implementation class. Typical uses of generic attributes include:

The attributes for a component may be of any Java programming language object type, and are keyed by attribute name (a String). However, see State Saving Alternatives and Implications for implications of your application’s choice of state saving method on the classes used to implement attribute values.

Attribute names that begin with jakarta.faces are reserved for use by the Jakarta Faces specification. Names that begin with jakarta are reserved for definition through the Eclipse Foundation Process. Implementations are not allowed to define names that begin with jakarta.

The Map returned by getAttributes() must also support attribute-property transparency, which operates as follows:

The Map returned by getAttributes() must also conform to the entire contract for the Map interface.

The render-independent characteristics of a user interface component are represented as JavaBean component properties, following JavaBeans naming conventions. Specifically, the method names of the getter and/or setter methods are determined using standard JavaBeans component introspection rules, as defined by java.beans.Introspector. The render-independent properties supported by all UIComponents are described in the following table:

The method names for the render-independent property getters and setters must conform to the design patterns in the JavaBeans specification. See State Saving Alternatives and Implications for implications of your application’s choice of state saving method on the classes used to implement property values.

The methods described in this section are called by the Jakarta Faces implementation during the various phases of the request processing lifecycle, and may be overridden in a concrete subclass to implement specialized behavior for this component.

The broadcast() method is called during the common event processing (see Common Event Processing) at the end of several request processing lifecycle phases. For more information about the event and listener model, see Event and Listener Model. Note that it is not necessary to override this method to support additional event types.

This method is called during the Apply Request Values phase of the request processing lifecycle, and has the responsibility of extracting a new local value for this component from an incoming request. The default implementation in UIComponentBase delegates to a corresponding Renderer, if the rendererType property is set, and does nothing otherwise.

Generally, component writers will choose to delegate decoding and encoding to a corresponding Renderer by setting the rendererType property (which means the default behavior described above is adequate).

These methods are called during the Render Response phase of the request processing lifecycle. encodeAll() will cause this component and all its children and facets that return true from isRendered() to be rendered, regardless of the value of the getRendersChildren() return value. encodeBegin(), encodeChildren(), and encodeEnd() have the responsibility of creating the response data for the beginning of this component, this component’s children (only called if the rendersChildren property of this component is true), and the ending of this component, respectively. Typically, this will involve generating markup for the output technology being supported, such as creating an HTML <input> element for a UIInput component. For clients that support it, the encode methods might also generate client-side scripting code (such as JavaScript), and/or stylesheets (such as CSS). The default implementations in UIComponentBase encodeBegin() and encodeEnd() delegate to a corresponding Renderer, if the rendererType property is true, and do nothing otherwise. The default implementation in UIComponentBase encodeChildren() must iterate over its children and call encodeAll() for each child component. encodeBegin() must publish a PreRenderComponentEvent.

Generally, component writers will choose to delegate encoding to a corresponding Renderer, by setting the rendererType property (which means the default behavior described above is adequate).

Enqueue the specified event for broadcast at the end of the current request processing lifecycle phase. Default behavior is to delegate this to the queueEvent() of the parent component, normally resulting in broadcast via the default behavior in the UIViewRoot lifecycle methods.

The component author can override any of the above methods to customize the behavior of their component.

The following methods are called by the various phases of the request processing lifecycle, and implement a recursive tree walk of the components in a component tree, calling the component specialization methods described above for each component. These methods are not generally overridden by component writers, but doing so may be useful for some advanced component implementations. See the javadocs for detailed information on these methods

In order to support the “component” implicit object (See Implicit Object ELResolver for Facelets and Programmatic Access), the following methods have been added to UIComponent

pushComponentToEL() and popComponentFromEL() must be called inside each of the lifecycle management methods in this section as specified in the javadoc for that method.

Perform the component tree processing required by the Restore View phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself.

Perform the component tree processing required by the Apply Request Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself

Perform the component tree processing required by the Process Validations phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself.

Perform the component tree processing required by the Update Model Values phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself.

Perform the component tree processing required by the state saving portion of the Render Response phase of the request processing lifecycle for all facets of this component, all children of this component, and this component itself.

Return the FacesContext instance for the current request.

Return the Renderer that is associated this UIComponent, if any, based on the values of the family and rendererType properties currently stored as instance data on the UIComponent.

These methods are used to register and deregister an event listener. They should be called only by a public addXxxListener() method on the component implementation class, which provides typesafe listener registration.

Return a Map of the ResourceBundle for this component. Please consult the Javadocs for more information.

The ActionSource interface defines a way for a component to indicate that wishes to be a source of ActionEvent events, including the ability invoke application actions (see Application Actions) via the default ActionListener facility (see ActionListener Property).

The ActionSource2 interface extends ActionSource and provides a JavaBeans property analogous to the action property on ActionSource. This allows the ActionSource concept to leverage the Jakarta Expression Language API.

NamingContainer is a marker interface. Components that implement NamingContainer have the property that, for all of their children that have non-null component identifiers, all of those identifiers are unique. This property is enforced by the renderView() method on ViewHandler. Since this is just a marker interface, there are no properties, methods, or events. Among the standard components, UIForm and UIData implement NamingContainer. See UIForm and Section Methods “UIData” for details of how the NamingContainer concept is used in these two cases.

NamingContainer defines a public static final character constant, SEPARATOR_CHAR, that is used as default value to separate components of client identifiers, as well as the components of search expressions used by the findComponent() method see (Component Tree Navigation). The value of this constant must be a colon character (“:”), which is according to the HTML standard among the allowable values for the id and name attribute.

Use of this separator character in client identifiers rendered by Renderers can cause problems with CSS stylesheets that attach styles to a particular client identifier. For the Standard HTML RenderKit, this issue can be worked around by using the styleClass attribute to select CSS styles by class rather than by identifier, or by wrapping the section in a plain HTML <div> or <span> element containing the desired client identifier, or by escaping the colon character with a backslash in the CSS selector.

This separator character can be overridden to another character by the context initialization parameter named jakarta.faces.SEPARATOR_CHAR, for example an underscore character (“_”), but the page authors must then ensure to not use this exact character in the component identifiers themselves.

Component authors should never use the final character constant SEPARATOR_CHAR directly, but they should instead use UINamingContainer.getSeparatorChar(FacesContext) method to obtain the desired separator character, which can be either the overridden character or the default character of (“:”).

The StateHolder interface is implemented by UIComponent, Converter, FacesListener, and Validator classes that need to save their state between requests. UIComponent implements this interface to denote that components have state that must be saved and restored between requests.

PartialStateHolder extends StateHolder and adds a usage contract for components that wish to take part in the partial state saving mechanism introduced in version 2.0. Implementations of this interface should use the jakarta.faces.component.StateHelper instance returned from UIComponent.getStateHelper() to store stateful component information that otherwise would have been stored as instance variables on the class implementing PartialStateHolder.

ValueHolder is an interface that may be implemented by any concrete UIComponent that wishes to support a local value, as well as access data in the model tier via a value expression , and support conversion between String and the model tier data’s native data type.

The EditableValueHolder interface (extends ValueHolder, see ValueHolder) describes additional features supported by editable components, including ValueChangeEvents and Validators.

Classes that implement this interface agree to maintain a list of SystemEventListener instances for each kind of SystemEvent they can generate. This interface enables arbitrary Objects to act as the source for SystemEvent instances.

Components must implement the ClientBehaviorHolder interface to add the ability for attaching ClientBehavior instances (see Component Behavior Model). Components that extend UIComponentBase only need to implement the getEventNames() method and specify "implements ClientBehaviorHolder". UIComponentBase provides base implementations for all other methods. The concrete HTML component classes that come with Jakarta Faces implement the ClientBehaviorHolder interface.

Attach a ClientBehavior to a component implementing this ClientBehaviorHolder interface for the specified event. A default implementation of this method is provided in UIComponentBase to make it easier for subclass implementations to add behaviors.

Return a Collection of logical event names that are supported by the component implementing this ClientBehaviorHolder interface. The Collection must be non null and unmodifiable.

Return a Map containing the event-client behavior association. Each event in the Map may contain one or more ClientBehavior instances that were added via the addClientBehavior() method.

Each key value in this Map must be one of the event names in the Collection returned from getEventNames().

Return the default event name for this component behavior if the component defines a default event.

A typical web application must constantly deal with two fundamentally different viewpoints of the underlying data being manipulated through the user interface:

To transform data formats between these views, Jakarta Faces provides an ability to plug-in an optional Converter for each ValueHolder, which has the responsibility of converting the internal data representation between the two views. The application developer attaches a particular Converter to a particular ValueHolder by calling setConverter, passing an instance of the particular converter. A Converter implementation may be acquired from the Application instance (see Object Factories) for your application.

Jakarta Faces provides the jakarta.faces.convert.Converter interface to define the behavioral characteristics of a Converter. Instances of implementations of this interface are either identified by a converter identifier, or by a class for which the Converter class asserts that it can perform successful conversions, which can be registered with, and later retrieved from, an Application, as described in Object Factories.

Often, a Converter will be an object that requires no extra configuration information to perform its responsibilities. However, in some cases, it is useful to provide configuration parameters to the Converter (such as a java.text.DateFormat pattern for a Converter that supports java.util.Date model objects). Such configuration information will generally be provided via JavaBeans properties on the Converter instance.

Converter implementations should be programmed so that the conversions they perform are symmetric. In other words, if a model data object is converted to a String (via a call to the getAsString method), it should be possible to call getAsObject and pass it the converted String as the value parameter, and return a model data object that is semantically equal to the original one. In some cases, this is not possible. For example, a converter that uses the formatting facilities provided by the java.text.Format class might create two adjacent integer numbers with no separator in between, and in this case the Converter could not tell which digits belong to which number.

For UIInput and UIOutput components that wish to explicitly select a Converter to be used, a new Converter instance of the appropriate type must be created, optionally configured, and registered on the component by calling setConverter(). Otherwise, the Jakarta Faces implementation will automatically create new instances based on the data type being converted, if such Converter classes have been registered. In either case, Converter implementations need not be threadsafe, because they will be used only in the context of a single request processing thread.

The following two method signatures are defined by the Converter interface:

This method is used to convert the presentation view of a component’s value (typically a String that was received as a request parameter) into the corresponding model view. It is called during the Apply Request Values phase of the request processing lifecycle.

This method is used to convert the model view of a component’s value (typically some native Java programming language class) into the presentation view (typically a String that will be rendered in some markup language. It is called during the Render Response phase of the request processing lifecycle.

If the class implementing Converter has a ResourceDependency annotation or a ResourceDependencies annotation, the action described in the Javadocs for the Converter interface must be followed when ValueHolder.setConverter is called.

Jakarta Faces provides a set of standard Converter implementations. A Jakarta Faces implementation must register the DateTime and Number converters by name with the Application instance for this web application, as described in the table below. This ensures that the converters are available for subsequent calls to Application.createConverter(). Each concrete implementation class must define a static final String constant CONVERTER_ID whose value is the standard converter id under which this Converter is registered.

The following converter id values must be registered to create instances of the specified Converter implementation classes:

See the Javadocs for these classes for a detailed description of the conversion operations they perform, and the configuration properties that they support.

A Jakarta Faces implementation must register converters for all of the following classes using the by-type registration mechanism:

See the Javadocs for these classes for a detailed description of the conversion operations they perform, and the configuration properties that they support.

A compliant implementation must allow the registration of a converter for class java.lang.String and java.lang.String.TYPE that will be used to convert values for these types.

Jakarta Faces implements a model for event notification and listener registration based on the design patterns in the JavaBeans Specification, version 1.0.1. This is similar to the approach taken in other user interface toolkits, such as the Swing Framework included in the JDK.

A UIComponent subclass may choose to emit events that signify significant state changes, and broadcast them to listeners that have registered an interest in receiving events of the type indicated by the event’s implementation class. At the end of several phases of the request processing lifecycle, the Jakarta Faces implementation will broadcast all of the events that have been queued to interested listeners. Jakarta Faces also defines system events. System events are events that are not specific to any particular application, but rather stem from specific points in time of running a Jakarta Faces application. The following UML class diagram illustrates the key players in the event model. Boxes shaded in gray indicate classes or interfaces defined outside of the jakarta.faces.event package.