Skip to content

Latest commit

 

History

History
199 lines (167 loc) · 6.19 KB

FacesMetadata.adoc

File metadata and controls

199 lines (167 loc) · 6.19 KB
Raw

Appendix A: Jakarta Faces Metadata

The XML Schema Definition for Application Configuration Resource web-facesconfig_4_1.xsd is included in a web browser optimized format along with the Javadoc. That is the canonical location of the schemas in the specification.

Required Handling of *-extension elements in the application configuration resources files

As specified in the XML Schema for Application Configuration Resources, many of the elements in the file have *-extension elements declared in a similar fashion to this one for the faces-config-extension:

<xsd:complexType name ="faces-config-extensionType">
  <xsd:annotation>
    <xsd:documentation>
      Extension element for faces-config. It may contain
      implementation specific content.
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
    <xsd:any namespace="##any" processContents="lax"
        minOccurs="0" maxOccurs="unbounded" />
  </xsd:sequence>
  <xsd:attribute name="id" type="xsd:ID" />
</xsd:complexType>

This section specifies the required handling of such elements.

Note that it is normal for an application to have several application configuration resources files. If multiple such resource files have conflicting *-extension elements, the last element processed takes precedence over preceding elements. Processing order can be controlled as specified in Ordering of Artifacts.

faces-config-extension handling

If an application configuration resource contains a faces-config-extension element, the children of the element must be inspected for containing well-formed XML conforming to the syntax specified in the following subsection(s). DTD syntax is used for convenience since the content of a *-extension element may not be constrained due to its declaration as containing <xsd:any>.

The facelets-processing element

DTD syntax..

<!ELEMENT facelets-processing (file-extension, process-as) >
<!ELEMENT file-extension ANY>
<!ELEMENT process-as ANY>

The <facelets-processing> element is used to affect the processing of Facelets VDL files. Therefore, this setting only applies to those requests that reach the Facelets ViewDeclarationLanguage implementation, as specified to the runtime via the jakarta.faces.FACELETS_VIEW_MAPPINGS and jakarta.faces.FACELETS_SUFFIX <context-param> entries. The specification defines three processing modes for Facelets files: Facelets XHTML syntax, XML View syntax, and Facelets JSPX syntax. This last syntax is intended to ease the migration to Facelets for applications already using the Jakarta Server Pages XML document syntax (also known as JSPX syntax). The affect on the processing of files in each of these three modes is specified in the following table.

Table 1. Valid <process-as> values and their implications on the processing of Facelet VDL files.
<process-as>html5</process-as>
HTML 5 (default)		 <process-as>xhtml</process-as>
Facelets XHTML		 <process-as>xml</process-as>
XML View		 <process-as>jspx</process-as>
Facelets JSPX

XML Doctype

Simplified to <!DOCTYPE html>

passed through

consumed

consumed

XML declaration

passed through

passed through

consumed

consumed

Processing instructions

passed through

passed through

consumed

consumed

CDATA section start and end tags

passed through

passed through

consumed

consumed

Escaping of inline text

escaped

escaped

escaped

not escaped

XML Comments

passed through

passed through

consumed

consumed

In the preceding table, “passed through” means that the content is passed through unmodified to the user agent. “consumed” means the content is silently consumed on the server. Note that for CDATA sections, the content of the CDATA section itself is passed through, even if the start and end tags should be consumed. “escaped” means that sensivite content in the response is automatically escaped: & becomes &, for example. “not escaped” means that such content is not escaped.

The content of the <file-extension> element is particular to the file extension of the physical resource for the Facelets VDL content, as specified in the jakarta.faces.FACELETS_VIEW_MAPPINGS and jakarta.faces.FACELETS_SUFFIX <context-param> elements. Consider the following example faces-config.xml.

<?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">
  <faces-config-extension>
    <facelets-processing>
      <file-extension>.jspx</file-extension>
      <process-as>jspx</process-as>
    </facelets-processing>
    <facelets-processing>
      <file-extension>.view.xml</file-extension>
      <process-as>xml</process-as>
    </facelets-processing>
  </faces-config-extension>
</faces-config>

And web.xml content

<context-param>
  <param-name>jakarta.faces.FACELETS_VIEW_MAPPINGS</param-name>
  <param-value>*.xhtml;*.view.xml;*.jspx</param-value>
</context-param>
<context-param>
  <param-name>jakarta.faces.FACELETS_SUFFIX</param-name>
  <param-value>.xhtml .view.xml .jspx</param-value>
</context-param>

This configuration states that .xhtml, .view.xml, and .jspx files must be treated as Facelets VDL files declares the processing mode of .jspx files to be jspx and declares the processing mode of .view.xml files to be xml.

XML Schema Definition For Facelet Taglib

The XML Schema Definition for Facelet Taglib web-facelettaglibrary_4_1.xsd is included in a web browser optimized format along with the Javadoc. That is the canonical location of the schemas in the specification.

XML Schema Definition For Partial Response

The XML Schema Definition for Partial Repsonse web-partialresponse_4_1.xsd is included in a web browser optimized format along with the Javadoc. That is the canonical location of the schemas in the specification.