Class UIInput

All Implemented Interfaces:
EventListener, EditableValueHolder, PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
Direct Known Subclasses:
HtmlInputFile, HtmlInputHidden, HtmlInputSecret, HtmlInputText, HtmlInputTextarea, UISelectBoolean, UISelectMany, UISelectOne, UIViewParameter

public class UIInput extends UIOutput implements EditableValueHolder

UIInput is a UIComponent that represents a component that both displays output to the user (like UIOutput components do) and processes request parameters on the subsequent request that need to be decoded. There are no restrictions on the data type of the local value, or the object referenced by the value binding expression (if any); however, individual Renderers will generally impose restrictions on the type of data they know how to display.

During the Apply Request Values phase of the request processing lifecycle, the decoded value of this component, usually but not necessarily a String, must be stored - but not yet converted - using setSubmittedValue(). If the component wishes to indicate that no particular value was submitted, it can either do nothing, or set the submitted value to null.

By default, during the Process Validators phase of the request processing lifecycle, the submitted value will be converted to a typesafe object, and, if validation succeeds, stored as a local value using setValue(). However, if the immediate property is set to true, this processing will occur instead at the end of the Apply Request Values phase.

During the Render Response phase of the request processing lifecycle, conversion for output occurs as for UIOutput.

When the validate() method of this UIInput detects that a value change has actually occurred, and that all validations have been successfully passed, it will queue a ValueChangeEvent. Later on, the broadcast() method will ensure that this event is broadcast to all interested listeners. This event will be delivered by default in the Process Validators phase, but can be delivered instead during Apply Request Values if the immediate property is set to true. If the validation fails, the implementation must call FacesContext.validationFailed().

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

  • Field Details

  • Constructor Details

    • UIInput

      public UIInput()

      Create a new UIInput 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.

      Overrides:
      getFamily in class UIOutput
    • getSubmittedValue

      public Object getSubmittedValue()

      Return the submittedValue value of this UIInput component. This method should only be used by the decode() and validate() method of this component, or its corresponding Renderer.

      Specified by:
      getSubmittedValue in interface EditableValueHolder
    • setSubmittedValue

      public void setSubmittedValue(Object submittedValue)

      Set the submittedValue value of this UIInput component. This method should only be used by the decode() and validate() method of this component, or its corresponding Renderer.

      Specified by:
      setSubmittedValue in interface EditableValueHolder
      Parameters:
      submittedValue - The new submitted value
    • getValue

      public Object getValue()

      If there is a local value, return it, otherwise return the result of calling super.getVaue().

      Specified by:
      getValue in interface ValueHolder
      Overrides:
      getValue in class UIOutput
      Since:
      2.2
    • setValue

      public void setValue(Object value)
      Description copied from interface: ValueHolder

      Set the value of this UIComponent (if any).

      Specified by:
      setValue in interface ValueHolder
      Overrides:
      setValue in class UIOutput
      Parameters:
      value - The new local value
    • resetValue

      public void resetValue()

      Convenience method to reset this component's value to the un-initialized state. This method does the following:

      Call UIOutput.setValue(java.lang.Object).

      Call setSubmittedValue(java.lang.Object) passing null.

      Call setLocalValueSet(boolean) passing false.

      Call setValid(boolean) passing true.

      Upon return from this call if the instance had a ValueBinding associated with it for the "value" property, this binding is evaluated when UIOutput.getValue() is called. Otherwise, null is returned from getValue().

      Specified by:
      resetValue in interface EditableValueHolder
      Overrides:
      resetValue in class UIOutput
    • isLocalValueSet

      public boolean isLocalValueSet()
      Return the "local value set" state for this component. Calls to setValue() automatically reset this property to true.
      Specified by:
      isLocalValueSet in interface EditableValueHolder
    • setLocalValueSet

      public void setLocalValueSet(boolean localValueSet)
      Sets the "local value set" state for this component.
      Specified by:
      setLocalValueSet in interface EditableValueHolder
    • isRequired

      public boolean isRequired()

      Return the "required field" state for this component.

      Specified by:
      isRequired in interface EditableValueHolder
    • getRequiredMessage

      public String getRequiredMessage()

      If there has been a call to setRequiredMessage(java.lang.String) on this instance, return the message. Otherwise, call UIComponent.getValueExpression(java.lang.String) passing the key "requiredMessage", get the result of the expression, and return it. Any ELExceptions thrown during the call to getValue() must be wrapped in a FacesException and rethrown.

    • setRequiredMessage

      public void setRequiredMessage(String message)

      Override any ValueExpression set for the "requiredMessage" with the literal argument provided to this method. Subsequent calls to getRequiredMessage() will return this value;

      Parameters:
      message - the literal message value to be displayed in the event the user hasn't supplied a value and one is required.
    • getConverterMessage

      public String getConverterMessage()

      If there has been a call to setConverterMessage(java.lang.String) on this instance, return the message. Otherwise, call UIComponent.getValueExpression(java.lang.String) passing the key "converterMessage", get the result of the expression, and return it. Any ELExceptions thrown during the call to getValue() must be wrapped in a FacesException and rethrown.

    • setConverterMessage

      public void setConverterMessage(String message)

      Override any ValueExpression set for the "converterMessage" with the literal argument provided to this method. Subsequent calls to getConverterMessage() will return this value;

      Parameters:
      message - the literal message value to be displayed in the event conversion fails.
    • getValidatorMessage

      public String getValidatorMessage()

      If there has been a call to setValidatorMessage(java.lang.String) on this instance, return the message. Otherwise, call UIComponent.getValueExpression(java.lang.String) passing the key "validatorMessage", get the result of the expression, and return it. Any ELExceptions thrown during the call to getValue() must be wrapped in a FacesException and rethrown.

    • setValidatorMessage

      public void setValidatorMessage(String message)

      Override any ValueExpression set for the "validatorMessage" with the literal argument provided to this method. Subsequent calls to getValidatorMessage() will return this value;

      Parameters:
      message - the literal message value to be displayed in the event validation fails.
    • isValid

      public boolean isValid()
      Description copied from interface: EditableValueHolder

      Return a flag indicating whether the local value of this component is valid (no conversion error has occurred).

      Specified by:
      isValid in interface EditableValueHolder
    • setValid

      public void setValid(boolean valid)
      Description copied from interface: EditableValueHolder

      Set a flag indicating whether the local value of this component is valid (no conversion error has occurred).

      Specified by:
      setValid in interface EditableValueHolder
      Parameters:
      valid - The new valid flag
    • setRequired

      public void setRequired(boolean required)

      Set the "required field" state for this component.

      Specified by:
      setRequired in interface EditableValueHolder
      Parameters:
      required - The new "required field" state
    • isImmediate

      public boolean isImmediate()
      Description copied from interface: EditableValueHolder

      Return the "immediate" state for this component.

      Specified by:
      isImmediate in interface EditableValueHolder
    • setImmediate

      public void setImmediate(boolean immediate)
      Description copied from interface: EditableValueHolder

      Set the "immediate" state for this component. When set to true, the component's value will be converted and validated immediately in the Apply Request Values phase, and ValueChangeEvents will be delivered in that phase as well. The default value for this property must be false.

      Specified by:
      setImmediate in interface EditableValueHolder
      Parameters:
      immediate - The new "immediate" state
    • getValidator

      public MethodBinding getValidator()
      Deprecated.
      getValidators() should be used instead.

      Return a MethodBinding pointing at a method that will be called during Process Validations phase of the request processing lifecycle, to validate the current value of this component.

      Specified by:
      getValidator in interface EditableValueHolder
    • setValidator

      public void setValidator(MethodBinding validatorBinding)
      Deprecated.
      Use addValidator(javax.faces.validator.Validator) instead, obtaining the argument Validator by creating an instance of MethodExpressionValidator.

      Set a MethodBinding pointing at a method that will be called during Process Validations phase of the request processing lifecycle, to validate the current value of this component.

      Any method referenced by such an expression must be public, with a return type of void, and accept parameters of type FacesContext, UIComponent, and Object.

      Specified by:
      setValidator in interface EditableValueHolder
      Parameters:
      validatorBinding - The new MethodBinding instance
    • getValueChangeListener

      public MethodBinding getValueChangeListener()
      Description copied from interface: EditableValueHolder

      If EditableValueHolder.setValueChangeListener(javax.faces.el.MethodBinding) was not previously called for this instance, this method must return null. If it was called, this method must return the exact MethodBinding instance that was passed to EditableValueHolder.setValueChangeListener(javax.faces.el.MethodBinding).

      Specified by:
      getValueChangeListener in interface EditableValueHolder
    • setValueChangeListener

      public void setValueChangeListener(MethodBinding valueChangeListener)
      Deprecated.

      Wrap the argument valueChangeMethod in an implementation of ValueChangeListener and store it in the internal data structure that backs the EditableValueHolder.getValueChangeListeners() method, taking care to over-write any instance that was stored by a previous call to setValueChangeListener.

      This argument method will be called during the Process Validations or Apply Request Values phases (depending on the value of the immediate property).

      Any method referenced by such an expression must be public, with a return type of void, and accept a parameter of type ValueChangeEvent.

      Specified by:
      setValueChangeListener in interface EditableValueHolder
      Parameters:
      valueChangeListener - The new method binding instance
    • markInitialState

      public void markInitialState()

      In addition to the actions taken in UIOutput when PartialStateHolder.markInitialState() is called, check if any of the installed Validators are PartialStateHolders and if so, call PartialStateHolder.markInitialState() as appropriate.

      Specified by:
      markInitialState in interface PartialStateHolder
      Overrides:
      markInitialState in class UIOutput
    • clearInitialState

      public void clearInitialState()
      Description copied from class: UIComponentBase

      For each of the attached objects on this instance that implement PartialStateHolder, call PartialStateHolder.clearInitialState() on the attached object.

      Specified by:
      clearInitialState in interface PartialStateHolder
      Overrides:
      clearInitialState in class UIOutput
    • processDecodes

      public void processDecodes(FacesContext context)

      Specialized decode behavior on top of that provided by the superclass. In addition to the standard processDecodes behavior inherited from UIComponentBase, calls validate() if the the immediate property is true; if the component is invalid afterwards or a RuntimeException is thrown, calls FacesContext.renderResponse().

      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)

      In addition to the standard processValidators behavior inherited from UIComponentBase, calls validate() if the immediate property is false (which is the default); if the component is invalid afterwards, calls FacesContext.renderResponse(). If a RuntimeException is thrown during validation processing, calls FacesContext.renderResponse() and re-throw the exception.

      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)

      In addition to the standard processUpdates behavior inherited from UIComponentBase, calls updateModel(). If the component is invalid afterwards, calls FacesContext.renderResponse(). If a RuntimeException is thrown during update processing, calls FacesContext.renderResponse() and re-throw the exception.

      Overrides:
      processUpdates in class UIComponentBase
      Parameters:
      context - FacesContext for the request we are processing
      Throws:
      NullPointerException - if context is null
    • decode

      public void decode(FacesContext context)
      Description copied from class: UIComponent

      Decode any new state of this UIComponent from the request contained in the specified FacesContext, and store this state as needed.

      During decoding, events may be enqueued for later processing (by event listeners who have registered an interest), by calling queueEvent().

      Overrides:
      decode in class UIComponentBase
      Parameters:
      context - FacesContext for the request we are processing
      Throws:
      NullPointerException - if context is null
    • updateModel

      public void updateModel(FacesContext context)

      Perform the following algorithm to update the model data associated with this UIInput, if any, as appropriate.

      • If the valid property of this component is false, take no further action.
      • If the localValueSet property of this component is false, take no further action.
      • If no ValueExpression for value exists, take no further action.
      • Call setValue() method of the ValueExpression to update the value that the ValueExpression points at.
      • If the setValue() method returns successfully:
        • Clear the local value of this UIInput.
        • Set the localValueSet property of this UIInput to false.
      • If the setValue() method throws an Exception:
      • The exception must not be re-thrown. This enables tree traversal to continue for this lifecycle phase, as in all the other lifecycle phases.
      Parameters:
      context - FacesContext for the request we are processing
      Throws:
      NullPointerException - if context is null
    • validate

      public void validate(FacesContext context)

      Perform the following algorithm to validate the local value of this UIInput.

      Application components implementing UIInput that wish to perform validation with logic embedded in the component should perform their own correctness checks, and then call the super.validate() method to perform the standard processing described above.

      Parameters:
      context - The FacesContext for the current request
      Throws:
      NullPointerException - if context is null
    • getConvertedValue

      protected Object getConvertedValue(FacesContext context, Object newSubmittedValue) throws ConverterException

      Convert the submitted value into a "local value" of the appropriate data type, if necessary. Employ the following algorithm to do so:

      • If a Renderer is present, call getConvertedValue() to convert the submitted value.
      • If no Renderer is present, and the submitted value is a String, locate a Converter as follows:
        • If getConverter() returns a non-null Converter, use that instance.
        • Otherwise, if a value binding for value exists, call getType() on it.
          • If this call returns null, assume the output type is String and perform no conversion.
          • Otherwise, call Application.createConverter(Class) to locate any registered Converter capable of converting data values of the specified type.
      • If a Converter instance was located, call its getAsObject() method to perform the conversion. If conversion fails, the Converter will have thrown a ConverterException which is declared as a checked exception on this method, and thus must be handled by the caller.
      • Otherwise, use the submitted value without any conversion
    • This method can be overridden by subclasses for more specific behavior.