Skip to content

Latest commit

 

History

History
1804 lines (1456 loc) · 70.3 KB

UsingFacesInWebApplications.adoc

File metadata and controls

1804 lines (1456 loc) · 70.3 KB

Using Jakarta Faces in Web Applications

This specification provides Jakarta Faces implementors significant freedom to differentiate themselves through innovative implementation techniques, as well as value-added features. However, to ensure that web applications based on Jakarta Faces can be executed unchanged across different Jakarta Faces implementations, the following additional requirements, defining how a Jakarta Faces-based web application is assembled and configured, must be supported by all Jakarta Faces implementations.

Web Application Deployment Descriptor

Jakarta Faces-based applications are web applications that conform to the requirements of the Jakarta Servlet Specification (version 5.0 or later), and also use the facilities defined in this specification. Conforming web applications are packaged in a web application archive (WAR), with a well-defined internal directory structure. A key element of a WAR is the web application deployment descriptor, an XML document that describes the configuration of the resources in this web application. This document is included in the WAR file itself, at resource path /WEB-INF/web.xml.

Portable Jakarta Faces-based web applications must include the following configuration elements, in the appropriate portions of the web application deployment descriptor. Element values that are rendered in italics represent values that the application developer is free to choose. Element values rendered in bold represent values that must be utilized exactly as shown.

Executing the request processing lifecycle via other mechanisms is also allowed (for example, an MVC-based application framework can incorporate calling the correct phase implementations in the correct order); however, all Jakarta Faces implementations must support the functionality described in this chapter to ensure application portability.

Servlet Definition

Jakarta Faces implementations must provide request processing lifecycle services through a standard servlet, defined by this specification. This servlet must be defined, in the deployment descriptor of an application that wishes to employ this portable mechanism, as follows:

<servlet>

 <servlet-name> faces-servlet-name </servlet-name>

 <servlet-class> jakarta.faces.webapp.FacesServlet </servlet-class>

</servlet>

The servlet name, denoted as faces-servlet-name above, may be any desired value; however, the same value must be used in the servlet mapping (see Servlet Mapping).

In addition to FacesServlet, Jakarta Faces implementations may support other ways to invoke the Jakarta Faces request processing lifecycle, but applications that rely on these mechanisms will not be portable.

Servlet Mapping

All requests to a web application are mapped to a particular servlet based on matching a URL pattern (as defined in the Jakarta Servlet Specification) against the portion of the request URL after the context path that selected this web application. Jakarta Faces implementations must support web application that define a <servlet-mapping> that maps any valid url-pattern to the FacesServlet. Prefix or extension mapping may be used. When using prefix mapping, the following mapping is recommended, but not required:

<servlet-mapping>

 <servlet-name> faces-servlet-name </servlet-name>

 <url-pattern> /faces/* </url-pattern>

</servlet-mapping>

When using extension mapping the following mapping is recommended, but not required:

<servlet-mapping>

 <servlet-name> faces-servlet-name </servlet-name>

 <url-pattern> *.faces </url-pattern>

</servlet-mapping>

In addition to FacesServlet, Jakarta Faces implementations may support other ways to invoke the Jakarta Faces request processing lifecycle, but applications that rely on these mechanisms will not be portable.

Application Configuration Parameters

Servlet containers support application configuration parameters that may be customized by including <context-param> elements in the web application deployment descriptor. All Jakarta Faces implementations are required to support the following application configuration parameter names:

  • jakarta.faces.ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE —See the javadocs for the constant jakarta.faces.component.UIInput.ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE for the specification of this feature.

  • jakarta.faces.CLIENT_WINDOW_MODE —The context-param that controls the operation of the ClientWindow feature. See the javadocs for the constant jakarta.faces.lifecycle.ClientWindow.CLIENT_WINDOW_MODE_PARAM_NAME for the specification of this feature.

  • jakarta.faces.CONFIG_FILES — Comma-delimited list of context-relative resource paths under which the Jakarta Faces implementation will look for application configuration resources (see Application Configuration Resource Format), before loading a configuration resource named “/WEB-INF/faces-config.xml” (if such a resource exists). If “/WEB-INF/faces-config.xml” is present in the list, it must be ignored.

  • jakarta.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE — If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, Application.createConverter() must guarantee that the default for the timezone of all jakarta.faces.convert.DateTimeConverter instances must be equal to TimeZone.getDefault() instead of “GMT”.

  • jakarta.faces.DISABLE_FACESSERVLET_TO_XHTML — If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the default mapping of the FacesServlet to *.xhtml must not take effect.

  • jakarta.faces.FACELETS_LIBRARIES —If this param is set, the runtime must interpret it as a semicolon (;) separated list of paths, starting with “/” (without the quotes). The runtime must interpret each entry in the list as a path relative to the web application root and interpret the file found at that path as a facelet tag library, conforming to the facelet taglibrary schema and expose the tags therein according to Facelet Tag Library mechanism.

  • jakarta.faces.FACELETS_BUFFER_SIZE —The buffer size to set on the response when the ResponseWriter is generated. By default the value is 1024. A value of -1 will not assign a buffer size on the response. This should be increased if you are using development mode in order to guarantee that the response isn’t partially rendered when an error is generated.

  • jakarta.faces.FACELETS_DECORATORS —A semicolon (;) delimitted list of class names of type jakarta.faces.view.facelets.TagDecorator, with a no-argument constructor. These decorators will be loaded when the first request for a Facelets VDL view hits the ViewHandler for page compilation.

  • jakarta.faces.FACELETS_REFRESH_PERIOD — When a page is requested, what interval in seconds should the compiler check for changes. If you don’t want the compiler to check for changes once the page is compiled, then use a value of -1. Setting a low refresh period helps during development to be able to edit pages in a running application. If this value is not specified, then the default depends on Application.getProjectStage(). If it is Production, then runtime must act as if it is set to -1, else the runtime must act as if it is set to 0.

  • jakarta.faces.FACELETS_RESOURCE_RESOLVER — If this param is set, the runtime must interpret its value as a fully qualified classname of a java class that extends jakarta.faces.view.facelets.ResourceResolver and has a zero argument public constructor or a one argument public constructor where the type of the argument is ResourceResolver. If this param is set and its value does not conform to those requirements, the runtime must log a message and continue. If it does conform to these requirements and has a one-argument constructor, the default ResourceResolver must be passed to the constructor. If it has a zero argument constructor it is invoked directly. In either case, the new ResourceResolver replaces the old one.

    Related to this param is the corresponding annotation, jakarta.faces.view.facelets.FaceletsResourceResolver. The presence of this annotation must be ignored if the corresponding param has been specified. If present, this annotation must be attached to a class that extends jakarta.faces.view.facelets.ResourceResolver. If more than one class in the application has this annotation, an informative error message with logging level SEVERE must be logged indicating this case. Exactly one of the classes with the annotation must be taken to be the ResourceResolver for the application and any other classes with the annotation must be ignored. See Ordering of Artifacts for the means to put application configuration resources in order such that the chosen class can be defined. The same rules regarding decoration of the instance as listed above must apply to the annotated class.

  • jakarta.faces.FACELETS_SKIP_COMMENTS —If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the runtime must ensure that any XML comments in the Facelets source page are not delivered to the client.

  • jakarta.faces.FACELETS_SUFFIX —Allow the web application to define alternate suffixes for Facelet based XHTML pages containing Jakarta Faces content. See the javadocs for the symbolic constant ViewHandler.FACELETS_SUFFIX_PARAM_NAME for the complete specification.

  • jakarta.faces.FACELETS_VIEW_MAPPINGS —If this param is set, the runtime must interpret it as a semicolon (;) separated list of strings that is used to forcibly declare that certain pages in the application must be interpreted as using Facelets, regardless of their extension. See the javadocs for the symbolic constant ViewHandler.FACELETS_VIEW_MAPPINGS_PARAM_NAME for the complete specification.

  • jakarta.faces.FULL_STATE_SAVING_VIEW_IDS — The runtime must interpret the value of this parameter as a comma separated list of view IDs, each of which must have their state saved using the state saving mechanism specified in pre-Jakarta Faces JSF 1.2 (under the JCP). Deprecated since 4.1: Full state saving will be removed in favor of partial state saving in order to keep the spec simple. Therefore specifying full state saving view IDs via this context parameter will not be an option anymore.

  • jakarta.faces.HONOR_CURRENT_COMPONENT_ATTRIBUTES — The ServletContext init parameter consulted by the UIComponent to tell whether or not the CURRENT_COMPONENT and CURRENT_COMPOSITE_COMPONENT attribute keys should be honored as specified. If this parameter is not specified, or is set to false, the contract specified by the CURRENT_COMPONENT and CURRENT_COMPOSITE_COMPONENT method is not honored. If this parameter is set to true, the contract is honored.

  • jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL —If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, any implementation of UIInput.validate() must take the following additional action.

    If the jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL context parameter value is true (ignoring case), and UIInput. getSubmittedValue() returns a zero-length String call UIInput.setSubmittedValue(null) and continue processing using null as the current submitted value

  • jakarta.faces.LIFECYCLE_ID —Lifecycle identifier of the Lifecycle instance to be used when processing Jakarta Faces requests for this web application. If not specified, the Jakarta Faces default instance, identified by LifecycleFactory.DEFAULT_LIFECYCLE, must be used.

  • jakarta.faces.PARTIAL_STATE_SAVING --The ServletContext init parameter consulted by the runtime to determine if the partial state saving mechanism should be used. Deprecated since 4.1: Full state saving will be removed in favor of partial state saving in order to keep the spec simple. Therefore disabling partial state saving via this context parameter will not be an option anymore.

  • jakarta.faces.PROJECT_STAGE —A human readable string describing where this particular Jakarta Faces application is in the software development lifecycle. Valid values are “Development”, “UnitTest”, “SystemTest”, or “Production”, corresponding to the enum constants of the class jakarta.faces.application.ProjectStage. It is also possible to set this value via JNDI. See the javadocs for Application.getProjectStage().

  • jakarta.faces.RESOURCE_EXCLUDES — The ServletContext init parameter consulted by the handleResourceRequest to tell which kinds of resources must never be served up in response to a resource request. The value of this parameter is a single space separated list of file extensions, including the leading '.' character (without the quotes). If not specified, the default value .class .jsp .jspx .properties .xhtml .groovy is used. If manually specified, the given value entirely overrides the default one and does not supplement it.

  • jakarta.faces.SEPARATOR_CHAR --The context param that allows the character used to separate segments in a UIComponent clientId to be set on a per-application basis.

  • jakarta.faces.SERIALIZE_SERVER_STATE --If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, and the jakarta.faces.STATE_SAVING_METHOD is set to “server” (as indicated below), the server state must be guaranteed to be Serializable such that the aggregate state implements java.io.Serializable. The intent of this parameter is to ensure that the act of writing out the state to an ObjectOutputStream would not throw a NotSerializableException, but the runtime is not required verify this before saving the state.

  • jakarta.faces.STATE_SAVING_METHOD —The location where state information is saved. Valid values are “server” (typically saved in HttpSession) and “client (typically saved as a hidden field in the subsequent form submit). If not specified, the default value “server” must be used. When examining the parameter value, the runtime must ignore case.

  • jakarta.faces.VALIDATE_EMPTY_FIELDS —If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, all submitted fields will be validated. This is necessary to allow the model validator to decide whether null or empty values are allowable in the current application. If the value is false, null or empty values will not be passed to the validators. If the value is the string “auto”, the runtime must check if JSR-303 Beans Validation is present in the current environment. If so, the runtime must proceed as if the value “true” had been specified. If JSR-303 Beans Validation is not present in the current environment, the runtime most proceed as if the value “false” had been specified. If the param is not set, the system must behave as if the param was set with the value “auto”.

  • jakarta.faces.validator.DISABLE_DEFAULT_BEAN_VALIDATOR —If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the runtime must not automatically add the validator with validator-id equal to the value of the symbolic constant jakarta.faces.validator. VALIDATOR_ID to the list of default validators. Setting this parameter to true will have the effect of disabling the automatic installation of Bean Validation to every input component in every view in the application, though manual installation is still possible.

  • jakarta.faces.validator.ENABLE_VALIDATE_WHOLE_BEAN —If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the <f:validateWholeBean /> tag is enabled. If not set or set to false, this tag is a no-op.

  • jakarta.faces.VIEWROOT_PHASE_LISTENER_QUEUES_EXCEPTIONS —If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, exceptions thrown by PhaseListeners installed on the UIViewRoot are queued to the ExceptionHandler instead of being logged and swallowed. If this param is not set or is set to false, the old behavior prevails.

  • jakarta.faces.ENABLE_WEBSOCKET_ENDPOINT — Enable WebSocket support. See the javadoc for jakarta.faces.component.UIWebsocket.

  • jakarta.faces.WEBSOCKET_ENDPOINT_PORT — The integer context parameter name to specify the websocket endpoint port when it’s different from HTTP port. See the javadoc for jakarta.faces.component.UIWebsocket.

  • jakarta.faces.WEBAPP_RESOURCES_DIRECTORY

    If this param is set, the runtime must interpret its value as a path, relative to the web app root, where resources are to be located. This param value must not start with a “/”, though it may contain “/” characters. If no such param exists, or its value is invalid, the value “resources”, without the quotes, must be used by the runtime as the value.

  • jakarta.faces.WEBAPP_CONTRACTS_DIRECTORY

    If this param is set, the runtime must interpret its value as a path, relative to the web app root, where resource library contracts are to be located. This param value must not start with a “/”, though it may contain “/” characters. If no such param exists, or its value is invalid, the value “contracts”, without the quotes, must be used by the runtime as the value.

Jakarta Faces implementations may choose to support additional configuration parameters, as well as additional mechanisms to customize the Jakarta Faces implementation; however, applications that rely on these facilities will not be portable to other Jakarta Faces implementations.

Included Classes and Resources

A Jakarta Faces-based application will rely on a combination of APIs, and corresponding implementation classes and resources, in addition to its own classes and resources. The web application archive structure identifies two standard locations for classes and resources that will be automatically made available when a web application is deployed:

  • /WEB-INF/classes —A directory containing unpacked class and resource files.

  • /WEB-INF/lib —A directory containing JAR files that themselves contain class files and resources.

In addition, servlet and portlet containers typically provide mechanisms to share classes and resources across one or more web applications, without requiring them to be included inside the web application itself.

The following sections describe how various subsets of the required classes and resources should be packaged, and how they should be made available.

Application-Specific Classes and Resources

Application-specific classes and resources should be included in /WEB-INF/classes or /WEB-INF/lib, so that they are automatically made available upon application deployment.

Jakarta Servlet API Classes (jakarta.servlet.*)

These classes will typically be made available to all web applications using the shared class facilities of the servlet container. Therefore, these classes should not be included inside the web application archive.

Jakarta Tags API Classes (jakarta.servlet.jsp.jstl.*)

These classes will typically be made available to all web applications using the shared class facilities of the servlet container. Therefore, these classes should not be included inside the web application archive.

Jakarta Tags Implementation Classes

These classes will typically be made available to all web applications using the shared class facilities of the servlet container. Therefore, these classes should not be included inside the web application archive.

Jakarta Faces API Classes (jakarta.faces.*)

These classes will typically be made available to all web applications using the shared class facilities of the servlet container. Therefore, these classes should not be included inside the web application archive.

Jakarta Faces Implementation Classes

These classes will typically be made available to all web applications using the shared class facilities of the servlet container. Therefore, these classes should not be included inside the web application archive.

FactoryFinder

jakarta.faces.FactoryFinder implements the standard discovery algorithm for all factory objects specified in the Jakarta Faces APIs. For a given factory class name, a corresponding implementation class is searched for based on the following algorithm. Items are listed in order of decreasing search precedence:

  1. If a default Jakarta Faces configuration file (/WEB-INF/faces-config.xml) is bundled into the web application, and it contains a factory entry of the given factory class name, that factory class is used.

  2. If the Jakarta Faces configuration resource(s) named by the jakarta.faces.CONFIG_FILES ServletContext init parameter (if any) contain any factory entries of the given factory class name, those factories are used, with the last one taking precedence.

  3. If there are any META-INF/faces-config.xml resources bundled any JAR files in the web ServletContext’s resource paths, the factory entries of the given factory class name in those files are used, with the last one taking precedence.

  4. If a META-INF/services/{factory-class-name} resource is visible to the web application class loader for the calling application (typically as a result of being present in the manifest of a JAR file), its first line is read and assumed to be the name of the factory implementation class to use.

  5. If none of the above steps yield a match, the Jakarta Faces implementation specific class is used.

If any of the factories found on any of the steps above happen to have a one-argument constructor, with argument the type being the abstract factory class, that constructor is invoked, and the previous match is passed to the constructor. For example, say the container vendor provided an implementation of FacesContextFactory, and identified it in META-INF/services/jakarta.faces.context.FacesContextFactory in a jar on the webapp ClassLoader. Also say this implementation provided by the container vendor had a one argument constructor that took a FacesContextFactory instance. The FactoryFinder system would call that one-argument constructor, passing the implementation of FacesContextFactory provided by the Jakarta Faces implementation.

If a Factory implementation does not provide a proper one-argument constructor, it must provide a zero-arguments constructor in order to be successfully instantiated.

Once the name of the factory implementation class is located, the web application class loader for the calling application is requested to load this class, and a corresponding instance of the class will be created. A side effect of this rule is that each web application will receive its own instance of each factory class, whether the Jakarta Faces implementation is included within the web application or is made visible through the container’s facilities for shared libraries.

public static Object getFactory(String factoryName);

Create (if necessary) and return a per-web-application instance of the appropriate implementation class for the specified Jakarta Faces factory class, based on the discovery algorithm described above.

Jakarta Faces implementations must also include implementations of the several factory classes. In order to be dynamically instantiated according to the algorithm defined above, the factory implementation class must include a public, no-arguments constructor. For each of the public static final String fields on the class FactoryFinder whose field names end with the string “_FACTORY” (without the quotes), the implementation must provide an implementation of the corresponding Factory class using the algorithm described earlier in this section.

FacesServlet

FacesServlet is an implementation of jakarta.servlet.Servlet that accepts incoming requests and passes them to the appropriate Lifecycle implementation for processing. This servlet must be declared in the web application deployment descriptor, as described in Servlet Definition, and mapped to a standard URL pattern as described in Servlet Mapping.

public void init(ServletConfig config) throws ServletException;

Acquire and store references to the FacesContextFactory and Lifecycle instances to be used in this web application. For the LifecycleInstance, first consult the init-param set for this FacesServlet instance for a parameter of the name jakarta.faces.LIFECYCLE_ID. If present, use that as the lifecycleID attribute to the getLifecycle() method of LifecycleFactory. If not present, consult the context-param set for this web application. If present, use that as the lifecycleID attribute to the getLifecycle() method of LifecycleFactory. If neither param set has a value for jakarta.faces.LIFECYCLE_ID, use the value DEFAULT. As an implementation note, please take care to ensure that all PhaseListener instances defined for the application are installed on all lifecycles created during this process.

public void destroy();

Release the FacesContextFactory and Lifecycle references that were acquired during execution of the init() method.

public void service(ServletRequest request, ServletResponse response)
    throws IOException, ServletException;

For each incoming request, the following processing is performed:

  • Using the FacesContextFactory instance stored during the init() method, call the getFacesContext() method to acquire a FacesContext instance with which to process the current request.

  • Call the execute() method of the saved Lifecycle instance, passing the FacesContext instance for this request as a parameter. If the execute() method throws a FacesException, re-throw it as a ServletException with the FacesException as the root cause.

  • Call the render() method of the saved Lifecycle instance, passing the FacesContext instance for this request as a parameter. If the render() method throws a FacesException, re-throw it as a ServletException with the FacesException as the root cause.

  • Call the release () method on the FacesContext instance, allowing it to be returned to a pool if the Jakarta Faces implementation uses one.

The FacesServlet implementation class must also declare two static public final String constants whose value is a context initialization parameter that affects the behavior of the servlet:

  • CONFIG_FILES_ATTR —the context initialization attribute that may optionally contain a comma-delimited list of context relative resources (in addition to /WEB-INF/faces-config.xml which is always processed if it is present) to be processed. The value of this constant must be “jakarta.faces.CONFIG_FILES”.

  • LIFECYCLE_ID_ATTR —the lifecycle identifier of the Lifecycle instance to be used for processing requests to this application, if an instance other than the default is required. The value of this constant must be “jakarta.faces.LIFECYCLE_ID”.

Application Configuration Resources

This section describes the Jakarta Faces support for portable application configuration resources used to configure application components.

Overview

Jakarta Faces defines a portable configuration resource format (as an XML document) for standard configuration information. Please see the Javadoc overview for a link, titled “faces-config XML Schema Documentation” to the XML Schema Definition for such documents.

One or more such application resources will be loaded automatically, at application startup time, by the Jakarta Faces implementation. The information parsed from such resources will augment the information provided by the Jakarta Faces implementation, as described below.

In addition to their use during the execution of a Jakarta Faces-based web application, configuration resources provide information that is useful to development tools created by Tool Providers. The mechanism by which configuration resources are made available to such tools is outside the scope of this specification.

Application Startup Behavior

Implementations may check for the presence of a servlet-class definition of class jakarta.faces.webapp.FacesServlet in the web application deployment descriptor as a means to abort the configuration process and reduce startup time for applications that do not use Jakarta Faces Technology.

At application startup time, before any requests are processed, the Jakarta Faces implementation must process zero or more application configuration resources, located as follows

Make a list of all of the application configuration resources found using the following algorithm:

  • Check for the existence of a context initialization parameter named jakarta.faces.CONFIG_FILES. If it exists, treat it as a comma-delimited list of context relative resource paths (starting with a “/”), and add each of the specified resources to the list. If this parameter exists, skip the searching specified in the next bullet item in this list.

  • Search for all resources that match either “META-INF/faces-config.xml” or end with “.faces-config.xml” directly in the “META-INF” directory. Each resource that matches that expression must be considered an application configuration resource.

  • Using the java.util.ServiceLoader, locate all implementations of the jakarta.faces.ApplicationConfigurationResourceDocumentPopulator service. For each implementation, create a fresh org.w3c.dom.Document instance, configured to be in the XML namespace of the application configuration resource format, and invoke the implementation’s populateApplicationConfigurationResource() method. If no exception is thrown, add the document to the list, otherwise log a message and continue.

Let this list be known as applicationConfigurationResources for discussion. Also, check for the existence of a web application configuration resource named “/WEB-INF/faces-config.xml”, and refer to this as applicationFacesConfig for discussion, but do not put it in the list. When parsing the application configuration resources, the implementation must ensure that applicationConfigurationResources are parsed before applicationFacesConfig.

Please see Ordering of Artifacts for details on the ordering in which the decoratable artifacts in the application configuration resources in applicationConfigurationResources and applicationFacesConfig must be processed.

This algorithm provides considerable flexibility for developers that are assembling the components of a Jakarta Faces-based web application. For example, an application might include one or more custom UIComponent implementations, along with associated Renderers, so it can declare them in an application resource named “/WEB-INF/faces-config.xml” with no need to programmatically register them with Application instance. In addition, the application might choose to include a component library (packaged as a JAR file) that includes a “META-INF/faces-config.xml” resource. The existence of this resource causes components, renderers, and other Jakarta Faces implementation classes that are stored in this library JAR file to be automatically registered, with no action required by the application.

Perform the actions specified in Faces Flows.

Perform the actions specified in Resource Library Contracts.

The runtime must publish the jakarta.faces.event.PostConstructApplicationEvent immediately after all application configuration resources have been processed.

XML parsing errors detected during the loading of an application resource file are fatal to application startup, and must cause the application to not be made available by the container. Jakarta Faces implementations that are part of a Jakarta EE technology-compliant implementation are required to validate the application resource file against the XML schema for structural correctness. The validation is recommended, but not required for Jakarta Faces implementations that are not part of a Jakarta EE technology-compliant implementation.

Resource Library Contracts

If the parsing of the application configuration resources completed successfully, scan the application for resource library contracts. Any resource library contract as described in Resource Library Contracts must be discovered at application startup time. The complete set of discovered contracts has no ordering semantics and effectively is represented as a Set<String> where the values are just the names of the resource libraries. If multiple sources in the application configuration resources contained <resource-library-contracts>, they are all merged into one element. Duplicates are resolved in as specified in Ordering of Artifacts. If the application configuration resources produced a <resource-library-contracts> element, create an implementation private data structure (called the “resource library contracts data structure”) containing the mappings between viewId patterns and resource library contracts as listed by the contents of that element.

The <resource-library-contracts> element is contained with in the <application> element and contains one or more <contract-mapping> elements. Each <contract-mapping> element must one or more <url-pattern> elements and one or more <contract> elements.

The value of the <url-pattern> element may be any of the following.

  • The literal string *, meaning all views should have these contracts applied.

  • An absolute prefix mapping, relative to the web app root, such as /directoryName/* meaning only views matching that prefix should have these contracts applied.

  • An exact fully qualified file path, relative to the web app root, such as /directoryName/fileName.xhtml, meaning exactly that view should have the contracts applied.

    See ViewDeclarationLanguage.calculateResourceLibraryContracts() for the specification of how the values of the <url-pattern> are to be processed.

The value of the <contracts> element is a comma separated list of resource library contract names. A resource library contract name is the name of a directory within the contracts directory of the web app root, or the contracts directory within the META-INF/contracts JAR entry.

Only the contracts explicitly mentioned in the <resource-library-contracts> element are included in the data structure. If the information from the application configuration resources refers to a contract that is not available to the application, an informative error message must be logged.

If the application configuration resources did not produce a <resource-library-contracts> element, the data structure should be populated as if this were the contents of the <resource-library-contracts> element:

<resource-library-contracts>
  <contract-mapping>
    <url-pattern>*</url-pattern>
    <contracts>”all available contracts”</contracts>
  </contract-mapping>
</resource-library-contracts>

Where “all available contracts” is replaced with a comma separated list of all the contracts discovered in the startup scan. In the case where there is no <resource-library-contracts> element in the application configuration resources, ordering of contracts is unspecified, which may lead to unexpected behavior in the case of multiple contracts that have the same contract declaration.

Faces Flows

If the parsing of the application configuration resources completed successfully, any XML based flow definitions in the application configuration resources will have been successfully discovered as well. The discovered flows must be exposed as thread safe immutable application scoped instances of jakarta.faces.flow.Flow, and made accessible to the runtime via the FlowHandler. If flows exist in the application, but the jakarta.faces.CLIENT_WINDOW_MODE context-param was not specified, the runtime must behave as if the value “url” (without the quotes) was specified for this context-param.

Defining Flows

Flows are defined using the <flow-definition> element. This element must have an id attribute which uniquely identifies the flow within the scope of the Application Configuration Resource file in which the element appears. To enable multiple flows with the same id to exist in an application, the <faces-config><name> element is taken to be the definingDocumentId of the flow. If no <name> element is specified, the empty string is taken as the value for definingDocumentId. Please see FlowHandler for an overview of the flow feature. Note that a number of conventions exist to make defining flows simpler. These conventions are specified in Packaging Flows in Directories.

Packaging Faces Flows in JAR Files

The runtime must support packaging Faces Flows in JAR files as specified in this section. Any flows packaged in a jar file must have its flow definition included in a faces-config.xml file located at the META-INF/faces-config.xml JAR entry. This ensures that such flow definitions are included in the application configuration resources. Any view nodes included in the jar must be located within sub entries of the META-INF/flows/<flowName> JAR entry, where <flowName> is a JAR directory entry whose name is identical to that of a flow id in the corresponding faces-config.xml file. If there are @FlowScoped beans or beans with @FlowDefinition in the JAR, there must be a JAR entry named META-INF/beans.xml. This ensures that such beans and definitions are discovered by the runtime at startup. None of the flow definition conventions specified in Packaging Flows in Directories apply when a flow is packaged in a JAR file. In other words, the flow must be explicitly declared in the JAR file’s faces-config.xml.

Packaging Flows in Directories

The view nodes of a flow need not be collected in any specific directory structure, but there is a benefit in doing so: flow definition conventions. If the jakarta.faces.CONFIG_FILES context parameter includes references to files of the form /<flowName>/<flowName>-flow.xml or /WEB-INF/<flow-Name>/<flowName>-flow.xml, and if such files exist in the current application (even if they are zero length), they are treated as flow definitions. Flow definitions defined in this way must not be nested any deeper in the directory structure than one level deep from the web app root or the WEB-INF directory.

The following conventions apply to flows defined in this manner. Any flow definition in the corresponding -flow.xml file will override any of the conventions in the case of a conflict.

  • Every vdl file in that directory is a view node of that flow.

  • The start node of the flow is the view whose name is the same as the name of the flow.

  • Navigation among any of the views in the directory is considered to be within the flow.

  • The flow defining document id is the empty string.

In the case of a zero length flow definition file, the following also applies:

  • There is one return node in the flow, whose id is the id of the flow with the string “-return” (without the quotes) appended to it. For example, if flowId is shopping, the return node id is shopping-return.

  • The from-outcome of the return node is a string created with the following formula:
    "/" + flowId + "-return".

For each directory packaged flow definition, the runtime must synthesize an instance of jakarta.faces.flow.Flow that represents the union of the flow definition from the /<flowName>/<flowName>-flow.xml file for that directory, and any of the preceding naming conventions, with precedence being given to the -flow.xml file. Such Flow instances must be added to the FlowHandler before the PostConstructApplicationEvent is published.

Application Shutdown Behavior

When the Jakarta Faces runtime is directed to shutdown by its container, the following actions must be taken.

  1. Ensure that calls to FacesContext.getCurrentInstance() that happen during application shutdown return successfully, as specified in the Javadocs for that method.

  2. Publish the jakarta.faces.event.PreDestroyApplicationEvent.

  3. Call FactoryFinder.releaseFactories().

Application Configuration Resource Format

Application configuration resources that are written to run on Jakarta Faces 4.1 must include the following schema declaration and must conform to the schema shown in Appendix A - Jakarta Faces Metadata

<faces-config
    xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
        https://jakarta.ee/xml/ns/jakartaee/web-facesconfig_4_1.xsd"
    version="4.1">

Application configuration resources that are written to run on Jakarta Faces 4.0 must include the following schema declaration:

<faces-config
    xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
        https://jakarta.ee/xml/ns/jakartaee/web-facesconfig_4_0.xsd"
    version="4.0">

Application configuration resources that are written to run on Jakarta Faces 3.0 must include the following schema declaration:

<faces-config
    xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
        https://jakarta.ee/xml/ns/jakartaee/web-facesconfig_3_0.xsd"
    version="3.0">

Note that the “hostname” of the xmlns and xsi:schemaLocation attributes has changed from “xmlns.jcp.org” to “jakarta.ee”. The “jakarta.ee” hostname must be used when using version="3.0" and web-facesconfig_3_0.xsd. It is not valid to use this hostname with versions prior to 3.0. Likewise, it is not valid to use the “xmlns.jcp.org” hostname when using version="3.0" and web-facesconfig_3_0.xsd.

Application configuration resources that are written to run on pre-Jakarta Faces JSF 2.3 must include the following schema declaration:

<faces-config
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_3.xsd"
    version="2.3">

Application configuration resources that are written to run on pre-Jakarta Faces JSF 2.2 must include the following schema declaration:

<faces-config
    xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
        http://xmlns.jcp.org/xml/ns/javaee/web-facesconfig_2_2.xsd"
    version="2.2">

Note that the “hostname” of the xmlns and xsi:schemaLocation attributes has changed from “java.sun.com” to “xmlns.jcp.org”. The “xmlns.jcp.org” hostname must be used when using version="2.2" and web-facesconfig_2_2.xsd. It is not valid to use this hostname with versions prior to 2.2. Likewise, it is not valid to use the “java.sun.com” hostname when using version="2.2" and web-facesconfig_2_2.xsd.

Application configuration resources that are written to run on pre-Jakarta Faces JSF 2.1 must include the following schema declaration:

<faces-config
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-facesconfig_2_1.xsd"
    version="2.1">

Application configuration resources that are written to run on pre-Jakarta Faces JSF 2.0 must include the following schema declaration:

<faces-config
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
    version="2.0">

Application configuration resources that are written to run on pre-Jakarta Faces JSF 1.2 Application configuration resources must include the following schema declaration and must conform to the schema referenced in the schemalocation URI shown below:

<faces-config
    xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
    version="1.2">

Application configuration resources that are written to run on pre-Jakarta Faces JSF 1.1 implementations must use the DTD declaration and include the following DOCTYPE declaration:

<!DOCTYPE faces-config PUBLIC
    "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
    "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">

Application configuration resources that are written to run on pre-Jakarta Faces JSF 1.0 implementations must use the DTD declaration for the 1.0 DTD contained in the binary download of the pre-Jakarta Faces JSF 1.0 reference implementation. They must also use the following DOCTYPE declaration:

<!DOCTYPE faces-config PUBLIC
    "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
    "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">

Configuration Impact on Jakarta Faces Runtime

The following XML elements [12] in application configuration resources cause registration of Jakarta Faces objects into the corresponding factories or properties. It is an error if the value of any of these elements cannot be correctly parsed, loaded, set, or otherwise used by the implementation.

  • /faces-config/component —Create or replace a component type / component class pair with the Application instance for this web application.

  • /faces-config/converter —Create or replace a converter id / converter class or target class / converter class pair with the Application instance for this web application.

  • /faces-config/render-kit —Create and register a new RenderKit instance with the RenderKitFactory, if one does not already exist for the specified render-kit-id.

  • /faces-config/render-kit/renderer —Create or replace a component family + renderer id / renderer class pair with the RenderKit associated with the render-kit element we are nested in.

  • /faces-config/validator —Create or replace a validator id / validator class pair with the Application instance for this web application.

For components, converters, and validators, it is legal to replace the implementation class that is provided (by the Jakarta Faces implementation) by default. This is accomplished by specifying the standard value for the <component-type>, <converter-id>, or <validator-id> that you wish to replace, and specifying your implementation class. To avoid class cast exceptions, the replacement implementation class must be a subclass of the standard class being replaced. For example, if you declare a custom Converter implementation class for the standard converter identifier jakarta.faces.Integer, then your replacement class must be a subclass of jakarta.faces.convert.IntegerConverter.

For replacement Renderers, your implementation class must extend jakarta.faces.render.Renderer. However, to avoid unexpected behavior, your implementation should recognize all of the render-dependent attributes supported by the Renderer class you are replacing, and provide equivalent decode and encode behavior.

The following XML elements cause the replacement of the default implementation class for the corresponding functionality, provided by the Jakarta Faces implementation. See Delegating Implementation Support for more information about the classes referenced by these elements:

  • /faces-config/application/action-listener —Replace the default ActionListener used to process ActionEvent events with an instance with the class specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is an ActionListener.

  • /faces-config/application/navigation-handler —Replace the default NavigationHandler instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a NavigationHandler.

  • /faces-config/application/resource-handler — Replace the default ResourceHandler instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a ResourceHandler.

  • /faces-config/application/search-expression-handler —This element contains the fully qualified class name of the concrete jakarta.faces.component.search.SearchExpressionHandler implementation class that will be used for processing of a search expression.

  • /faces-config/application/search-keyword-resolver — This element contains the fully qualified class name of the concrete jakarta.faces.component.search.SearchKeywordResolver implementation class that will be used during the processing of a search expression keyword.

  • /faces-config/application/state-manager —Replace the default StateManager instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a StateManager.

  • /faces-config/application/system-event-listener —Instantiate a new instance of the class specified as the content within a nested system-event-listener-class element, which must implement SystemEventListener. This instance is referred to as systemEventListener for discussion. If a system-event-class is specified as a nested element within system-event-listener, it must be a class that extends SystemEvent and has a public zero-arguments constructor. The Class object for system-event-class is obtained and is referred to as systemEventClass for discussion. If system-event-class is not specified, SystemEvent.class must be used as the value of system EventClass. If source-class is specified as a nested element within system-event-listener, it must be a fully qualified class name. The Class object for source-class is obtained and is referred to as sourceClass for discussion. If source-class is not specified, let sourceClass be null. Obtain a reference to the Application instance and call subscribeForEvent(facesEventClass, sourceClass, systemEventListener), passing the arguments as assigned in the discussion.

  • /faces-config/application/view-handler —Replace the default ViewHandler instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a ViewHandler.

The following XML elements cause the replacement of the default implementation class for the corresponding functionality, provided by the Jakarta Faces implementation. Each of the referenced classes must have a public zero-arguments constructor:

  • /faces-config/factory/application-factory —Replace the default ApplicationFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is an ApplicationFactory.

  • /faces-config/factory/client-window-factory —Replace the default ClientWindowFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a ClientWindowFactory.

  • /faces-config/factory/exception-handler-factory —Replace the default ExceptionHandlerFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a ExceptionHandlerFactory.

  • /faces-config/factory/faces-context-factory —Replace the default FacesContextFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a FacesContextFactory.

  • /faces-config/factory/flash-factory —Replace the default FlashFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a FlashFactory.

  • /faces-config/factory/flow-handler-factory —Replace the default FlowHandlerFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a FlowHandlerFactory.

  • /faces-config/factory/lifecycle-factory —Replace the default LifecycleFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a LifecycleFactory.

  • /faces-config/factory/render-kit-factory —Replace the default RenderKitFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a RenderKitFactory.

  • /faces-config/factory/search-expression-context-kit-factory —This element contains the fully qualified class name of the concrete SearchExpressionContextFactory implementation class that will be called when FactoryFinder.getFactory(SEARCH_EXPRESSION_CONTEXT_FACTORY) is called.

  • /faces-config/factory/view-declaration-language-factory —Replace the default ViewDeclarationLanguageFactory instance with the one specified. The contents of this element must be a fully qualified Java class name that, when instantiated, is a ViewDeclarationLanguageFactory.

The following XML elements cause the addition of event listeners to standard Jakarta Faces implementation objects, as follows. Each of the referenced classes must have a public zero-arguments constructor.

  • /faces-config/lifecycle/phase-listener —Instantiate a new instance of the specified class, which must implement PhaseListener, and register it with the Lifecycle instance for the current web application.

In addition, the following XML elements influence the runtime behavior of the Jakarta Faces implementation, even though they do not cause registration of objects that are visible to a Jakarta Faces-based application.

  • /faces-config/navigation-rule —Make the characteristics of a navigation rule available to the default NavigationHandler implementation.

Delegating Implementation Support

The runtime must support the decorator design pattern as specified below for all classes of the jakarta.faces package implementing the FacesWrapper interface, among others:

  • Application via ApplicationWrapper

  • ApplicationFactory

  • ClientWindow via ClientWindowWrapper

  • ClientWindowFactory

  • ConfigurableNavigationHandler via ConfigurableNavigationHandlerWrapper

  • ExceptionHandler via ExceptionHandlerWrapper

  • ExceptionHandlerFactory

  • ExternalContext via ExternalContextWrapper

  • ExternalContextFactory

  • FaceletCacheFactory

  • FacesContext via FacesContextWrapper

  • FacesContextFactory

  • Flash via FlashWrapper

  • FlashFactory

  • FlowHandlerFactory via FlowHandlerFactoryWrapper

  • Lifecycle via LifecycleWrapper

  • LifecycleFactory

  • NavigationCase via NavigationCaseWrapper

  • NavigationHandler via NavigationHandlerWrapper

  • PartialViewContext via PartialViewContextWrapper

  • PartialViewContextFactory

  • Renderer via RendererWrapper

  • RenderKit via RenderKitWrapper

  • RenderKitFactory

  • Resource via ResourceWrapper

  • ResourceHandler via ResourceHandlerWrapper

  • ResponseWriter via ResponseWriterWrapper

  • SearchExpressionContextFactory

  • SearchExpressionHandler via SearchExpressionHandlerWrapper

  • StateManager via StateManagerWrapper

  • TagHandlerDelegateFactory

  • ViewDeclarationLanguage via ViewDeclarationLanguageWrapper

  • ViewDeclarationLanguageFactory

  • ViewHandler via ViewHandlerWrapper

  • VisitContext via VisitContextWrapper

  • VisitContextFactory

For all of these artifacts, the decorator design pattern is leveraged, so that if one provides a constructor that takes a single argument of the appropriate type, the custom implementation receives via FacesWrapper.getWrapped() method a reference to the implementation that was previously fulfilling the role. In this way, the custom implementation is able to override just a subset of the functionality (or provide only some additional functionality) and delegate the rest to the existing implementation.

For example, say you wanted to provide a custom ViewHandler that was the same as the default one, but provided a different implementation of the calculateLocale() method. Consider this code excerpt from a custom ViewHandler:

public class YourViewHandler extends ViewHandlerWrapper {

  // Always implement the constructor taking the wrapped instance
  public YourViewHandler(ViewHandler wrapped) {
    super(wrapped);
  }

  // Overridden version of calculateLocale()
  public Locale calculateLocale(FacesContext context) {

    // You can if necessary obtain the original locale as follows
    Locale originalLocale = getWrapped().calculateLocale(context);

    // You can perform custom calculation of the locale here
    Locale customLocale = ...

    return customLocale;
  }
}

This can then be configured in the faces-config.xml file as follows:

<application>
  <view-handler>com.example.YourViewHandler</view-handler>
</application>

The constructor taking the wrapped instance will get called as the application is initially configured by the Jakarta Faces implementation, and the previously registered ViewHandler will get passed to it.

The implementation must also support decoration of a RenderKit instance. At the point in time of when the <render-kit> element is processed in an application configuration resources, if the current RenderKitFactory already has a RenderKit instance for the <render-kit-id> within the <render-kit> element, and the Class whose fully qualified java class name is given as the value of the <render-kit-class> element within the <render-kit> element has a constructor that takes an RenderKit instance, the existing RenderKit for that <render-kit-id> must be passed to that constructor, and the RenderKit resulting from the executing of that constructor must be passed to RenderKitFactory.addRenderKit().

Ordering of Artifacts

Because the specification allows the application configuration resources to be composed of multiple files, discovered and loaded from several different places in the application, the question of ordering must be addressed. This section specifies how application configuration resource authors may declare the ordering requirements of their artifacts.

Application Startup Behavior defines two concepts: applicationConfigurationResources and applicationFacesConfig. The former is an ordered list of all the application configuration resources except the one at “WEB-INF/faces-config.xml”, and the latter is a list containing only the one at “WEB-INF/faces-config.xml”.

An application configuration resource may have a top level <name> element of type javaee:java-identifierType. If a <name> element is present, it must be considered for the ordering of decoratable artifacts (unless the duplicate name exception applies, as described below).

Two cases must be considered to allow application configuration resources to express their ordering preferences.

  1. Absolute ordering: an <absolute-ordering> element in the applicationFacesConfig

    In this case, ordering preferences that would have been handled by case 2 below must be ignored.

    Any <name> element direct children of the <absolute-ordering> must be interpreted as indicating the absolute ordering in which those named application configuration resources, which may or may not be present in applicationConfigurationResources, must be processed.

    The <absolute-ordering> element may contain zero or one <others /> elements. The required action for this element is described below. If the <absolute-ordering> element does not contain an <others /> element, any application configuration resources not specifically mentioned within <name /> elements must be ignored.

    Duplicate name exception: if, when traversing the children of <absolute-ordering> , multiple children with the same <name> element are encountered, only the first such occurrence must be considered.

    If an <ordering> element appears in the applicationFacesConfig, an informative message must be logged and the element must be ignored.

  2. Relative ordering: an <ordering> element within a file in the applicationConfigurationResources

    An entry in applicationConfigurationResources may have an <ordering> element. If so, this element must contain zero or one <before> elements and zero or one <after> elements. The meaning of these elements is explained below.

    Duplicate name exception: if, when traversing the constituent members of applicationConfigurationResources, multiple members with the same <name> element are encountered, the application must log an informative error message including information to help fix the problem, and must fail to deploy. For example, one way to fix this problem is for the user to use absolute ordering, in which case relative ordering is ignored.

    If an <absolute-ordering> element appears in an entry in applicationConfigurationResources, an informative message must be logged and the element must be ignored.

Consider this abbreviated but illustrative example. faces-configA, faces-configB and faces-configC are found in applicationConfigurationResources, while my-faces-config is the applicationFacesConfig. The principles that explain the ordering result follow the example code.

faces-configA:.

<faces-config>
  <name>A</name>
  <ordering><after><name>B</name></after></ordering>
  <application>
    <view-handler>com.a.ViewHandlerImpl</view-handler>
  </application>
  <lifecycle>
    <phase-listener>com.a.PhaseListenerImpl</phase-listener>
  </lifecycle>
</faces-config>

faces-configB:.

<faces-config>
  <name>B</name>
  <application>
    <view-handler>com.b.ViewHandlerImpl</view-handler>
  </application>
  <lifecycle>
    <phase-listener>com.b.PhaseListenerImpl</phase-listener>
  </lifecycle>
</faces-config>

faces-configC:.

<faces-config>
  <name>C</name>
  <ordering><before><others/></before></ordering>
  <application>
    <view-handler>com.c.ViewHandlerImpl</view-handler>
  </application>
  <lifecycle>
    <phase-listener>com.c.PhaseListenerImpl</phase-listener>
  </lifecycle>
</faces-config>

my-faces-config:.

<faces-config>
  <name>my</name>
  <application>
    <view-handler>com.my.ViewHandlerImpl</view-handler>
  </application>
  <lifecycle>
    <phase-listener>com.my.PhaseListenerImpl</phase-listener>
  </lifecycle>
</faces-config>

In this example, the processing order for the applicationConfigurationResources and applicationFacesConfig will be.

Implementation Specific Config
C
B
A
my

The preceding example illustrates some, but not all, of the following principles.

  • <before> means the document must be ordered before the document with the name matching the name specified within the nested <name> element.

  • <after> means the document must be ordered after the document with the name matching the name specified within the nested <name> element.

  • There is a special element <others /> which may be included zero or one time within the <before> or < after> elements, or zero or one time directly within the <absolute-ordering> elements. The <others /> element must be handled as follows.

  • The <others /> element represents a set of application configuration resources. This set is described as the set of all application configuration resources discovered in the application, minus the one being currently processed, minus the application configuration resources mentioned by name in the <ordering/> section. If this set is the empty set, at the time the application configuration resources are being processed, the <others /> element must be ignored.

    • If the <before> element contains a nested <others />, the document will be moved to the beginning of the list of sorted documents. If there are multiple documents stating <before> <others />, they will all be at the beginning of the list of sorted documents, but the ordering within the group of such documents is unspecified.

    • If the <after> element contains a nested <others />, the document will be moved to the end of the list of sorted documents. If there are multiple documents requiring <after> <others />, they will all be at the end of the list of sorted documents, but the ordering within the group of such documents is unspecified.

    • Within a <before> or <after> element, if an <others /> element is present, but is not the only <name> element within its parent element, the other elements within that parent must be considered in the ordering process.

    • If the <others /> element appears directly within the <absolute-ordering> element, the runtime must ensure that any application configuration resources in applicationConfigurationResources not explicitly named in the <absolute-ordering> section are included at that point in the processing order.

  • If a faces-config file does not have an <ordering> or <absolute-ordering> element the artifacts are assumed to not have any ordering dependency.

  • If the runtime discovers circular references, an informative message must be logged, and the application must fail to deploy. Again, one course of action the user may take is to use absolute ordering in the applicationFacesConfig.

The previous example can be extended to illustrate the case when applicationFacesConfig contains an ordering section.

my-faces-config:.

<faces-config>
  <name>my</name>
  <absolute-ordering>
    <name>C</name>
    <name>A</name>
  </absolute-ordering>
  <application>
    <view-handler>com.my.ViewHandlerImpl</view-handler>
  </application>
  <lifecycle>
    <phase-listener>com.my.PhaseListenerImpl</phase-listener>
  </lifecycle>
</faces-config>

In this example, the constructor decorator ordering for ViewHandler would be C, A, my.

Some additional example scenarios are included below. All of these apply to the applicationConfigurationResources relative ordering case, not to the applicationFacesConfig absolute ordering case.

Document A - <after><others/><name>C</name></after>
Document B - <before><others/></before>
Document C - <after><others/></after>
Document D - no ordering
Document E - no ordering
Document F - <before><others/><name>B</name></before>

The valid parse order is F, B, D/E, C, A, where D/E may appear as D, E or E, D

Document <no id> - <after><others/></after>
                   <before><name>C</name></before>
Document B - <before><others/></before>
Document C - no ordering
Document D - <after><others/></after>
Document E - <before><others/></before>
Document F - no ordering

The complete list of parse order solutions for the above example is

  • B,E,F,<no id>,C,D

  • B,E,F,<no_id>,D,C

  • E,B,F,<no id>,C,D

  • E,B,F,<no_id>,D,C

  • B,E,F,D,<no id>,C

  • E,B,F,D,<no id>,C

Document A - <after><name>B</name></after>
Document B - no ordering
Document C - <before><others/></before>
Doucment D - no ordering

Resulting parse order: C, B, D, A. The parse order could also be: C, D, B, A.

Example Application Configuration Resource

The following example application resource file defines a custom UIComponent of type Date, plus a number of Renderers that know how to decode and encode such a component:

<?xml version="1.0" encoding="UTF-8"?>
<faces-config
    xmlns="https://jakarta.ee/xml/ns/jakartaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
        https://jakarta.ee/xml/ns/jakartaee/web-facesconfig_4_1.xsd"
    version="4.1">

  <!-- Define our custom component -->
  <component>
    <description>
      A custom component for rendering
      user-selectable dates in various formats.
    </description>
    <display-name>My Custom Date</display-name>
    <component-type>Date</component-type>
    <component-class>
      com.example.components.DateComponent
    </component-class>
  </component>

  <!-- Define two renderers that know how to deal with dates -->
  <render-kit>
    <!-- No render-kit-id, so add them to default RenderKit -->
    <renderer>
      <display-name>Calendar Widget</display-name>
      <component-family>MyComponent</component-family>
      <renderer-type>MyCalendar</renderer-type>
      <renderer-class>
        com.example.renderers.MyCalendarRenderer
      </renderer-class>
    </renderer>

    <renderer>
      <display-name>Month/Day/Year</display-name>
      <renderer-type>MonthDayYear</renderer-type>
      <renderer-class>
        com.example.renderers.MonthDayYearRenderer
      </renderer-class>
    </renderer>
  </render-kit>
</faces-config>

Additional examples of configuration elements that might be found in application configuration resources are in Example NavigationHandler Configuration.

Annotations that correspond to and may take the place of entries in the Application Configuration Resources

An implementation must support several annotation types that take may take the place of entries in the Application Configuration Resources. The implementation requirements are specified in this section.

Requirements for scanning of classes for annotations

  • If the <faces-config> element in the WEB-INF/faces-config.xml file contains metadata-complete attribute whose value is “true”, the implementation must not perform annotation scanning on any classes except for those classes provided by the implementation itself. Otherwise, continue as follows.

  • If the runtime discovers a conflict between an entry in the Application Configuration Resources and an annotation, the entry in the Application Configuration Resources takes precedence.

  • All classes in WEB-INF/classes must be scanned.

  • For every jar in the application’s WEB-INF/lib directory, if the jar contains a “META-INF/faces-config.xml” file or a file that matches the regular expression “.*\.faces-config.xml” (even an empty one), all classes in that jar must be scanned.