UIInput (Java(TM) EE 8 Specification APIs)

java.lang.Object
- javax.faces.component.UIComponent
- - javax.faces.component.UIComponentBase
  - - javax.faces.component.UIOutput
    - - javax.faces.component.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 Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE` If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, validation must be performed, even when there is no corresponding value for this component in the incoming request.
`static String`	`COMPONENT_FAMILY` The standard component family for this component.
`static String`	`COMPONENT_TYPE` The standard component type for this component.
`static String`	`CONVERSION_MESSAGE_ID` The message identifier of the `FacesMessage` to be created if a conversion error occurs, and neither the page author nor the `ConverterException` provides a message.
`static String`	`EMPTY_STRING_AS_NULL_PARAM_NAME` The name of a context parameter that indicates how empty strings need to be interpreted.
`static String`	`REQUIRED_MESSAGE_ID` The message identifier of the `FacesMessage` to be created if a required check fails.
`static String`	`UPDATE_MESSAGE_ID` The message identifier of the `FacesMessage` to be created if a model update error occurs, and the thrown exception has no message.
`static String`	`VALIDATE_EMPTY_FIELDS_PARAM_NAME` The name of a context parameter that indicates how empty values should be handled with respect to validation.

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

Constructor Summary

Constructors
Constructor and Description

UIInput()
Create a new UIInput instance with default property values.

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addValidator(Validator validator)` Add a `Validator` instance to the set associated with this `UIInput`.
`void`	`addValueChangeListener(ValueChangeListener listener)` Add a new `ValueChangeListener` to the set of listeners interested in being notified when `ValueChangeEvent`s occur.
`void`	`clearInitialState()` For each of the attached objects on this instance that implement `PartialStateHolder`, call `PartialStateHolder.clearInitialState()` on the attached object.
`protected boolean`	`compareValues(Object previous, Object value)` Return `true` if the new value is different from the previous value.
`void`	`decode(FacesContext context)` Decode any new state of this `UIComponent` from the request contained in the specified `FacesContext`, and store this state as needed.
`protected Object`	`getConvertedValue(FacesContext context, Object newSubmittedValue)` Convert the submitted value into a "local value" of the appropriate data type, if necessary.
`String`	`getConverterMessage()` If there has been a call to `setConverterMessage(java.lang.String)` on this instance, return the message.
`String`	`getFamily()` Return the identifier of the component family to which this component belongs.
`String`	`getRequiredMessage()` If there has been a call to `setRequiredMessage(java.lang.String)` on this instance, return the message.
`Object`	`getSubmittedValue()` Return the submittedValue value of this `UIInput` component.
`MethodBinding`	`getValidator()` Deprecated. `getValidators()` should be used instead.
`String`	`getValidatorMessage()` If there has been a call to `setValidatorMessage(java.lang.String)` on this instance, return the message.
`Validator[]`	`getValidators()` Return the set of registered `Validator`s for this `UIInput` instance.
`Object`	`getValue()` If there is a local value, return it, otherwise return the result of calling `super.getVaue()`.
`MethodBinding`	`getValueChangeListener()` If `EditableValueHolder.setValueChangeListener(javax.faces.el.MethodBinding)` was not previously called for this instance, this method must return `null`.
`ValueChangeListener[]`	`getValueChangeListeners()` Return the set of registered `ValueChangeListener`s for this `UIInput` instance.
`static boolean`	`isEmpty(Object value)` Is the value denoting an empty value.
`boolean`	`isImmediate()` Return the "immediate" state for this component.
`boolean`	`isLocalValueSet()` Return the "local value set" state for this component.
`boolean`	`isRequired()` Return the "required field" state for this component.
`boolean`	`isValid()` Return a flag indicating whether the local value of this component is valid (no conversion error has occurred).
`void`	`markInitialState()` In addition to the actions taken in `UIOutput` when `PartialStateHolder.markInitialState()` is called, check if any of the installed `Validator`s are PartialStateHolders and if so, call `PartialStateHolder.markInitialState()` as appropriate.
`void`	`processDecodes(FacesContext context)` Specialized decode behavior on top of that provided by the superclass.
`void`	`processUpdates(FacesContext context)` In addition to the standard `processUpdates` behavior inherited from `UIComponentBase`, calls `updateModel()`.
`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()`.
`void`	`removeValidator(Validator validator)` Remove a `Validator` instance from the set associated with this `UIInput`, if it was previously associated.
`void`	`removeValueChangeListener(ValueChangeListener listener)` Remove an existing `ValueChangeListener` (if any) from the set of listeners interested in being notified when `ValueChangeEvent`s occur.
`void`	`resetValue()` Convenience method to reset this component's value to the un-initialized state.
`void`	`restoreState(FacesContext context, Object state)` Perform any processing required to restore the state from the entries in the state Object.
`Object`	`saveState(FacesContext context)` Gets the state of the instance as a `Serializable` Object.
`void`	`setConverterMessage(String message)` Override any `ValueExpression` set for the "converterMessage" with the literal argument provided to this method.
`void`	`setImmediate(boolean immediate)` Set the "immediate" state for this component.
`void`	`setLocalValueSet(boolean localValueSet)` Sets the "local value set" state for this component.
`void`	`setRequired(boolean required)` Set the "required field" state for this component.
`void`	`setRequiredMessage(String message)` Override any `ValueExpression` set for the "requiredMessage" with the literal argument provided to this method.
`void`	`setSubmittedValue(Object submittedValue)` Set the submittedValue value of this `UIInput` component.
`void`	`setValid(boolean valid)` Set a flag indicating whether the local value of this component is valid (no conversion error has occurred).
`void`	`setValidator(MethodBinding validatorBinding)` Deprecated. Use `addValidator(javax.faces.validator.Validator)` instead, obtaining the argument `Validator` by creating an instance of `MethodExpressionValidator`.
`void`	`setValidatorMessage(String message)` Override any `ValueExpression` set for the "validatorMessage" with the literal argument provided to this method.
`void`	`setValue(Object value)` Set the value of this `UIComponent` (if any).
`void`	`setValueChangeListener(MethodBinding valueChangeListener)` Deprecated. Use `addValueChangeListener(javax.faces.event.ValueChangeListener)` instead, obtaining the argument `ValueChangeListener` by creating an instance of `MethodExpressionValueChangeListener`.
`void`	`updateModel(FacesContext context)` Perform the following algorithm to update the model data associated with this `UIInput`, if any, as appropriate.
`void`	`validate(FacesContext context)` Perform the following algorithm to validate the local value of this `UIInput`.
`protected void`	`validateValue(FacesContext context, Object newValue)` Set the "valid" property according to the below algorithm.

