Module jakarta.faces

Package jakarta.faces.component

Class UIForm

java.lang.Object

jakarta.faces.component.UIComponent

jakarta.faces.component.UIComponentBase

jakarta.faces.component.UIForm

All Implemented Interfaces:

NamingContainer, PartialStateHolder, StateHolder, TransientStateHolder, UniqueIdVendor, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener

Direct Known Subclasses:

HtmlForm

public class UIForm
extends UIComponentBase
implements NamingContainer, UniqueIdVendor

UIForm is a UIComponent that represents an input form to be presented to the user, and whose child components represent (among other things) the input fields to be included when the form is submitted.

By default, the rendererType property must be set to "jakarta.faces.Form". This value can be changed by calling the setRendererType() method.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	COMPONENT_FAMILY	The standard component family for this component.
static final String	COMPONENT_TYPE	The standard component type for this component.

Fields inherited from class jakarta.faces.component.UIComponent

ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY

Fields inherited from interface jakarta.faces.component.NamingContainer

SEPARATOR_CHAR

Constructor Summary

Constructors

Constructor	Description
UIForm()	Create a new UIForm instance with default property values.

Method Summary

Modifier and Type	Method	Description
String	createUniqueId(FacesContext context, String seed)	Generate an identifier for a component.
String	getContainerClientId(FacesContext context)	Override the UIComponent.getContainerClientId(jakarta.faces.context.FacesContext) to allow users to disable this form from prepending its clientId to its descendent's clientIds depending on the value of this form's isPrependId() property.
String	getFamily()	Return the identifier of the component family to which this component belongs.
boolean	invokeOnComponent(FacesContext context, String clientId, ContextCallback callback)	Starting at this component in the View hierarchy, search for a component with a clientId equal to the argument clientId and, if found, call the ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) method on the argument callback, passing the current FacesContext and the found component as arguments.
boolean	isPrependId()	Is the id prepended.
boolean	isSubmitted()	Returns the current value of the submitted property.
void	processDecodes(FacesContext context)	Override UIComponent.processDecodes(jakarta.faces.context.FacesContext) to ensure that the form is decoded before its children.
void	processUpdates(FacesContext context)	Override UIComponent.processUpdates(jakarta.faces.context.FacesContext) to ensure that the children of this UIForm instance are only processed if isSubmitted() returns true.
void	processValidators(FacesContext context)	Override UIComponent.processValidators(jakarta.faces.context.FacesContext) to ensure that the children of this UIForm instance are only processed if isSubmitted() returns true.
void	setPrependId(boolean prependId)	Set whether the id should be prepended.
void	setSubmitted(boolean submitted)	If this UIForm instance (as opposed to other forms in the page) is experiencing a submit during this request processing lifecycle, this method must be called, with true as the argument, during the UIComponent.decode(jakarta.faces.context.FacesContext) for this UIForm instance.
boolean	visitTree(VisitContext context, VisitCallback callback)	Perform a tree visit starting at this node in the tree.

Methods inherited from class jakarta.faces.component.UIComponentBase

addClientBehavior, addFacesListener, broadcast, clearInitialState, decode, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, isRendered, isTransient, markInitialState, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, subscribeToEvent, unsubscribeFromEvent

Methods inherited from class jakarta.faces.component.UIComponent

encodeAll, getClientId, getCompositeComponentParent, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type for this component.

See Also:

• Constant Field Values

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

The standard component family for this component.

See Also:

• Constant Field Values

Constructor Details

UIForm

public UIForm()

Create a new UIForm instance with default property values.

Method Details

getFamily

public String getFamily()

Description copied from class: UIComponent

Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the rendererType property, may be used to select the appropriate Renderer for this component instance. Note this method should NOT return null

Specified by:

getFamily in class UIComponent

Returns:

the component family (not null).

isSubmitted

public boolean isSubmitted()

Returns the current value of the submitted property. The default value is false. See setSubmitted(boolean) for details.

This property must be kept as a transient property using the UIComponent.getTransientStateHelper().

Returns:

true if the form was submitted, false otherwise.

setSubmitted

public void setSubmitted(boolean submitted)

If this UIForm instance (as opposed to other forms in the page) is experiencing a submit during this request processing lifecycle, this method must be called, with true as the argument, during the UIComponent.decode(jakarta.faces.context.FacesContext) for this UIForm instance. If this UIForm instance is not experiencing a submit, this method must be called, with false as the argument, during the UIComponent.decode(jakarta.faces.context.FacesContext) for this UIForm instance.

The value of a UIForm's submitted property must not be saved as part of its state.

This property must be kept as a transient property using the UIComponent.getTransientStateHelper().

Parameters:

submitted - the new value of the submitted flag.

isPrependId

public boolean isPrependId()

Is the id prepended.

Returns:

true if it is, false otherwise.

setPrependId

public void setPrependId(boolean prependId)

Set whether the id should be prepended.

Parameters:

prependId - true if it is, false otherwise.

processDecodes

public void processDecodes(FacesContext context)

Override UIComponent.processDecodes(jakarta.faces.context.FacesContext) to ensure that the form is decoded before its children. This is necessary to allow the submitted property to be correctly set.

Overrides:

processDecodes in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

processValidators

public void processValidators(FacesContext context)

