javax.faces.component

## Class UIForm

- java.lang.Object
- - javax.faces.component.UIComponent
  - - javax.faces.component.UIComponentBase
    - - javax.faces.component.UIForm

- All Implemented Interfaces:
    EventListener, NamingContainer, PartialStateHolder, StateHolder, TransientStateHolder, UniqueIdVendor, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
  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 "`javax.faces.Form`". This value can be changed by calling the `setRendererType()` method.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `COMPONENT_FAMILY` The standard component family for this component.
    `static String` | `COMPONENT_TYPE` The standard component type for this component.

    - ### Fields inherited from class javax.faces.component.UIComponent

      `ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY`

    - ### Fields inherited from interface javax.faces.component.NamingContainer

      `SEPARATOR_CHAR`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `String` | `createUniqueId(FacesContext context, String seed)` Generate an identifier for a component.
    `String` | `getContainerClientId(FacesContext context)` Override the `UIComponent.getContainerClientId(javax.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` | `isPrependId()` The prependId flag.
    `boolean` | `isSubmitted()` Returns the current value of the `submitted` property.
    `void` | `processDecodes(FacesContext context)` Override `UIComponent.processDecodes(javax.faces.context.FacesContext)` to ensure that the form is decoded before its children.
    `void` | `processUpdates(FacesContext context)` Override `UIComponent.processUpdates(javax.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(javax.faces.context.FacesContext)` to ensure that the children of this `UIForm` instance are only processed if `isSubmitted()` returns `true`.
    `void` | `setPrependId(boolean prependId)`
    `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(javax.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 javax.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, getValueBinding, invokeOnComponent, isRendered, isTransient, markInitialState, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, restoreState, saveAttachedState, saveState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent`

    - ### Methods inherited from class javax.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 Detail

    - #### 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 Detail

    - #### UIForm

          public UIForm()

      Create a new `UIForm` instance with default property values.

  - ### Method Detail

    - #### 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.

      Specified by:
        `getFamily` in class `UIComponent`

    - #### 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()`.

    - #### 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(javax.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(javax.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()`.

    - #### isPrependId

          public boolean isPrependId()

      The prependId flag.

    - #### setPrependId

          public void setPrependId(boolean prependId)

    - #### processDecodes

          public void processDecodes(FacesContext context)

      Override `UIComponent.processDecodes(javax.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(javax.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`

    - #### processUpdates

          public void processUpdates(FacesContext context)

      Override `UIComponent.processUpdates(javax.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(javax.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`

    - #### 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(javax.faces.component.UIComponent, javax.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(javax.faces.component.visit.VisitContext, javax.faces.component.visit.VisitCallback)`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.