Methods inherited from class javax.faces.component.UIOutput
getConverter, getLocalValue, setConverter

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.faces.component.ValueHolder
getConverter, getLocalValue, setConverter

- 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
  - CONVERSION_MESSAGE_ID
```
public static final String CONVERSION_MESSAGE_ID
```
    The message identifier of the FacesMessage to be created if a conversion error occurs, and neither the page author nor the ConverterException provides a message.
    
    See Also:
    
    Constant Field Values
  - REQUIRED_MESSAGE_ID
```
public static final String REQUIRED_MESSAGE_ID
```
    The message identifier of the FacesMessage to be created if a required check fails.
    
    See Also:
    
    Constant Field Values
  - UPDATE_MESSAGE_ID
```
public static final String UPDATE_MESSAGE_ID
```
    The message identifier of the FacesMessage to be created if a model update error occurs, and the thrown exception has no message.
    
    See Also:
    
    Constant Field Values
  - VALIDATE_EMPTY_FIELDS_PARAM_NAME
```
public static final String VALIDATE_EMPTY_FIELDS_PARAM_NAME
```
    The name of a context parameter that indicates how empty values should be handled with respect to validation. See validateValue(javax.faces.context.FacesContext, java.lang.Object) for the allowable values and specification of how they should be interpreted.
    
    See Also:
    
    Constant Field Values
  - EMPTY_STRING_AS_NULL_PARAM_NAME
