Skip to content

Latest commit

 

History

History
2994 lines (2308 loc) · 98.5 KB

IntegrationWithJSP.adoc

File metadata and controls

2994 lines (2308 loc) · 98.5 KB
Raw

Integration with Jakarta Server Pages

Any Jakarta Faces implementations that claims compliance with this specification must include a complete Jakarta Server Pages implementation, and expose this implementation to the runtime of any Jakarta Faces application. Jakarta Faces applications, however, need not use Jakarta Server Pages as their View Declaration Language (VDL). In fact, a Jakarta Faces application is free to use whatever technology it likes for its VDL, as long as that VDL itself complies with the Jakarta Faces specification.

This version of the specification requires that implementations support two View Declaration Language syntaxes

  • Jakarta Server Pages

  • Facelets XHTML

This chapter describes the Jakarta Server Pages support required by Jakarta Server Faces. This Jakarta Server Pages support is enabled by providing custom actions so that a Jakarta Faces user interface can be easy defined in a Jakarta Server Pages page by adding tags corresponding to Jakarta Faces UI components. Custom actions provided by a Jakarta Faces implementation may be mixed with standard Jakarta Server Pages actions and custom actions from other libraries, as well as template text for layout, in the same Jakarta Server Pages page.

Facelets XHTML is specified in Facelets and its use in Web Applications. This chapters builds on the previous one. Facelets relies on concepts specified in Jakarta Server Pages.

For Jakarta Server Pages version 2.0 and onward, the file extension “.jsf” is reserved, and may optionally be used (typically by authoring tools) to represent VDL pages containing Jakarta Faces content 13. When running in a pre-Jakarta Server Pages 2.0 environment, Jakarta Server Pages authors must give their Jakarta Server Pages pages that contain Jakarta Faces content a filename ending in “.jsp”.

UIComponent Custom Actions

A Jakarta Server Pages custom action (aka custom tag or tag) for a Jakarta Faces UIComponent is constructed by combining properties and attributes of a Java UI component class with the rendering attributes supported by a specific Renderer from a concrete RenderKit. For example, assume the existence of a concrete RenderKit, HTMLRenderKit, which supports three Renderer types for the UIInput component:

Table 1. Example Renderer Types
RendererType Render-Dependent Attributes

“Text”

“size”

“Secret”

“size”, “secretChar”

“Textarea”

“size”, “rows”

The tag library descriptor (TLD) file for the corresponding tag library, then, would define three custom actions—one per Renderer. Below is an example of a portion of the custom action definition for the inputText tag 14:

<tag>
  <name>inputText</name>
  <tag-class>acme.html.tags.InputTag</tag-class>
  <bodycontent>JSP</bodycontent>

  <attribute>
    <name>id</name>
    <required>false</required>
    <rtexprvalue>true</rtexprvalue>
  </attribute>

  <attribute>
    <name>value</name>
    <required>false</required>
    <deferred-value>
      <type>java.lang.Object</type>
    <deferred-value>
  </attribute>

  <attribute>
    <name>size</name>
    <required>false</required>
    <deferred-value>
      <type>java.lang.Integer</type>
    <deferred-value>
  </attribute>
  ...
</tag>

Note that the size attribute is derived from the Renderer of type “Text”, while the id and value attributes are derived from the UIInput component class itself. Also note that the id attribute has rtexprvalue set to true. This is to allow ${} expressions in the id attribute so that <c:forEach> can include faces components that incorporate the index into their id. RenderKit implementors will generally provide a Jakarta Server Pages tag library which includes component custom actions corresponding to each of the component classes (or types) supported by each of the RenderKit’s Renderers. See RenderKit and Renderer for details on the RenderKit and Renderer APIs. Jakarta Faces implementations must provide such a tag library for the standard HTML RenderKit (see Standard HTML RenderKit Tag Library).

Using UIComponent Custom Actions in Jakarta Server Pages Pages

The following subsections define how a page author utilizes the custom actions provided by the RenderKit implementor in the Jakarta Server Pages pages that create the user interface of a Jakarta Faces-based web application.

Declaring the Tag Libraries

This specification hereby reserves the following Uniform Resource Identifier (URI) values to refer to the standard tag libraries for the custom actions defined by Jakarta Server Faces:

The page author must use the standard Jakarta Server Pages taglib directive to declare the URI of each tag library to be utilized, as well as the prefix used (within this page) to identify custom actions from this library. For example,

<%@ taglib uri=”http://java.sun.com/jsf/core” prefix=”f” %>
<%@ taglib uri=”http://java.sun.com/jsf/html” prefix=”h” %>

declares the unique resource identifiers of the tag libraries being used, as well as the prefixes to be used within the current page for referencing actions from these libraries 15.

Including Components in a Page

A Jakarta Faces UIComponent custom action can be placed at any desired position in a Jakarta Server Pages page that contains the taglib directive for the corresponding tag library, subject to the following restrictions:

  • When using a single Jakarta Server Pages page to create the entire view, Jakarta Faces component custom actions must be nested inside the <f:view> custom action from the Jakarta Faces Core Tag Library.

The following example illustrates the general use of a UIComponent custom action in a Jakarta Server Pages page. In this scenario:

<h:inputText id=”username” value=”#{logonBean.username}”/>

represents a UIInput field, to be rendered with the “Text” renderer type, and points to the username property of a backing bean for the actual value. The id attribute specifies the component id of a UIComponent instance, from within the component tree, to which this custom action corresponds. If no id is specified, one will be automatically generated by the custom action implementation.

Custom actions that correspond to Jakarta Faces UIComponent instances must subclass jakarta.faces.webapp.UIComponentELTag (see UIComponentELTag)

During the Render Response phase of the request processing lifecycle, the appropriate encoding methods of the component (or its associated Renderer) will be utilized to generate the representation of this component in the response page. In addition, the first time a particular page is rendered, the component tree may also be dynamically constructed.

All markup other than UIComponent custom actions is processed by the Jakarta Server Pages container, in the usual way. Therefore, you can use such markup to perform layout control, or include non-Jakarta Faces content, in conjunction with the actions that represent UI components.

Creating Components and Overriding Attributes