Override UIComponent.processValidators(jakarta.faces.context.FacesContext) to ensure that the children of this UIForm instance are only processed if isSubmitted() returns true.

Overrides:

processValidators in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

See Also:

• PreValidateEvent
• PostValidateEvent

processUpdates

public void processUpdates(FacesContext context)

Override UIComponent.processUpdates(jakarta.faces.context.FacesContext) to ensure that the children of this UIForm instance are only processed if isSubmitted() returns true.

Overrides:

processUpdates in class UIComponentBase

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

createUniqueId

public String createUniqueId(FacesContext context,
 String seed)

Generate an identifier for a component. The identifier will be prefixed with UNIQUE_ID_PREFIX, and will be unique within this component-container. Optionally, a unique seed value can be supplied by component creators which should be included in the generated unique id.

If the prependId property has the value false, this method must call createUniqueId on the next ancestor UniqueIdVendor.

Specified by:

createUniqueId in interface UniqueIdVendor

Parameters:

context - FacesContext

seed - an optional seed value - e.g. based on the position of the component in the VDL-template

Returns:

a unique-id in this component-container

getContainerClientId

public String getContainerClientId(FacesContext context)

Override the UIComponent.getContainerClientId(jakarta.faces.context.FacesContext) to allow users to disable this form from prepending its clientId to its descendent's clientIds depending on the value of this form's isPrependId() property.

Overrides:

getContainerClientId in class UIComponent

Parameters:

context - the Faces context.

Returns:

the container client id.

visitTree

public boolean visitTree(VisitContext context,
 VisitCallback callback)

Description copied from class: UIComponent

Perform a tree visit starting at this node in the tree.

UIComponent.visitTree() implementations do not invoke the VisitCallback directly, but instead call VisitContext.invokeVisitCallback(jakarta.faces.component.UIComponent, jakarta.faces.component.visit.VisitCallback) to invoke the callback. This allows VisitContext implementations to provide optimized tree traversals, for example by only calling the VisitCallback for a subset of components.

UIComponent.visitTree() implementations must call UIComponent.pushComponentToEL() before performing the visit and UIComponent.popComponentFromEL() after the visit.

Overrides:

visitTree in class UIComponent

Parameters:

context - the VisitContext for this visit

callback - the VisitCallback instance whose visit method will be called for each node visited.

Returns:

component implementations may return true to indicate that the tree visit is complete (eg. all components that need to be visited have been visited). This results in the tree visit being short-circuited such that no more components are visited.

See Also:

• UIComponent.visitTree(jakarta.faces.component.visit.VisitContext, jakarta.faces.component.visit.VisitCallback)

invokeOnComponent

public boolean invokeOnComponent(FacesContext context,
 String clientId,
 ContextCallback callback)
                          throws FacesException

Description copied from class: UIComponentBase

Starting at this component in the View hierarchy, search for a component with a clientId equal to the argument clientId and, if found, call the ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) method on the argument callback, passing the current FacesContext and the found component as arguments. This method is similar to UIComponent.findComponent(java.lang.String) but it does not support the leading UINamingContainer.getSeparatorChar(jakarta.faces.context.FacesContext) syntax for searching from the root of the View.

The default implementation will first check if this.getClientId() is equal to the argument clientId. If so, first call UIComponent.pushComponentToEL(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent), then call the ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) method on the argument callback, passing through the FacesContext argument and passing this as the component argument. Then call UIComponent.popComponentFromEL(jakarta.faces.context.FacesContext). If an Exception is thrown by the callback, wrap it in a FacesException and re-throw it. Otherwise, return true.

Otherwise, for each component returned by UIComponent.getFacetsAndChildren(), call invokeOnComponent() passing the arguments to this method, in order. The first time invokeOnComponent() returns true, abort traversing the rest of the Iterator and return true.

When calling ContextCallback.invokeContextCallback(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent) the implementation of this method must guarantee that the state of the component passed to the callback correctly reflects the component's position in the View hierarchy with respect to any state found in the argument clientId. For example, an iterating component such as UIData will need to set its row index to correctly reflect the argument clientId before finding the appropriate child component backed by the correct row. When the callback returns, either normally or by throwing an Exception the implementation of this method must restore the state of the view to the way it was before invoking the callback.

If none of the elements from UIComponent.getFacetsAndChildren() returned true from invokeOnComponent(), return false.

Simple usage example to find a component by clientId.

 
    private UIComponent found = null;

    private void doFind(FacesContext context, String clientId) {
      context.getViewRoot().invokeOnComponent(context, clientId,
          new ContextCallback() {
             public void invokeContextCallback(FacesContext context,
                                           UIComponent component) {
               found = component;
             }
          });
    }
 
 

Overrides:

invokeOnComponent in class UIComponentBase

Parameters:

context - the FacesContext for the current request

clientId - the client identifier of the component to be passed to the argument callback.

callback - an implementation of the Callback interface.

Returns:

true if the a component with the given clientId is found, the callback method was successfully invoked passing that component as an argument, and no Exception was thrown. Returns false if no component with the given clientId is found.

Throws:

FacesException - if the argument Callback throws an Exception, it is wrapped in a FacesException and re-thrown.

See Also:

• UIComponent.invokeOnComponent(jakarta.faces.context.FacesContext, java.lang.String, jakarta.faces.component.ContextCallback)