```
public static final String EMPTY_STRING_AS_NULL_PARAM_NAME
```
    The name of a context parameter that indicates how empty strings need to be interpreted.
    
    See Also:
    
    Constant Field Values
  - ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE
```
public static final String ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE
```
    If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, validation must be performed, even when there is no corresponding value for this component in the incoming request. See validate(javax.faces.context.FacesContext).
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - UIInput
```
public UIInput()
```
    Create a new UIInput 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. Note this method should NOT return null
    
    Overrides:
    
    getFamily in class UIOutput
    
    Returns:
    
    the component family (not null).
  - 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
    
    Returns:
    
    the submitted value.
  - 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
    
    Returns:
    
    the value.
    
    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.
    
    Clear state for property localValueSet.
    
    Clear state for property valid.
    
    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
    
    Returns:
    
    true if the local value is set, false otherwise.
  - setLocalValueSet
```
public void setLocalValueSet(boolean localValueSet)
```
    Sets the "local value set" state for this component.
    
    Specified by:
    
    setLocalValueSet in interface EditableValueHolder
    
    Parameters:
    
    localValueSet - the "local value set" boolean.
  - isRequired
```
public boolean isRequired()
```
    Return the "required field" state for this component.
    
    Specified by:
    
    isRequired in interface EditableValueHolder
    
    Returns:
    
    true if required, false otherwise.
  - 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.
    
    Returns:
    
    the required message.
  - 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.
    
    Returns:
    
    the converter message.
  - 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.
    
    Returns:
    
    the validator message.
  - 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
    
    Returns:
    
    true if valid, false otherwise.
  - 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
    
    Returns:
    
    true if is immediate, false otherwise.
  - 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
    
    Returns:
    
    the validator as a method binding.
  - 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
    
    Returns:
    
    the value change listener.
  - setValueChangeListener
```
public void setValueChangeListener(MethodBinding valueChangeListener)
```
    Deprecated. Use addValueChangeListener(javax.faces.event.ValueChangeListener) instead, obtaining the argument ValueChangeListener by creating an instance of MethodExpressionValueChangeListener.
    
    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 value change listener.
  - 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(). To ensure the PostValidateEvent is published at the proper time, this component must be validated first, followed by the component's children and facets. 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
    
    See Also:
    
    PreValidateEvent, PostValidateEvent
  - 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:
      
      Enqueue an error message. Create a FacesMessage with the id UPDATE_MESSAGE_ID. Create a UpdateModelException, passing the FacesMessage and the caught exception to the constructor. Create an ExceptionQueuedEventContext, passing the FacesContext, the UpdateModelException, this component instance, and PhaseId.UPDATE_MODEL_VALUES to its constructor. Call FacesContext.getExceptionHandler() and then call ExceptionHandler.processEvent(javax.faces.event.SystemEvent), passing the ExceptionQueuedEventContext.
      
      Set the valid property of this UIInput to false.
      
      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.
    - Retrieve the submitted value with getSubmittedValue(). If this returns null, and the value of the ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE context-param is true (ignoring case), examine the value of the "required" property. If the value of "required" is true, continue as below. If the value of "required" is false or the required attribute is not set, exit without further processing. If the context-param is not set, or is set to false (ignoring case), exit without further processing. (This indicates that no value was submitted for this component.)
    - If the javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL context parameter value is true (ignoring case), and getSubmittedValue() returns a zero-length String call setSubmittedValue(java.lang.Object), passing null as the argument and continue processing using null as the current submitted value.
    - Convert the submitted value into a "local value" of the appropriate data type by calling getConvertedValue(javax.faces.context.FacesContext, java.lang.Object).
    - If conversion fails:
      
      Enqueue an appropriate error message by calling the addMessage() method on the FacesContext.
      
      Set the valid property on this component to false
    - Validate the property by calling validateValue(javax.faces.context.FacesContext, java.lang.Object).
    - If the valid property of this component is still true, retrieve the previous value of the component (with getValue()), store the new local value using setValue(), and reset the submitted value to null with a call to setSubmittedValue(java.lang.Object) passing null as the argument. If the local value is different from the previous value of this component, as determined by a call to compareValues(java.lang.Object, java.lang.Object), fire a ValueChangeEvent to be broadcast to all interested listeners.
    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.
    Parameters:
    
    context - the Faces context.
    
    newSubmittedValue - the new submitted value.
    
    Returns:
    
    the converted value.
    
    Throws:
    
    ConverterException
  - validateValue