As UIComponent custom actions are encountered during the processing of a Jakarta Server Pages page, the custom action implementation must check the component tree for the existence of a corresponding UIComponent, and (if not found) create and configure a new component instance corresponding to this custom action. The details of this process (as implemented in the findComponent() method of UIComponentClassicTagBase, for easy reuse) are as follows:

  • If the component associated with this component custom action has been identified already, return it unchanged.

  • Identify the component identifier for the component related to this UIComponent custom action, as follows:

    • If the page author has specified a value for the id attribute, use that value.

    • Otherwise, call the createUniqueId() method of the UIViewRoot at the root of the component tree for this view, and use that value.

  • If this UIComponent custom action is creating a facet (that is, we are nested inside an <f:facet> custom action), determine if there is a facet of the component associated with our parent UIComponent custom action, with the specified facet name, and proceed as follows:

    • If such a facet already exists, take no additional action.

    • If no such facet already exists, create a new UIComponent (by calling the createComponent() method on the Application instance for this web application, passing the value returned by getComponentType(), set the component identifier to the specified value, call setProperties() passing the new component instance, and add the new component as a facet of the component associated with our parent UIComponent custom action, under the specified facet name.

  • If this UIComponent custom action is not creating a facet (that is, we are not nested inside an <f:facet> custom action), determine if there is a child component of the component associated with our parent UIComponent custom action, with the specified component identifier, and proceed as follows:

    • If such a child already exists, take no additional action.

    • If no such child already exists, create a new UIComponent (by calling the createComponent() method on the Application instance for this web application, passing the value returned by getComponentType(), set the component identifier to the specified value, call setProperties() passing the new component instance, and add the new component as a child of the component associated with our parent UIComponent custom action.

Deleting Components on Redisplay

In addition to the support for dynamically creating new components, as described above, UIComponent custom actions will also delete child components (and facets) that are already present in the component tree, but are not rendered on this display of the page. For example, consider a UIComponent custom action that is nested inside a Jakarta Tag’s <c:if> custom action whose condition is true when the page is initially rendered. As described in this section, a new UIComponent will have been created and added as a child of the UIComponent corresponding to our parent UIComponent custom action. If the page is re-rendered, but this time the <c:if> condition is false, the previous child component will be removed.

Representing Component Hierarchies

Nested structures of UIComponent custom actions will generally mirror the hierarchical relationships of the corresponding UIComponent instances in the view that is associated with each Jakarta Server Pages page. For example, assume that a UIForm component (whose component id is logonForm) contains a UIPanel component used to manage the layout. You might specify the contents of the form like this:

<h:form id=”logonForm”>
  <h:panelGrid columns=”2”>
    <h:outputLabel for=”username”>
      <h:outputText value=”Username:”/>
    </h:outputLabel>
    <h:inputText id=”username” value=”#{logonBean.username}”/>
    <h:outputLabel for=”password”>
      <h:outputText value=”Password:”/>
    </h:outputLabel>
    <h:inputSecret id=”password” value=”#{logonBean.password}”/>
    <h:commandButton id=”submitButton” type=”SUBMIT”
        action=”#{logonBean.logon}”/>
    <h:commandButton id=”resetButton” type=”RESET”/>
  </h:panelGrid>
</h:form>

Registering Converters, Event Listeners, and Validators

Each Jakarta Faces implementation is required to provide the core tag library (see Jakarta Faces Core Tag Library), which includes custom actions that (when executed) create instances of a specified Converter, ValueChangeListener, ActionListener or Validator implementation class, and register the created instance with the UIComponent associated with the most immediately surrounding UIComponent custom action.

Using these facilities, the page author can manage all aspects of creating and configuring values associated with the view, without having to resort to Java code. For example:

<h:inputText id=”username” value=”#{logonBean.username}”>
  <f:validateLength minimum=”6”/>
</h:inputText>

associates a validation check (that the value entered by the user must contain at least six characters) with the username UIInput component being described.

Following are usage examples for the valueChangeListener and actionListener custom actions.

<h:inputText id=”maxUsers”>
  <f:convertNumber integerOnly=”true”/>
  <f:valueChangeListener type="custom.MyValueChangeListener"/>
</h:inputText>
<h:commandButton label="Login">
  <f:actionListener type="custom.MyActionListener"/>
</h:commandButton>

This example causes a Converter and a ValueChangeListener of the user specified type to be instantiated and added as to the enclosing UIInput component, and an ActionListener is instantiated and added to the enclosing UICommand component. If the user specified type does not implement the proper listener interface a JSPException must be thrown.

Using Facets

A Facet is a subordinate UIComponent that has a special relationship to its parent UIComponent, as described in Facet Management. Facets can be defined in a Jakarta Server Pages page using the <f:facet> custom action. Each facet action must have one and only one child UIComponent custom action 16. For example:

<h:dataTable ...>
  <f:facet name=”header”>
    <h:outputText value=”Customer List”/>
  </f:facet>
  <h:column>
    <f:facet name=”header”>
      <h:outputText value=”Account Id”/>
    </f:facet>
    <h:outputText id=”accountId” value= ”#{customer.accountId}”/>
  </h:column>
  ...
</h:dataTable>

Interoperability with Jakarta Server Pages Template Text and Other Tag Libraries

It is permissible to use other tag libraries, such as the Jakarta Standard Tag Library (Jakarta Tags) in the same Jakarta Server Pages page with UIComponent custom actions that correspond to Jakarta Faces components, subject to certain restrictions. When Jakarta Faces component actions are nested inside custom actions from other libraries, or combined with template text, the following behaviors must be supported:

  • Jakarta Faces component custom actions nested inside a custom action that conditionally renders its body (such as Jakarta Tags’s <c:if> or <c:choose>) must contain a manually assigned id attribute.

  • Interoperation with the Jakarta Tag’s Internationalization-Capable Formatting library (typically used with the “fmt” prefix) is restricted as follows:

    • The <fmt:parseDate> and <fmt:parseNumber> custom actions should not be used. The corresponding Jakarta Faces facility is to use an <h:inputText> component custom action with an appropriate DateTimeConverter or NumberConverter.

    • The <fmt:requestEncoding> custom action should not be used. By the time it is executed, the request parameters will have already been parsed, so any change in the setting here will have no impact. Jakarta Faces handles character set issues automatically in most cases. To use a fixed character set in exceptional circumstances, use the a “<%@ page contentType=”[content-type];[charset]” %>” directive.

    • The <fmt:setLocale/> custom action should not be used. Even though it might work in some circumstances, it would result in Jakarta Faces and Jakarta Tags assuming different locales. If the two locales use different character sets, the results will be undefined. Applications should use Jakarta Faces facilities for setting the locale property on the UIViewRoot component to change locales for a particular user.

Composing Pages from Multiple Sources

Jakarta Server Pages pages can be composed from multiple sources using several mechanisms:

  • The <%@include%> directive performs a compile-time inclusion of a specified source file into the page being compiled 17. From the perspective of Jakarta Faces, such inclusions are transparent—the page is compiled as if the inclusions had been performed before compilation was initiated.

  • Several mechanisms (including the <jsp:include> standard action, the Jakarta Tag’s <c:import> custom action when referencing a resource in the same webapp, and a call to RequestDispatcher.include() for a resource in the same webapp) perform a runtime dynamic inclusion of the results of including the response content of the requested page resource in place of the include action. Any Jakarta Faces components created by execution of Jakarta Faces component custom actions in the included resource will be grafted onto the component tree, just as if the source text of the included page had appeared in the calling page at the position of the include action.

  • For mechanisms that aggregate content by other means (such as use of an HttpURLConnection, a RequestDispatcher.include() on a resource from a different web application, or accessing an external resource with the Jakarta Tag’s <c:import> custom action on a resource from a different web application, only the response content of the aggregation request is available. Therefore, any use of Jakarta Faces components in the generation of such a response are not combined with the component tree for the current page.

UIComponent Custom Action Implementation Requirements

The custom action implementation classes for UIComponent custom actions must conform to all of the requirements defined in the Jakarta Server Pages Specification. In addition, they must meet the following Jakarta Faces-specific requirements:

  • Extend the UIComponentELTag or UIComponentELBodyTag base class, so that Jakarta Faces implementations can recognize UIComponent custom actions versus others.

  • Provide a public getComponentType() method that returns a String-valued component type registered with the Application instance for this web application. The value returned by this method will be passed to Application.createComponent() when a new UIComponent instance associated with this custom action is to be created.

  • Provide a public getRendererType() method that returns a String-valued renderer type registered with the RenderKit instance for the currently selected RenderKit, or null if there should be no associated Renderer. The value returned by this method will be used to set the rendererType property of any UIComponent created by this custom action.

  • Provide setter methods taking a jakarta.el.ValueExpression or jakarta.el.MethodExpression parameter for all set-able (from a custom action) properties of the corresponding UIComponent class, and all additional set-able (from a custom action) attributes supported by the corresponding Renderer.

  • On the method that causes a UIComponent instance to be added to the tree, verify that the component id of that UIComponent is unique within the scope of the closest ancestor component that is a NamingContainer. If this constraint is not met, throw JspException.

  • Provide a protected setProperties() method of type void that takes a UIComponent instance as parameter. The implementation of this method must perform the following tasks:

    • Call super.setProperties(), passing the same UIComponent instance received as a parameter.

    • For each non-null custom action attribute that corresponds to a property based attribute to be set on the underlying component, call either setValueExpression() or getAttributes().put(), depending on whether or not a value expression was specified as the custom action attribute value (performing any required type conversion). For example, assume that title is the name of a render-dependent attribute for this component:

      public void setTitle(jakarta.el.ValueExpression title) {
  this.title = title;
}

protected void setProperties(UIComponent component) throws JspException {
  super.setProperties(component);
  if (title != null) {
    try {
      component.setValueExpression(“title”, title);
    } catch (ELException e) {
      throw new JspException(e);
    }
  ...
}

    • For each non-null custom action attribute that corresponds to a method based attribute to be set on the underlying component, the value of the attribute must be a method reference expression. We have a number of wrapper classes to turn a MethodExpression into the appropriate listener. For example, assume that valueChangeListener is the name of an attribute for this component:

      public void setValueChangeListener(jakarta.el.MethodExpression me) {
  valueChangeListener = me;
}

protected void setProperties(UIComponent component) {
  super.setProperties(component);
  MethodExpressionValueChangeListener listener =
      new MethodExpressionValueChangeListener(valueChangeListener);
  input.addValueChangeListener(listener);
  ...
}

    • Non-null custom action attributes that correspond to a writable property to be set on the underlying component are handled in a similar fashion. For example, assume a custom action for the UIData component is being created that needs to deal with the rows property (which is of type int):

      public void setRows(jakarta.el.ValueExpression rows) {
  this.rows = rows;
}

protected void setProperties(UIComponent component) {
  super.setProperties(component);
  if (rows != null) {
    try {
      component.setValueExpression(“rows”, rows);
    } catch (ELException e) {
      throw new JspException(e);
    }
  }
  ...
}

  • Optionally, provide a public release() method of type void, taking no parameters, to be called when the Jakarta Server Pages page handler releases this custom action instance. If implemented, the method must perform the following tasks:

    • Call super.release() to invoke the superclass’s release functionality.

    • Clear the instance variables representing the values for set-able custom action attributes (for example, by setting String values to null).

  • Optionally provide overridden implementations for the following method to fine tune the behavior of your UIComponent custom action implementation class: encodeComponent().

It is technically possible to override other public and protected methods of the UIComponentELTag or UIComponentBodyELTag base class; however, it is likely that overriding these methods will interfere with the functionality that other portions of the Jakarta Faces implementation are assuming to be present, so overriding these methods is strongly discouraged.

The definition of each UIComponent custom action in the corresponding tag library descriptor (TLD) must conform to the following requirements:

  • The <body-content> element for the custom action itself must specify JSP.

  • For each attribute that is intended to be passed on to the underlying faces component:

    • The attribute may not be named id. This name is reserved for Faces use.

    • If the attribute represents a method expression, it must have a <deferred-method> element containing a <method-signature> element that describes the signature of the method pointed to by the expression, as described in section JSP.C.1 in the Jakarta Server Pages 3.0 specification.

    • Otherwise, the attribute must be a value based attribute, and must have a <deferred-value> element containing a <type> element which describes the expected type to which the expression will evaluate. Please see section JSP.C.1 in the Jakarta Server Pages 3.0 specification for details.

Considerations for Custom Actions written for pre-Jakarta Faces JSF 1.1 and 1.0

Versions 1.0 and 1.1 of the pre-Jakarta Faces spec included their own EL that happend to have similar semantics to the Jakarta Server Pages EL, but the implementation was bundled into the Faces implementation. This version leverages the Jakarta Expression Language facility. This change has necessitated deprecating some methods and classes, including the classes Custom Actions as their base class for tags that expose Faces components to the Jakarta Server Pages page. This section explains how custom actions built for Faces 1.0 and 1.1 can continue to run Faces 1.2.

Past and Present Tag constraints

Faces 1.0 and 1.1 were targeted at pre-Jakarta Server Pages JSP version 1.2 and Servlet version 2.3. This decision brought about several constraints for faces tag attributes:

  • all tag attributes had to declare rtexprvalue to be false.

  • all tag attributes had to take the type java.lang.String.

  • Faces had to choose a new expression delimiter, #{} , to prevent the Jakarta Server Pages container from prematurely evaluating the expression. This became known as deferred evaluation.

  • Because Faces had introduced its own version of the EL, the custom tag action layer had to do a lot of extra work to “value binding enable” its attributes, calling Faces EL APIs to turn the String attribute value into an instance of ValueBinding or MethodBinding.

  • Faces provided the UIComponentTag and UIComponentBodyTag base classes that were designed to adhere to the above rules.

Tags that use the Jakarta Expression Language have the following constraints:

  • all tag attributes must not have an rtexprvalue attribute

  • all tag attributes must accept jakarta.el.ValueExpression or jakarta.el.MethodExpression as their type (depending on if the attribute refers to a method or a value).

  • all tag attributes (except for id) must have a <deferred-value> or <deferred-method> element. See Jakarta Faces Core Tag Library in the description for the Attributes column.

  • The Jakarta Server Pages Container will hand the tag setter a jakarta.el.ValueExpression or jakarta.el.MethodExpression directly, so there is no need to use the Faces API to create them.

  • The UIComponentTag and UIComponentBodyTag classes are deprecated and Faces provides new base class, UIComponentELTag to the new rules for taglibs in Faces.

It’s very important to note that we still are using #\{} as the delimiters for expressions that appear in a Jakarta Server Pages page in the value of a tag attribute, but when the Java API is used, either $\{} or #\{} may be used for delimiters.

Faces 1.0 and 1.1 Taglib migration story

It is imperative that applications written for Faces 1.0 and 1.1 continue to run on Faces 1.2. From the JSP perspective, this means

  1. that Jakarta Server Pages pages using the standard h: and f: tags must work without change

  2. that Jakarta Server Pages pages using custom faces taglibs must work without change

The first item is enabled by re-writing the h: and f: taglibs which must be provided by the Faces implementor.

The second item is enabled as follows. For discussion the term jsp-version is used to denote the jsp-version element in a Jakarta Server Pages 1.2 (and earlier) TLD, as well as the version element in a Jakarta Server Pages 2.0 (and later) TLD. The Jakarta Server Pages container must examine the jsp-version element of the TLD for a taglib. If the jsp-version is less than 2.1, the taglib is deemed to be a Faces 1.0 or 1.1 taglib and the container must ignore all expressions that use #\{} as delimiters, except for those appearing in tag attribute with a property setter that takes a jakarta.el.ValueExpression or jakarta.el.MethodExpression. If the jsp-version is 2.1 or greater, the taglib is deemed to be a Faces 1.2 or later taglib and the Jakarta Server Pages container is aware of #\{} expressions.

Jakarta Faces Core Tag Library

[P1-start Jakarta Faces taglib requirements] All Jakarta Faces implementations must provide a tag library containing core actions (described below) that are independent of a particular RenderKit. The corresponding tag library descriptor must meet the following requirements:

  • Must declare a tag library version (<tlib-version>) value of 1.2.

  • Must declare a URI (<uri>) value of http://java.sun.com/jsf/core.

  • Must be included in the META-INF directory of a JAR file containing the corresponding implementation classes, suitable for inclusion with a web application, such that the tag library descriptor will be located automatically by the algorithm described in Section 7.3 of the _ Jakarta Server Pages Specification_ (version 2.1). [P1-end]

[P1-start no javascript in jakarta_faces_core taglib] The tags in the implementation of this tag library must not cause JavaScript to be rendered to the client. Doing so would break the requirement that the Jakarta Faces Core Tag library is independent of any specific RenderKit. [P1-end]

Each custom action included in the Jakarta Faces Core Tag Library is documented in a subsection below, with the following outline for each action:

  • Name—The name of this custom action, as used in a Jakarta Server Pages page.

  • Short Description—A summary of the behavior implemented by this custom action.

  • Syntax—One or more examples of using this custom action, with the required and optional sets of attributes that may be used together. If the tag may have an id attribute, its value may be a literal string, or an immediate, non-defferd expression, such as “userName” or “user${i}” without the quotes.

  • Body Content—The type of nested content for this custom action, using one of the standard values empty, JSP, or tagdependent as described in the Jakarta Server Pages specification. This section also describes restrictions on the types of content (template text, Jakarta Faces core custom actions, Jakarta Faces UIComponent custom actions, and/or other custom actions) that can be nested in the body of this custom action.

  • Attributes—A table containing one row for each defined attribute for this custom action. The following columns provide descriptive information about each attribute:

    • Name—Name of this attribute, as it must be used in the page. If the name of the attribute is in italics, it is required.

    • Expr—The type of dynamic expression (if any) that can be used in this attribute value. Legal values are VE (this may be a literal or a value expression), ME (this may be a method expression), or NONE (this attribute accepts literal values only). If the Expr column is VE, the corresponding <attribute> declaration in the TLD must contain a <deferred-value> element, optionally containing a <type> element that contains the fully qualified java class name of the expected type of the expression. If <type> is omitted, Object.class is assumed. If the Expr column is ME, the corresponding <attribute> declaration in the TLD must contain a <deferred-method> element, containing a <method-signature> element that describes the exact method signature for the method. In this case, the Description column the description column contains the method signature.

    • Type—Fully qualified Java class or primitive type of this attribute.

    • Description—The functional meaning of this attribute’s value.

  • Constraints—Additional constraints enforced by this action, such as combinations of attributes that may be used together.

  • Description—Details about the functionality provided by this custom action.

<f:actionListener>

Register an ActionListener instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:actionListener type=”fully-qualified-classname” binding=”value Expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

type

VE

String

Fully qualified Java class name of an ActionListener to be created and registered

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.event.ActionListener
Constraints

  • Must be nested inside a UIComponent custom action.

  • The corresponding UIComponent implementation class must implement ActionSource, and therefore define a public addActionListener() method that accepts an ActionListener parameter.

  • The specified listener class must implement jakarta.faces.event.ActionListener.

  • type and/or binding must be specified.

[P1-start f:actionListener constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement ActionSource, or the specified listener class does not implement jakarta.faces.event.ActionListener, throw a JspException. [P1-end] Note that if the binding attribute is used, the scope of the ValueExpression must be chosen carefully so as not to introduce undesireable results. In general, when using the binding attribute, do not point to beans in request or narrower scope.

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, check the binding attribute.

If binding is set, create a ValueExpression by invoking Application.createValueExpression() with binding as the expression argument, and Object.class as the expectedType argument. Use the ValueExpression to obtain a reference to the ActionListener instance. If there is no exception thrown, and ValueExpression.getValue() returned a non-null object that implements jakarta.faces.event.ActionListener, register it by calling addActionListener(). If there was an exception thrown, rethrow the exception as a JspException.

If the listener instance could not be created, check the type attribute. If the type attribute is set, instantiate an instance of the specified class, and register it by calling addActionListener(). If the binding attribute was also set, evaluate the expression into a ValueExpression and store the listener instance by calling setValue() on the ValueExpression. If there was an exception thrown, rethrow the exception as a JspException.

As an alternative to using the binding and/or type attributes, you may also register a method in a backing bean class to receive ActionEvent notifications, by using the actionListener attribute on the corresponding UIComponent custom action.

<f:attribute>

Add an attribute or ValueExpression on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:attribute name=”attribute-name” value=”attribute-value”/>

Body Content

empty.

Attributes
Name Expr Type Description

name

VE

String

Name of the component attribute to be set

value

VE

Object

Value of the component attribute to be set
Constraints

  • Must be nested inside a UIComponent custom action.

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). Call the getValue() method on the argument name to obtain the name of the attribute. If the associated component already has a component attribute with that name, take no action. Otherwise, call the isLiteralText() method on the argument value. If it returns true, store the value in the component’s attribute Map under the name derived above. If it returns false, store the ValueExpression in the component’s ValueExpression Map under the name derived above.

There is no standard implementation class for this action. It must be provided by the implementation.

<f:convertDateTime>

Register a DateTimeConverter instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:convertDateTime

  • [dateStyle=”{default|short|medium|long|full}”]

  • [locale=”{locale|string}”]

  • [pattern=”pattern”]

  • [timeStyle=”{default|short|medium|long|full}”]

  • [timeZone=”{timeZone|string}”]

  • [type=”{date|time|both|localDate|localDateTime|localTime|
    offsetTime|offsetDateTime|zonedDateTime}”]

  • [binding=”Value Expression”]/>

Body Content

empty.

Attributes
Name Expr Type Description

date-Style

VE

String

Predefined formatting style which determines how the date component of a date string is to be formatted and parsed. Applied only if type is "date", "both", "localDate", "localDateTime", or "zonedDateTime". Valid values are "default", "short", "medium", "long", and "full". Default value is "default". If a java.time formatter is being used, yet the dateStyle is set to "default", the value "medium" is assumed.

locale

VE

Locale or String

Locale whose predefined styles for dates and times are used during formatting or parsing. If not specified, the Locale returned by FacesContext.getViewRoot().getLocale() will be used. Value must be either a VE expression that evaluates to a java.util.Locale instance, or a String that is valid to pass as the first argument to the constructor java.util.Locale(String language, String country). The empty string is passed as the second argument.

pattern

VE

String

Custom formatting pattern which determines how the date/time string should be formatted and parsed.

time-Style

VE

String

Predefined formatting style which determines how the time component of a date string is to be formatted and parsed. Applied only if type is "time", "both", "localTime" or "offsetTime". Valid values are "default", "short", "medium", "long", and "full". Default value is "default". If a java.time formatter is being used, yet the timeStyle is set to "default", the value "medium" is assumed.

time-Zone

VE

timezone or String

Time zone in which to interpret any time information in the date string. Value must be either a VE expression that evaluates to a java.util.TimeZone instance, or a String that is a timezone ID as described in the javadocs for java.util.TimeZone.getTimeZone().

type

VE

String

Specifies what contents the string value will be formatted to include, or parsed expecting. Valid values are "date", "time", "both", "localDate", "localDateTime", "localTime", "offsetTime", "offsetDateTime", and "zonedDateTime". The values starting with "local", "offset" and "zoned" correspond to Java SE 8 Date Time API classes in package java.time with the name derived by upper casing the first letter. For example, java.time.LocalDate for the value "localDate". Default value is "date".

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Converter
Constraints

  • Must be nested inside a UIComponent custom action whose component class implements ValueHolder, and whose value is a java.util.Date (or appropriate subclass).

  • If pattern is specified, the pattern syntax must use the pattern syntax specified by java.text.SimpleDateFormat or java.time.format.DateTimeFormatter depending on the value of type.

  • If pattern is not specified, formatted strings will contain a date value, a time value, or both depending on the specified type. When date or time values are included, they will be formatted according to the specified dateStyle and timeStyle, respectively.

  • if type is not specified:

    • if dateStyle is set and timeStyle is not, type defaults to date

    • if timeStyle is set and dateStyle is not, type defaults to time

    • if both dateStyle and timeStyle are set, type defaults to both

[P1-start f:convertDateTime constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement ValueHolder, throw a JspException [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createConverter() and register the returned Converter instance on the associated UIComponent.

[P1-start f:convertDateTime implementation requirements ]The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ConverterELTag.

  • The createConverter() method must:

    • If binding is non-null, call getValue() on it to obtain a reference to the Converter instance. If there is no exception thrown, and binding.getValue() returned a non-null object that implements jakarta.faces.convert.Converter, it must then cast the returned instance to jakarta.faces.convert.DateTimeConverter and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

    • use the converterId if the converter instance could not be created from the binding attribute. Call the createConverter() method of the Application instance for this application, passing converter id “jakarta.faces.DateTime”. If the binding attribute was also set, store the converter instance by calling binding.setValue(). It must then cast the returned instance to jakarta.faces.convert.DateTimeConverter and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

  • If the type attribute is not specified, it defaults as follows:

    • If dateStyle is specified but timeStyle is not specified, default to date.

    • If dateStyle is not specified but timeStyle is specified, default to time.

    • If both dateStyle and timeStyle are specified, default to both. [P1-end]

<f:convertNumber>

Register a NumberConverter instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:convertNumber

  • [currencyCode=”currencyCode”]

  • [currencySymbol=”currencySymbol”]

  • [groupingUsed=”{true|false}”]

  • [integerOnly=”{true|false}”]

  • [locale=”locale”]

  • [maxFractionDigits=”maxFractionDigits”]

  • [maxIntegerDigits=”maxIntegerDigits”]

  • [minFractionDigits=”minFractionDigits”]

  • [minIntegerDigits=”minIntegerDigits”]

  • [pattern=”pattern”]

  • [type=”{number|currency|percent}”]

  • [binding=”Value Expression”]/>

Body Content

empty.

Attributes
Name Expr Type Description

currencyCode

VE

String

ISO 4217 currency code, applied only when formatting currencies.

currencySymbol

VE

String

Currency symbol, applied only when formatting currencies.

groupingUsed

VE

boolean

Specifies whether formatted output will contain grouping separators.

integerOnly

VE

boolean

Specifies whether only the integer part of the value will be parsed.

locale

VE

java.util.Locale

Locale whose predefined styles for numbers are used during formatting or parsing. If not specified, the Locale returned by FacesContext.getViewRoot().getLocale() will be used.

maxFractionDigits

VE

int

Maximum number of digits that will be formatted in the fractional portion of the output.

maxIntegerDigits

VE

int

Maximum number of digits that will be formatted in the integer portion of the output

minFractionDigits

VE

int

Minimum number of digits that will be formatted in the fractional portion of the output.

minIntegerDigits

VE

int

Minimum number of digits that will be formatted in the integer portion of the output.

pattern

VE

String

Custom formatting pattern which determines how the number string should be formatted and parsed.

type

VE

String

Specifies whether the value will be parsed and formatted as a number, currency, or percentage.

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Converter
Constraints

  • Must be nested inside a UIComponent custom action whose component class implements ValueHolder, and whose value is a numeric wrapper class or primitive.

  • If pattern is specified, the pattern syntax must use the pattern syntax specified by java.text.DecimalFormat.

  • If pattern is not specified, formatting and parsing will be based on the specified type.

[P1-start f:convertNumber constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement ValueHolder, throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createConverter() and register the returned Converter instance on the associated UIComponent.

[P1-start f:convertNumber implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ConverterELTag.

  • The createConverter() method must:

  • If binding is non-null, call binding.getValue() to obtain a reference to the Converter instance. If there is no exception thrown, and binding.getValue() returned a non-null object that implements jakarta.faces.convert.Converter, it must then cast the returned instance to jakarta.faces.convert.NumberConverter and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

  • use the converterId if the converter instance could not be created from the binding attribute. Call the createConverter() method of the Application instance for this application, passing converter id “jakarta.faces.Number”. If the binding attribute was also set, store the converter instance by calling binding.setValue(). It must then cast the returned instance to jakarta.faces.convert.NumberConverter and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException. [P1-end]

<f:converter>

Register a named Converter instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:converter converterId=”converterId” binding=”Value Expression”/>

Body Content

empty

Attributes
Name Expr Type Description

converterId

VE

String

Converter identifier of the converter to be created.

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Converter
Constraints

  • Must be nested inside a UIComponent custom action whose component class implements ValueHolder.

  • converterId and/or binding must be specified.

[P1-start f:converter constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement ValueHolder, throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createConverter() and register the returned Converter instance on the associated UIComponent.

[P1-start f:converter implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ConverterJspTag.

  • The createConverter() method must:

    • If binding is non-null, call binding.getValue() to obtain a reference to the Converter instance. If there is no exception thrown, and binding.getValue() returned a non-null object that implements jakarta.faces.convert.Converter, register it by calling setConverter(). If there was an exception thrown, rethrow the exception as a JspException. Use the converterId attribute if the converter instance could not be created from the binding attribute. If the converterId attribute is set, call the createConverter() method of the Application instance for this application, passing converter id specified by their converterId attribute. If the binding attribute was also set, store the converter instance by calling binding.setValue(). Register the converter instance by calling setConverter(). If there was an exception thrown, rethrow the exception as a JspException. [P1-end]

<f:facet>

Register a named facet (see Facet Management) on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:facet name=”facet-name”/>

Body Content

JSP. However, only a single UIComponent custom action (and any related nested Jakarta Faces custom actions) is allowed; no template text or other custom actions may be present.

Attributes
Name Expr Type Description

name

NONE

String

Name of the facet to be created
Constraints

  • [P1-start f:facet constraints] Must be nested inside a UIComponent custom action.

  • Exactly one UIComponent custom action must be nested inside this custom action (although the nested component custom action could itself have nested children). [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the associated component does not already have a facet with a name specified by this custom action’s name attribute, create a facet with this name from the UIComponent custom action that is nested within this custom action.

[P1-start f:facet implementation] The implementation class must be, or extend, jakarta.faces.webapp.FacetTag. [P1-end]

<f:loadBundle>

Load a resource bundle localized for the locale of the current view, and expose it (as a Map) in the request attributes for the current request.

Syntax

<f:loadBundle basename=”resource-bundle-name” var=”attributeKey”/>

Body Content

empty

Attributes
Name Expr Type Description

basename

VE

String

Base name of the resource bundle to be loaded.

var

NONE

String

Name of a request scope attribute under which the resource bundle will be exposed as a Map.
Constraints

  • [P1-start f:loadBundle constraints] Must be nested inside an <f:view> custom action. [P1-end]

Description

Load the resource bundle specified by the basename attribute, localized for the Locale of the UIViewRoot component of the current view, and expose its key-values pairs as a Map under the attribute key specified by the var attribute. In this way, value binding expressions may be used to conveniently retrieve localized values. If the named bundle is not found, throw JspException.

If the get() method for the Map instance exposed by this custom action is passed a key value that is not present (that is, there is no underlying resource value for that key), the literal string “???foo???” (where “foo” is replaced by the key the String representation of the key that was requested) must be returned, rather than the standard Map contract return value of null.

<f:param>

Add a child UIParameter component to the UIComponent associated with the closest parent UIComponent custom action.

Syntax
Syntax 1: Unnamed value

<f:param [id=”componentIdOrImmediateExpression”]

  • value=”parameter-value”

  • [binding=”componentReference”] />

Syntax 2: Named value

<f:param [id=”componentIdOrImmediateExpression”]

  • [binding=”componentReference”]

  • name=”parameter-name” value=”parameter-value”/>

Body Content

empty.

Attributes
Name Expr Type Description

binding

VE

ValueExpression

ValueExpression expression to a backing bean property bound to the component instance for the UIComponent created by this custom action

id

NONE

String

Component identifier of a UIParameter component

name

VE

String

Name of the parameter to be set

value

VE

String

Value of the parameter to be set
Constraints

  • [P1-start f:param constraints] Must be nested inside a UIComponent custom action. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create a new UIParameter component, and attach it as a child of the associated UIComponent. It is up to the parent UIComponent to determine how it will handle its UIParameter children.

[P1-start f:param implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.UIComponentELTag.

  • The getComponentType() method must return “Parameter”.

  • The getRendererType() method must return null. [P1-end]

<f:phaseListener>

Register a PhaseListener instance on the UIViewRoot associated with the closest parent UIViewRoot custom action.

Syntax

<f:phaseListener type=”fully-qualified-classname” binding=”Value expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

type

VE

String

Fully qualified Java class name of an PhaseListener to be created and registered

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.event.PhaseListener
Constraints

  • [P1-start f:phaseListener constraints] Must be nested inside a UIViewRoot custom action.

  • The specified listener class must implement jakarta.faces.event.PhaseListener.

  • type and/or binding must be specified. [P1-end]

Description

Locate the one and only UIViewRoot custom action instance by walking up the tag tree until you find a UIComponentTagBase instance that has no parent. If the getCreated() method of this instance returns true, check the binding attribute.

If binding is set, call binding.getValue() to obtain a reference to the PhaseListener instance. If there is no exception thrown, and binding.getValue() returned a non-null object that implements jakarta.faces.event.PhaseListener, register it by calling addPhaseListener(). If there was an exception thrown, rethrow the exception as a JspException.

If the listener instance could not be created, check the type attribute. If the type attribute is set, instantiate an instance of the specified class, and register it by calling addPhaseListener(). If the binding attribute was also set, store the listener instance by calling binding.setValue(). If there was an exception thrown, rethrow the exception as a JspException.

<f:selectItem>

Add a child UISelectItem component to the UIComponent associated with the closest parent UIComponent custom action.

Syntax
Syntax 1: Directly Specified Value

<f:selectItem [id=”componentIdOrImmediateExpression”]

  • [binding=”componentReference”]

  • [itemDisabled=”{true|false}”]

  • itemValue=”itemValue”

  • itemLabel=”itemLabel”

  • [itemDescription=”itemDescription”] />

Syntax 2: Indirectly Specified Value

<f:selectItem [id=”componentIdOrImmediateExpression”]

  • [binding=”componentReference”]

  • value=”selectItemValue”/>

Body Content

empty

Attributes
Name Expr Type Description

binding

VE

ValueExpression

ValueExpression expression to a backing bean property bound to the component instance for the UIComponent created by this custom action.

id

NONE

String

Component identifier of a UISelectItem component.

itemDescription

VE

String

Description of this option (for use in development tools).

itemDisabled

VE

boolean

Flag indicating whether the option created by this component is disabled.

itemLabel

VE

String

Label to be displayed to the user for this option.

itemValue

VE

Object

Value to be returned to the server if this option is selected by the user.

value

VE

jakarta.faces.model.SelectItem

Value binding pointing at a SelectItem instance containing the information for this option.

escape

VE

boolean

ValueExpression pointing to a boolean that tells whether or not the label of this selectItem should be escaped per HTML rules. Default is true.
Constraints

  • [P1-start f:selectItem constraints] Must be nested inside a UIComponent custom action that creates a UISelectMany or UISelectOne component instance.[P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create a new UISelectItem component, and attach it as a child of the associated UIComponent.

[P1-start f:selectItem implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.UIComponentELTag.

  • The getComponentType() method must return “SelectItem”.

  • The getRendererType() method must return null.[P1-end]

<f:selectItems>

Add a child UISelectItems component to the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:selectItems [id=”componentIdOrImmediateExpression”]

  • [binding=”componentReference”]

  • value=”selectItemsValue” />

Body Content

empty

Attributes
Name Expr Type Description

binding

VE

ValueExpression

ValueExpression expression to a backing bean property bound to the component instance for the UIComponent created by this custom action.

id

NONE

String

Component identifier of a UISelectItem component.

value

VE

jakarta.faces.model.SelectItem, see description for specific details

Value binding expression pointing at one of the following instances:

  1. an individual jakarta.faces.model.SelectItem

  2. a java language array of jakarta.faces.model.SelectItem

  3. a java.util.Collection of jakarta.faces.model.SeleccItem

  4. A java.util.Map where the keys are converted to Strings and used as labels, and the corresponding values are converted to Strings and used as values for newly created jakarta.faces.model.SelectItem instances. The instances are created in the order of the iterator over the keys provided by the Map.
Constraints

  • Must be nested inside a UIComponent custom action that creates a UISelectMany or UISelectOne component instance.

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create a new UISelectItems component, and attach it as a child of the associated UIComponent.

[P1-start f:selectItems implementation]The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.UIComponentELTag.

  • The getComponentType() method must return “jakarta.faces.SelectItems”.

  • The getRendererType() method must return null. [P1-end]

<f:setPropertyActionListener>

Tag implementation that creates a special ActionListener instance and registers it on the ActionSource associated with our most immediate surrounding instance of a tag whose implementation class is a subclass of UIComponentTag. This tag creates no output to the page currently being created. This tag is useful for pushing a specific value into a managed bean on page submit.

Syntax

<f:setPropertyActionListener target=”Value Expression” value=”value Expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

value

VE

ValueExpression

The ValueExpression from which the value is taken.

target

VE

ValueExpression

The ValueExpression into which the evaluated value from the “value” attribute is stored when the listener executes.
Constraints

  • Must be nested inside a UIComponent custom action.

  • The corresponding UIComponent implementation class must implement ActionSource, and therefore define a public addActionListener() method that accepts an ActionListener parameter.

  • The tag implementation must only create and register the ActionListener instance the first time the component for this tag is created

  • When the listener executes:

    • Call getValue() on the "value" ValueExpression.

    • If value of the "value" expression is null, call setValue() on the "target" ValueExpression with the null value.

    • If the value of the "value" expression is not null, call getType() on the "value" and "target" ValueExpressions to determine their property types.

    • Coerce the value of the "value" expression to the "target" expression value type following the Expression Language coercion rules. Call setValue() on the "target" ValueExpression with the resulting value.

    • If either conversion or the execution of setValue() fails throw an AbortProcessingException.

  • This tag creates no output to the page currently being created. It is used solely for the side effect of ActionListener creation and addition.

[P1-start f:setPropertyActionListener constraints]If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement ActionSource, or the specified listener class does not implement jakarta.faces.event.ActionListener, throw a JspException.[P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true return SKIP_BODY.

Create an instance of ActionListener that implements StateHolder and stores the target and value ValueExpression instances as instance variables included in the state saving contract. The processAction() method of the listener must call getValue() on the value ValueExpression and convert the value before passing the result to a call to setValue() on the target ValueExpression.

<f:subview>

Container action for all Jakarta Faces core and component custom actions used on a nested page included via <jsp:include> or any custom action that dynamically includes another page from the same web application, such as Jakarta Tags’s <c:import>.

Syntax

<f:subview id=”componentIdOrImmediateExpression”

  • [binding=”componentReference”]

  • [rendered=”{true|false}”]>

    • Nested template text and custom actions

</f:subview>

Body Content

JSP. May contain any combination of template text, other Jakarta Faces custom actions, and custom actions from other custom tag libraries.

Attributes
Name Expr Type Description

binding

VE

ValueExpression

ValueExpression expression to a backing bean property bound to the component instance for the UIComponent created by this custom action.

id

NONE

String

Component identifier of a UINamingContainer component

rendered

VE

Boolean

Whether or not this subview should be rendered.
Constraints

  • [P1-start f:subview constraints] Must be nested inside a <f:view> custom action (although this custom action might be in a page that is including the page containing the <f:subview> custom action.

  • Must not contain an <f:view> custom action.

  • Must have an id attribute whose value is unique within the scope of the parent naming container. If this constraint is not met, the action taken regarding id uniqueness in section UIComponent Custom Action Implementation Requirements must be taken

  • May be placed in a parent page (with <jsp:include> or <c:import> nested inside), or within the nested page. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create a new UINamingContainer component, and attach it as a child of the associated UIComponent. Such a component provides a scope within which child component identifiers must still be unique, but allows child components to have the same simple identifier as child components nested in some other naming container. This is useful in several scenarios:

“main.jsp”
<f:view>
  <c:import url=”foo.jsp”/>
  <c:import url=”bar.jsp”/>
</f:view>

“foo.jsp”
<f:subview id=”aaa”>
  ... components and other content ...
</f:subview>

“bar.jsp”
<f:subview id=”bbb”>
  ... components and other content ...
</f:subview>

In this scenario, <f:subview> custom actions in imported pages establish a naming scope for components within those pages. Identifiers for <f:subview> custom actions nested in a single <f:view> custom action must be unique, but it is difficult for the page author (and impossible for the Jakarta Server Pages page compiler) to enforce this restriction.

“main.jsp”
<f:view>
  <f:subview id=”aaa”>
    <c:import url=”foo.jsp”/>
  </f:subview>
  <f:subview id=”bbb”>
    <c:import url=”bar.jsp”/>
  </f:subview>
</f:view>

“foo.jsp”
... components and other content ...

“bar.jsp”
... components and other content ...

In this scenario, the <f:subview> custom actions are in the including page, rather than the included page. As in the previous scenario, the “id” values of the two subviews must be unique; but it is much easier to verify using this style.

It is also possible to use this approach to include the same page more than once, but maintain unique identifiers:

“main.jsp”
<f:view>
  <f:subview id=”aaa”>
    <c:import url=”foo.jsp”/>
  </f:subview>
  <f:subview id=”bbb”>
    <c:import url=”foo.jsp”/>
  </f:subview>
</f:view>

“foo.jsp”
... components and other content ...

In all of the above examples, note that foo.jsp and bar.jsp may not contain <f:view>.

The implementation class for this action must meet the following requirements:

  • [P1-start f:subview implementation] Must extend jakarta.faces.UIComponentELTag.

  • The getComponentType() method must return “NamingContainer”.

  • The getRendererType() method must return null. [P1-end]

<f:validateDoubleRange>

Register a DoubleRangeValidator instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax
Syntax 1: Maximum only specified

<f:validateDoubleRange maximum=”543.21” binding=”VB Expression”/>

Syntax 2: Minimum only specified

<f:validateDoubleRange minimum=”123.45” binding=”VB Expression”/>

Syntax 3: Both maximum and minimum are specified

<f:validateDoubleRange maximum=”543.21” minimum=”123.45” binding=”VB Expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

maximum

VE

double

Maximum value allowed for this component

minimum

VE

double

Minimum value allowed for this component

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Validator

for

VE

ValueExpression

A ValueExpression expression that evaluates to String referring to the value of one of the exposed attached objects within the composite component inside of which this tag is nested.
Constraints

  • Must be nested inside a EditableValueHolder custom action whose value is (or is convertible to) a double.

  • Must specify either the maximum attribute, the minimum attribute, or both.

  • If both limits are specified, the maximum limit must be greater than the minimum limit.

[P1-start f:validateDoubleRange constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement EditableValueHolder throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createValidator() and register the returned Validator instance on the associated UIComponent.

[P1-start f:validateDoubleRange implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ValidatorELTag.

  • The createValidator() method must:

    • If binding is non-null, create a ValueBinding by invoking Application.createValueExpression() with binding as the expression argument, and Validator.class as the expectedType argument.use the ValueBinding to obtain a reference to the Validator instance. If there is no exception thrown, and ValueExpression.getValue() returned a non-null object that implements jakarta.faces.validator.Validator, it must then cast the returned instance to jakarta.faces.validator.DoubleRangeValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

  • use the validatorId if the validator instance could not be created from the binding attribute. Call the createValidator() method of the Application instance for this application, passing validator id “jakarta.faces.DoubleRange”. If the binding attribute was also set, evaluate the expression into a ValueExpression and store the validator instance by calling setValue() on the ValueExpression. It must then cast the returned instance to jakarta.faces.validator.DoubleRangeValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException. [P1-end]

<f:validateLength>

Register a LengthValidator instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax
Syntax 1: Maximum length only specified

<f:validateLength maximum=”10” binding=”VB Expression”/>

Syntax 2: Minimum only specified

<f:validateLength minimum=”1” binding=”VB Expression”/>

Syntax 3: Both maximum and minimum are specified

<f:validateLength maximum=”10” minimum=”1” binding=”VB Expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

maximum

VE

double

Maximum value allowed for this component

minimum

VE

double

Minimum value allowed for this component

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Validator
Constraints

  • Must be nested inside a EditableValueHolder custom action whose value is (or is convertible to) a double.

  • Must specify either the maximum attribute, the minimum attribute, or both.

  • If both limits are specified, the maximum limit must be greater than the minimum limit.

[P1-start f:validateDoubleRange constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement EditableValueHolder throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createValidator() and register the returned Validator instance on the associated UIComponent.

[P1-start f:validateDoubleRange implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ValidatorELTag.

  • The createValidator() method must:

    • If binding is non-null, create a ValueBinding by invoking Application.createValueExpression() with binding as the expression argument, and Validator.class as the expectedType argument.use the ValueBinding to obtain a reference to the Validator instance. If there is no exception thrown, and ValueExpression.getValue() returned a non-null object that implements jakarta.faces.validator.Validator, it must then cast the returned instance to jakarta.faces.validator.DoubleRangeValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

    • use the validatorId if the validator instance could not be created from the binding attribute. Call the createValidator() method of the Application instance for this application, passing validator id “jakarta.faces.DoubleRange”. If the binding attribute was also set, evaluate the expression into a ValueExpression and store the validator instance by calling setValue() on the ValueExpression. It must then cast the returned instance to jakarta.faces.validator.DoubleRangeValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException. [P1-end]

<f:validateRegex>

Register a RegexValidator instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:validateRegex pattern=”a*b”/>

Body Content

empty.

Attributes
Name Expr Type Description

pattern

VE

String

The string to be interpreted as a java.util.regex.Pattern

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Validator
Constraints

  • Must be nested inside a EditableValueHolder custom action whose value is a String.

  • Must specify either the pattern attribute.

[P1-start f:validateLength constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement EditableValueHolder, throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createValidator() and register the returned Validator instance on the associated UIComponent.

[P1-start f:validateLength implementation] The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ValidatorELTag.

  • The createValidator() method must:

    • If binding is non-null, create a ValueExpression by invoking Application.createValueExpression() with binding as the expression argument, and Validator.class as the expectedType argument.use the ValueExpression to obtain a reference to the Validator instance. If there is no exception thrown, and ValueExpression.getValue() returned a non-null object that implements jakarta.faces.validator.Validator, it must then cast the returned instance to jakarta.faces.validator.RegexValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

    • use the validatorId if the validator instance could not be created from the binding attribute. Call the createValidator() method of the Application instance for this application, passing validator id “jakarta.faces.RegularExpression”. If the binding attribute was also set, evaluate the expression into a ValueExpression and store the validator instance by calling setValue() on the ValueExpression. It must then cast the returned instance to jakarta.faces.validator.RegexValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.[P1-end]

<f:validateLongRange>

Register a LongRangeValidator instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax
Syntax 1: Maximum only specified

<f:validateLongRange maximum=”543” binding=”VB Expression”/>

Syntax 2: Minimum only specified

<f:validateLongRange minimum=”123” binding=”VB Expression”/>

Syntax 3: Both maximum and minimum are specified

<f:validateLongRange maximum=”543” minimum=”123” binding=”VB Expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

maximum

VE

long

Maximum value allowed for this component

minimum

VE

long

Minimum value allowed for this component

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Validator
Constraints

  • Must be nested inside a EditableValueHolder custom action whose value is (or is convertible to) a long.

  • Must specify either the maximum attribute, the minimum attribute, or both.

  • If both limits are specified, the maximum limit must be greater than the minimum limit.

[P1-start f:validateLongeRange constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement EditableValueHolder, throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createValidator() and register the returned Validator instance on the associated UIComponent.

The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ValidatorELTag.

  • The createValidator() method must:

    • If binding is non-null, create a ValueExpression by invoking Application.createValueExpression() with binding as the expression argument, and Validator.class as the expectedType argument. Use the ValueExpression to obtain a reference to the Validator instance. If there is no exception thrown, and ValueExpression.getValue() returned a non-null object that implements jakarta.faces.validator.Validator, it must then cast the returned instance to jakarta.faces.validator.LongRangeValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

    • use the validatorId if the validator instance could not be created from the binding attribute. Call the createValidator() method of the Application instance for this application, passing validator id “jakarta.faces.LongRange”. If the binding attribute was also set, evaluate the expression into a ValueExpression and store the validator instance by calling setValue() on the ValueExpression. It must then cast the returned instance to jakarta.faces.validator.LongRangeValidator and configure its properties based on the specified attributes for this custom action, and return the configured instance. If there was an exception thrown, rethrow the exception as a JspException.

<f:validator>

Register a named Validator instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:validator validatorId=”validatorId” binding=”VB Expression”/>

Body Content

empty

Attributes
Name Expr Type Description

validatorId

VE

String

Validator identifier of the validator to be created.

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.convert.Validator
Constraints

  • Must be nested inside a UIComponent custom action whose component class implements EditableValueHolder.

  • validatorId and/or binding must be specified.

[P1-start f:validator constraints 2] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement EditableValueHolder throw a JspException. [P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, create, call createValidator() and register the returned Validator instance on the associated UIComponent.

The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.webapp.ValidatorJspTag.

  • The createValidator() method must:

    • If binding is non-null, call binding.getValue() to obtain a reference to the Validator instance. If there is no exception thrown, and binding.getValue() returned a non-null object that implements jakarta.faces.validator.Validator, register it by calling addValidator(). If there was an exception thrown, rethrow the exception as a JspException.

    • use the validatorId attribute if the validator instance could not be created from the binding attribute. If the validatorId attribute is set, call the createValidator() method of the Application instance for this application, passing validator id specified by their validatorId attribute. If the binding attribute was also set, store the validator instance by calling binding.setValue(). Register the validator instance by calling addValidator(). If there was an exception thrown, rethrow the exception as a JspException.

<f:valueChangeListener>

Register a ValueChangeListener instance on the UIComponent associated with the closest parent UIComponent custom action.

Syntax

<f:valueChangeListener type=”fully-qualified-classname” binding=”VB Expression”/>

Body Content

empty.

Attributes
Name Expr Type Description

type

VE

String

Fully qualified Java class name of a ValueChangeListener to be created and registered

binding

VE

ValueExpression

A ValueExpression expression that evaluates to an object that implements jakarta.faces.event.ValueChangeListener
Constraints

  • Must be nested inside a UIComponent custom action.

  • The corresponding UIComponent implementation class must implement EditableValueHolder, and therefore define a public addValueChangeListener() method that accepts an ValueChangeListener parameter.

  • The specified listener class must implement jakarta.faces.event.ValueChangeListener.

  • type and/or binding must be specified.

[P1-start f:valueChangeListener constraints] If this tag is not nested inside a UIComponent custom action, or the UIComponent implementation class does not correctly implement EditableValueHolder, or the specified listener class does not implement jakarta.faces.event.ValueChangeListener, throw a JspException. [P1-end] Note that if the binding attribute is used, the scope of the ValueExpression must be chosen carefully so as not to introduce undesireable results. In general, when using the binding attribute, do not point to beans in request or narrower scope.

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, check the binding attribute.

If binding is non-null, call binding.getValue() to obtain a reference to the ValueChangeListener instance. If there is no exception thrown, and ValueExpression.getValue() returned a non-null object that implements jakarta.faces.event.ValueChangeListener, register it by calling addValueChangeListener(). If there was an exception thrown, rethrow the exception as a JspException.

If the listener instance could not be created, check the type attribute. If the type attribute is set, instantiate an instance of the specified class, and register it by calling addValueChangeListener(). If the binding attribute was also set, store the listener instance by calling binding.setValue(). If there was an exception thrown, rethrow the exception as a JspException.

As an alternative to using the binding and/or type attributes, you may also register a method in a backing bean class to receive ValueChangeEvent notifications, by using the valueChangeListener attribute on the corresponding UIComponent custom action.instantiate an instance of the specified class, and register it by calling addValueChangeListener().

<f:verbatim>

Register a child UIOutput instance on the UIComponent associated with the closest parent UIComponent custom action which renders nested body content.

Syntax

<f:verbatim [escape=”{true|false}” rendered=”{true|false}”]/>

Body Content

JSP. However, no UIComponent custom actions, or custom actions from the Jakarta Faces Core Tag Library, may be nested inside this custom action.

Attributes
Name Expr Type Description

escape

VE

boolean

If true, generated markup is escaped in a manner appropriate for the markup language being rendered. Default value is false.

rendered

VE

boolean

Flag indicating whether or not this component should be rendered (during Render Response Phase), or processed on any subsequent form submit. Default value is true.
Constraints

  • [P1-start f:verbatim constraints] Must be implemented as a UIComponentBodyTag.[P1-end]

Description

Locate the closest parent UIComponent custom action instance by calling UIComponentClassicTagBase.getParentUIComponentClassicTagBase(). If the getCreated() method of this instance returns true, creates a new UIOutput component, and add it as a child of the UIComponent associated with the located instance. The rendererType property of this UIOutput component must be set to “jakarta.faces.Text”, and the transient property must be set to true. Also, the value (or value binding, if it is an expression) of the escape attribute must be passed on to the renderer as the value the escape attribute on the UIOutput component.

<f:view>

Container for all Jakarta Faces core and component custom actions used on a page.

Syntax

<f:view

  • [locale=”locale” renderKitId=”alternate”]

  • [beforePhase=”methodExpression”]

  • [afterPhase=”methodExpression”]>

    • Nested template text and custom actions

</f:view>

Body Content

JSP. May contain any combination of template text, other Jakarta Faces custom actions, and custom actions from other custom tag libraries.

Attributes
Name Expr Type Description

renderKitId

VE

String

The identifier for the render kit to use for rendering this page.

locale

VE

String or Locale

Name of a Locale to use for localizing this page (such as en_uk), or value binding expression that returns a Locale instance

beforePhase

ME

String

MethodExpression expression that points to a method whose signature is that of jakarta.faces.event.PhaseListener.beforePhase()

afterPhase

ME

String

MethodExpression expression that points to a method whose signature is that of jakarta.faces.event.PhaseListener.afterPhase()
Constraints

  • [P1-start f:view constraints] Any Jakarta Server Pages-created response using actions from the Jakarta Faces Core Tag Library, as well as actions extending jakarta.faces.webapp.UIComponentELTag from other tag libraries, must be nested inside an occurrence of the <f:view> action.

  • Jakarta Server Pages page fragments included via the standard <%@ include %> directive need not have their Jakarta Faces actions embedded in a <f:view> action, because the included template text and custom actions will be processed as part of the outer page as it is compiled, and the <f:view> action on the outer page will meet the nesting requirement.

  • If the renderKitId attribute is present, its value is stored in UIViewRoot. If the renderKitId attribute is not present, then the default render kit identifier as returned by Application.getDefaultRenderKitId() is stored in UIViewRoot if it is not null. Otherwise, the render kit identifier as specified by the constant RenderKitFactory.HTML_BASIC_RENDER_KIT is stored in UIViewRoot. Specifying a renderKitId for the current view also affects all subsequent views, unless overridden by another use of the renderKitId attribute. Please refer to ViewHandler for more information.

  • If the locale attribute is present, its value overrides the Locale stored in UIViewRoot, normally set by the ViewHandler, and the doStartTag() method must store it by calling UIViewRoot.setLocale().

  • The doStartTag() method must call jakarta.servlet.jsp.jstl.core.Config.set(), passing the ServletRequest instance for this request, the constant jakarta.servlet.jsp.jstl.core.Config.FMT_LOCALE, and the Locale returned by calling UIViewRoot.getLocale(). [P1-end]

Description

Provides the Jakarta Faces implementation a convenient place to perform state saving during the render response phase of the request processing lifecycle, if the implementation elects to save state as part of the response.

The implementation class for this action must meet the following requirements:

  • Must extend jakarta.faces.UIComponentELTag.

  • The getComponentType() method must return “ViewRoot”.

  • The getRendererType() method must return null.

Please refer to the javadocs for jakarta.faces.application.StateManager for details on what the tag handler for this tag must do to implement state saving.

Standard HTML RenderKit Tag Library

All Jakarta Faces implementations must provide a tag library containing actions that correspond to each valid combination of a supported component class (see Standard User Interface Components”) and a Renderer from the Standard HTML RenderKit (see Standard HTML RenderKit Implementation) that supports that component type. [P1-start html_basic taglib requirements] The tag library descriptor for this tag library must meet the following requirements:

  • Must declare a tag library version (<tlib-version>) value of 1.2.

  • Must declare a URI (<uri>) value of http://java.sun.com/jsf/html.

  • Must be included in the META-INF directory of a JAR file containing the corresponding implementation classes, suitable for inclusion with a web application, such that the tag library descriptor will be located automatically by the algorithm described in Section 7.3 of the _ Jakarta Server Pages Specification_ (version 1.2).[P1-end]

[P1-start html_basic return values]The custom actions defined in this tag library must specify the following return values for the getComponentType() and getRendererType() methods, respectively:.

Table 2. Standard HTML RenderKit Tag Library
getComponentType() getRendererType() custom action name

jakarta.faces.Column

(null)18

column

jakarta.faces.HtmlCommandButton

jakarta.faces.Button

commandButton

jakarta.faces.HtmlCommandLink

jakarta.faces.Link

commandLink

jakarta.faces.HtmlDataTable

jakarta.faces.Table

dataTable

jakarta.faces.HtmlForm

jakarta.faces.Form

form

jakarta.faces.HtmlGraphicImage

jakarta.faces.Image

graphicImage

jakarta.faces.HtmlInputHidden

jakarta.faces.Hidden

inputHidden

jakarta.faces.HtmlInputSecret

jakarta.faces.Secret

inputSecret

jakarta.faces.HtmlInputText

jakarta.faces.Text

inputText

jakarta.faces.HtmlInputTextarea

jakarta.faces.Textarea

inputTextarea

jakarta.faces.HtmlMessage

jakarta.faces.Message

message

jakarta.faces.HtmlMessages

jakarta.faces.Messages

messages

jakarta.faces.HtmlOutputFormat

jakarta.faces.Format

outputFormat

jakarta.faces.HtmlOutputLabel

jakarta.faces.Label

outputLabel

jakarta.faces.HtmlOutputLink

jakarta.faces.Link

outputLink

jakarta.faces.Output

jakarta.faces.Body

body

jakarta.faces.Output

jakarta.faces.Head

head

jakarta.faces.Output

jakarta.faces.resource.Script

outputScript

jakarta.faces.Output

jakarta.faces.resource.Stylesheet

outputStylesheet

jakarta.faces.HtmlOutputText

jakarta.faces.Text

outputText

jakarta.faces.HtmlPanelGrid

jakarta.faces.Grid

panelGrid

jakarta.faces.HtmlPanelGroup

jakarta.faces.Group

panelGroup

jakarta.faces.HtmlSelectBooleanCheckbox

jakarta.faces.Checkbox

selectBooleanCheckbox

jakarta.faces.HtmlSelectManyCheckbox

jakarta.faces.Checkbox

selectManyCheckbox

jakarta.faces.HtmlSelectManyListbox

jakarta.faces.Listbox

selectManyListbox

jakarta.faces.HtmlSelectManyMenu

jakarta.faces.Menu

selectManyMenu

jakarta.faces.HtmlSelectOneListbox

jakarta.faces.Listbox

selectOneListbox

jakarta.faces.HtmlSelectOneMenu

jakarta.faces.Menu

selectOneMenu

jakarta.faces.HtmlSelectOneRadio

jakarta.faces.Radio

selectOneRadio

Note, to avoid confusion between Jakarta Server Pages and Facelets, any Renderers that are only supported in Facelets are specified in Standard HTML RenderKit Tag Library.

[P1-end] [P1-start html_basic taglibrary requirements 2]The tag library descriptor for this tag library (and the corresponding tag handler implementation classes) must meet the following requirements:

  • The attributes for the tags, both in the TLD and in the associated tag handlers, must conform exactly to the type, name, and description given in the VDLDocs for the html_basic tag library.

  • If the type of the attribute is jakarta.el.ValueExpression, the TLD for the attribute must contain a <deferred-value> with a nested <type> element, inside of which is nested the expected type, as given in the VDLDocs. The JavaBeans setter method in the tag handler for the tag must be of type jakarta.el.ValueExpression.

  • If the type of the attribute is jakarta.el.MethodExpression, the TLD for the attribute must contain a <deferred-method> with a nested <method-signature>, inside of which is the method signature for that MethodExpression, as given in the VDLDocs. The actual name of the method in the signature declaration is immaterial and unspecified. The JavaBeans setter method in the tag handler for the tag must be of type jakarta.el.MethodExpression.

  • Any attributes listed in the VDLDocs with a request-time value of true must specify an <rtexprvalue> of true in the TLD.

  • The following action must be taken to handle the value of the converter property. If isLiteralText() on the converter property returns true, get the value of the property and treat it as a converterId by passing it as the argument to the createConverter() method of the Application instance for this webapp, then pass the created Converter to the setConverter() method of the component for this tag. If isLiteralText() on the converter property returns false, call setValueExpression() on the component, passing “converter” as the name of the ValueExpression and the ValueExpression instance as the value.

  • For a non-null action attribute on custom actions related to ActionSource components (commandButton, commandLink), the setProperties() method of the tag handler implementation class must pass the value of the action attribute, which is a MethodExpression, to the component’s setActionExpression() method.

  • For other non-null attributes that correspond to MethodExpression attributes on the underlying components (actionListener, validator, valueChangeListener), the setProperties() method of the tag handler implementation class must store that instance as the value of the corresponding component property.

  • For any non-null id, scope, or var attribute, the setProperties() method of the tag handler implementation class must simply set the value of the corresponding component attribute.

  • For all other non-null attributes, the setProperties() of the tag handler implementation class method must:

    • If the attribute.isLiteralText() returns true, set the corresponding attribute on the underlying component (after performing any necessary type conversion).

    • Otherwise, call the setValueExpression() method on the underlying component, passing the attribute name and the ValueExpression instance as parameters.[P1-end]