```
protected void validateValue(FacesContext context,
                             Object newValue)
```
    Set the "valid" property according to the below algorithm.
    - If the valid property on this component is still true, and the required property is also true, ensure that the local value is not empty (where "empty" is defined as null or a zero-length String). If the local value is empty:
      
      Enqueue an appropriate error message by calling the addMessage() method on the FacesContext instance for the current request. If the getRequiredMessage() returns non-null, use the value as the summary and detail in the FacesMessage that is enqueued on the FacesContext, otherwise use the message for the REQUIRED_MESSAGE_ID.
      
      Set the valid property on this component to false.
      
      If calling ValidatorException.getFacesMessages() returns non-null, each message should be added to the FacesContext. Otherwise the single message returned from ValidatorException.getFacesMessage() should be added.
    - Otherwise, if the valid property on this component is still true, take the following action to determine if validation of this component should proceed.
      
      If the value is not empty, validation should proceed.
      
      If the value is empty, but the system has been directed to validate empty fields, validation should proceed. The implementation must obtain the init parameter Map from the ExternalContext and inspect the value for the key given by the value of the symbolic constant VALIDATE_EMPTY_FIELDS_PARAM_NAME. If there is no value under that key, use the same key and look in the application map from the ExternalContext. If the value is null or equal to the string “auto” (without the quotes) take appropriate action to determine if Bean Validation is present in the runtime environment. If not, validation should not proceed. If so, validation should proceed. If the value is equal (ignoring case) to “true” (without the quotes) validation should proceed. Otherwise, validation should not proceed.
      
      If the above determination indicates that validation should proceed, call the validate() method of each Validator registered for this UIInput, followed by the method pointed at by the validatorBinding property (if any). If any of these validators or the method throws a ValidatorException, catch the exception, add its message (if any) to the FacesContext, and set the valid property of this component to false.
    Parameters:
    
    context - the Faces context.
    
    newValue - the new value.
  - compareValues
```
protected boolean compareValues(Object previous,
                                Object value)
```
    Return true if the new value is different from the previous value. First compare the two values by passing value to the equals method on argument previous. If that method returns true, return true. If that method returns false, and both arguments implement java.lang.Comparable, compare the two values by passing value to the compareTo method on argument previous. Return true if this method returns 0, false otherwise.
    
    Parameters:
    
    previous - old value of this component (if any)
    
    value - new value of this component (if any)
    
    Returns:
    
    true if the new value is different from the previous value, false otherwise.
  - isEmpty
```
public static boolean isEmpty(Object value)
```
    Is the value denoting an empty value.
    
    If the value is null, return true. If the value is a String and it is the empty string, return true. If the value is an array and the array length is 0, return true. If the value is a List and the List is empty, return true. If the value is a Collection and the Collection is empty, return true. If the value is a Map and the Map is empty, return true. In all other cases, return false.
    
    Parameters:
    
    value - the value to check.
    
    Returns:
    
    true if it is, false otherwise.
  - addValidator
```
public void addValidator(Validator validator)
```
    Add a Validator instance to the set associated with this UIInput.
    
    Specified by:
    
    addValidator in interface EditableValueHolder
    
    Parameters:
    
    validator - The Validator to add
    
    Throws:
    
    NullPointerException - if validator is null
  - getValidators
```
public Validator[] getValidators()
```
    Return the set of registered Validators for this UIInput instance. If there are no registered validators, a zero-length array is returned.
    
    Specified by:
    
    getValidators in interface EditableValueHolder
    
    Returns:
    
    the validators, or a zero-length array.
  - removeValidator
```
public void removeValidator(Validator validator)
```
    Remove a Validator instance from the set associated with this UIInput, if it was previously associated. Otherwise, do nothing.
    
    Specified by:
    
    removeValidator in interface EditableValueHolder
    
    Parameters:
    
    validator - The Validator to remove
  - addValueChangeListener
```
public void addValueChangeListener(ValueChangeListener listener)
```
    Add a new ValueChangeListener to the set of listeners interested in being notified when ValueChangeEvents occur.
    
    Specified by:
    
    addValueChangeListener in interface EditableValueHolder
    
    Parameters:
    
    listener - The ValueChangeListener to be added
    
    Throws:
    
    NullPointerException - if listener is null
  - getValueChangeListeners
```
public ValueChangeListener[] getValueChangeListeners()
```
    Return the set of registered ValueChangeListeners for this UIInput instance. If there are no registered listeners, a zero-length array is returned.
    
    Specified by:
    
    getValueChangeListeners in interface EditableValueHolder
    
    Returns:
    
    the value change listeners, or a zero-length array.
  - removeValueChangeListener
```
public void removeValueChangeListener(ValueChangeListener listener)
```
    Remove an existing ValueChangeListener (if any) from the set of listeners interested in being notified when ValueChangeEvents occur.
    
    Specified by:
    
    removeValueChangeListener in interface EditableValueHolder
    
    Parameters:
    
    listener - The ValueChangeListener to be removed
    
    Throws:
    
    NullPointerException - if listener is null
  - saveState
```
public Object saveState(FacesContext context)
```
    Description copied from interface: StateHolder
    Gets the state of the instance as a Serializable Object.
    
    If the class that implements this interface has references to instances that implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.saveState(javax.faces.context.FacesContext) method on all those instances as well. This method must not save the state of children and facets. That is done via the StateManager
    
    This method must not alter the state of the implementing object. In other words, after executing this code:
```
 Object state = component.saveState(facesContext);
 
```
    component should be the same as before executing it.
    
    The return from this method must be Serializable
    Specified by:
    
    saveState in interface StateHolder
    
    Overrides:
    
    saveState in class UIOutput
    
    Parameters:
    
    context - the Faces context.
    
    Returns:
    
    the saved state.
  - restoreState
```
public void restoreState(FacesContext context,
                         Object state)
```
    Description copied from interface: StateHolder
    
    Perform any processing required to restore the state from the entries in the state Object.
    
    If the class that implements this interface has references to instances that also implement StateHolder (such as a UIComponent with event handlers, validators, etc.) this method must call the StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object) method on all those instances as well.
    
    If the state argument is null, take no action and return.
    
    Specified by:
    
    restoreState in interface StateHolder
    
    Overrides:
    
    restoreState in class UIOutput
    
    Parameters:
    
    context - the Faces context.
    
    state - the state.

Class UIInput

Field Summary

Fields inherited from class javax.faces.component.UIComponent

Constructor Summary

Method Summary

Methods inherited from class javax.faces.component.UIOutput

Methods inherited from class javax.faces.component.UIComponentBase

Methods inherited from class javax.faces.component.UIComponent

Methods inherited from class java.lang.Object

Methods inherited from interface javax.faces.component.ValueHolder

Field Detail

COMPONENT_TYPE

COMPONENT_FAMILY

CONVERSION_MESSAGE_ID

REQUIRED_MESSAGE_ID

UPDATE_MESSAGE_ID

VALIDATE_EMPTY_FIELDS_PARAM_NAME

EMPTY_STRING_AS_NULL_PARAM_NAME

ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE

Constructor Detail

UIInput

Method Detail

getFamily

getSubmittedValue

setSubmittedValue

getValue

setValue

resetValue

isLocalValueSet

setLocalValueSet

isRequired

getRequiredMessage

setRequiredMessage

getConverterMessage

setConverterMessage

getValidatorMessage

setValidatorMessage

isValid

setValid

setRequired

isImmediate

setImmediate

getValidator

setValidator

getValueChangeListener

setValueChangeListener

markInitialState

clearInitialState

processDecodes

processValidators

processUpdates

decode

updateModel

validate

getConvertedValue

validateValue

compareValues

isEmpty

addValidator

getValidators

removeValidator

addValueChangeListener

getValueChangeListeners

removeValueChangeListener

saveState

restoreState