Class UIInput
- java.lang.Object
- 
- jakarta.faces.component.UIComponent
- 
- jakarta.faces.component.UIComponentBase
- 
- jakarta.faces.component.UIOutput
- 
- jakarta.faces.component.UIInput
 
 
 
 
- 
- All Implemented Interfaces:
- EditableValueHolder,- PartialStateHolder,- StateHolder,- TransientStateHolder,- ValueHolder,- ComponentSystemEventListener,- FacesListener,- SystemEventListenerHolder,- EventListener
 - Direct Known Subclasses:
- HtmlInputFile,- HtmlInputHidden,- HtmlInputSecret,- HtmlInputText,- HtmlInputTextarea,- UISelectBoolean,- UISelectMany,- UISelectOne,- UIViewParameter
 
 @JSFComponent(defaultRendererType="jakarta.faces.Text") public class UIInput extends UIOutput implements EditableValueHolder UICommand is a base abstraction for components that implement ActionSource.See the javadoc for this class in the JSF Specification for further details. 
- 
- 
Field SummaryFields Modifier and Type Field Description static StringALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUEIf set to true, validation is always performed when required is true.static StringCOMPONENT_FAMILYstatic StringCOMPONENT_TYPEstatic StringCONVERSION_MESSAGE_IDstatic StringEMPTY_STRING_AS_NULL_PARAM_NAMESubmitted values are decoded as null values instead empty strings.static StringREQUIRED_MESSAGE_IDstatic StringUPDATE_MESSAGE_IDstatic StringVALIDATE_EMPTY_FIELDS_PARAM_NAMEForce validation on empty fields (By default is auto, which means it is only enabled when Bean Validation binaries are available on the current classpath).- 
Fields inherited from class jakarta.faces.component.UIComponentATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY
 
- 
 - 
Constructor SummaryConstructors Constructor Description UIInput()Construct an instance of the UIInput.
 - 
Method SummaryAll Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddValidator(Validator validator)See getValidator.voidaddValueChangeListener(ValueChangeListener listener)voidbroadcast(FacesEvent event)Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.voidclearInitialState()protected booleancompareValues(Object previous, Object value)voiddecode(FacesContext context)Check the submitted form parameters for data associated with this component.protected ObjectgetConvertedValue(FacesContext context, Object submittedValue)Convert the provided object to the desired value.StringgetConverterMessage()Text to be displayed to the user as an error message when conversion of a submitted value to the target type fails.StringgetFamily()StringgetRequiredMessage()Text to be displayed to the user as an error message when this component is marked as "required" but no input data is present during a postback (ie the user left the required field blank).ObjectgetSubmittedValue()Gets the current submitted value.StringgetValidatorMessage()Text which will be shown if validation fails.Validator[]getValidators()See getValidator.ObjectgetValue()Return the current value of this component.ValueChangeListener[]getValueChangeListeners()The valueChange event is delivered when the value attribute is changed.static booleanisEmpty(Object value)Check if a value is empty or not.booleanisImmediate()A boolean value that identifies the phase during which action events should fire.booleanisLocalValueSet()Specifies whether a local value is currently set.booleanisRequired()A boolean value that indicates whether an input value is required.booleanisValid()Specifies whether the component's value is currently valid, ie whether the validators attached to this component have allowed it.voidmarkInitialState()voidprocessDecodes(FacesContext context)Set the "submitted value" of this component from the relevant data in the current servlet request object.voidprocessUpdates(FacesContext context)This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.voidprocessValidators(FacesContext context)voidremoveValidator(Validator validator)See getValidator.voidremoveValueChangeListener(ValueChangeListener listener)voidresetValue()Convenience method to reset this component's value to an uninitialized state, by resetting the local value and submitted values to null (ensuring thatEditableValueHolder.isLocalValueSet()is false), and setting "valid" to true.voidrestoreState(FacesContext facesContext, Object state)Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.ObjectsaveState(FacesContext facesContext)Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.voidsetConverterMessage(String converterMessage)voidsetImmediate(boolean immediate)voidsetLocalValueSet(boolean localValueSet)Specify the return value of method isLocalValueSet.voidsetRequired(boolean required)Set to true to cause validation failure when a form containing this component is submitted and there is no value selected for this component.voidsetRequiredMessage(String requiredMessage)voidsetSubmittedValue(Object submittedValue)Invoked during the "decode" phase of processing to inform this component what data was received from the user.voidsetValid(boolean valid)voidsetValidatorMessage(String validatorMessage)voidsetValue(Object value)Store the specified object as the "local value" of this component.voidupdateModel(FacesContext context)voidvalidate(FacesContext context)Determine whether the new value is valid, and queue a ValueChangeEvent if necessary.protected voidvalidateValue(FacesContext context, Object convertedValue)- 
Methods inherited from class jakarta.faces.component.UIOutputgetConverter, getLocalValue, setConverter
 - 
Methods inherited from class jakarta.faces.component.UIComponentBaseaddClientBehavior, addFacesListener, encodeAll, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, visitTree
 - 
Methods inherited from class jakarta.faces.component.UIComponentgetClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getListenersForEventClass, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, subscribeToEvent, unsubscribeFromEvent
 - 
Methods inherited from class java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 - 
Methods inherited from interface jakarta.faces.component.ValueHoldergetConverter, getLocalValue, setConverter
 
- 
 
- 
- 
- 
Field Detail- 
COMPONENT_TYPEpublic static final String COMPONENT_TYPE - See Also:
- Constant Field Values
 
 - 
COMPONENT_FAMILYpublic static final String COMPONENT_FAMILY - See Also:
- Constant Field Values
 
 - 
CONVERSION_MESSAGE_IDpublic static final String CONVERSION_MESSAGE_ID - See Also:
- Constant Field Values
 
 - 
REQUIRED_MESSAGE_IDpublic static final String REQUIRED_MESSAGE_ID - See Also:
- Constant Field Values
 
 - 
UPDATE_MESSAGE_IDpublic static final String UPDATE_MESSAGE_ID - See Also:
- Constant Field Values
 
 - 
VALIDATE_EMPTY_FIELDS_PARAM_NAME@JSFWebConfigParam(defaultValue="auto", expectedValues="auto, true, false", since="2.0", group="validation") public static final String VALIDATE_EMPTY_FIELDS_PARAM_NAMEForce validation on empty fields (By default is auto, which means it is only enabled when Bean Validation binaries are available on the current classpath).- See Also:
- Constant Field Values
 
 - 
EMPTY_STRING_AS_NULL_PARAM_NAME@JSFWebConfigParam(defaultValue="false", expectedValues="true, false", since="2.0", group="validation") public static final String EMPTY_STRING_AS_NULL_PARAM_NAMESubmitted values are decoded as null values instead empty strings.Note this param is ignored for components extending from UISelectOne/UISelectMany. - See Also:
- Constant Field Values
 
 - 
ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE@JSFWebConfigParam(defaultValue="false", expectedValues="true, false", since="2.3", group="validation") public static final String ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUEIf set to true, validation is always performed when required is true.- See Also:
- Constant Field Values
 
 
- 
 - 
Method Detail- 
setValuepublic void setValue(Object value) Store the specified object as the "local value" of this component. The value-binding named "value" (if any) is ignored; the object is only stored locally on this component. During the "update model" phase, if there is a value-binding named "value" then this local value will be stored via that value-binding and the "local value" reset to null.- Specified by:
- setValuein interface- ValueHolder
- Overrides:
- setValuein class- UIOutput
 
 - 
getValue@JSFExclude @JSFProperty(clientEvent="valueChange") public Object getValue() Return the current value of this component.If a submitted value has been converted but not yet pushed into the model, then return that locally-cached value (see isLocalValueSet). Otherwise, evaluate an EL expression to fetch a value from the model.- Specified by:
- getValuein interface- ValueHolder
- Overrides:
- getValuein class- UIOutput
- Returns:
- the new value value
 
 - 
processDecodespublic void processDecodes(FacesContext context) Set the "submitted value" of this component from the relevant data in the current servlet request object.If this component is not rendered, then do nothing; no output would have been sent to the client so no input is expected. Invoke the inherited functionality, which typically invokes the renderer associated with this component to extract and set this component's "submitted value". If this component is marked "immediate", then immediately apply validation to the submitted value found. On error, call context method "renderResponse" which will force processing to leap to the "render response" phase as soon as the "decode" step has completed for all other components. - Overrides:
- processDecodesin class- UIComponentBase
 
 - 
processValidatorspublic void processValidators(FacesContext context) - Overrides:
- processValidatorsin class- UIComponentBase
 
 - 
processUpdatespublic void processUpdates(FacesContext context) Description copied from class:UIComponentBaseThis isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.Components that were never rendered can't possibly be receiving update data (no corresponding fields were ever put into the response) so if this component is not rendered then this method does not invoke processUpdates on its children. - Overrides:
- processUpdatesin class- UIComponentBase
 
 - 
decodepublic void decode(FacesContext context) Description copied from class:UIComponentBaseCheck the submitted form parameters for data associated with this component. This default implementation delegates to this component's renderer if there is one, and otherwise ignores the call.- Overrides:
- decodein class- UIComponentBase
 
 - 
broadcastpublic void broadcast(FacesEvent event) throws AbortProcessingException Description copied from class:UIComponentBaseInvoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.This method does not propagate the event up to parent components, ie listeners attached to parent components don't automatically get called. If any of the listeners throws AbortProcessingException then that exception will prevent any further listener callbacks from occurring, and the exception propagates out of this method without alteration. ActionEvent events are typically queued by the renderer associated with this component in its decode method; ValueChangeEvent events by the component's validate method. In either case the event's source property references a component. At some later time the UIViewRoot component iterates over its queued events and invokes the broadcast method on each event's source object. - Overrides:
- broadcastin class- UIComponentBase
- Parameters:
- event- must not be null.
- Throws:
- AbortProcessingException
 
 - 
updateModelpublic void updateModel(FacesContext context) 
 - 
validateValueprotected void validateValue(FacesContext context, Object convertedValue) 
 - 
validatepublic void validate(FacesContext context) Determine whether the new value is valid, and queue a ValueChangeEvent if necessary.The "submitted value" is converted to the necessary type; conversion failure is reported as an error and validation processing terminates for this component. See documentation for method getConvertedValue for details on the conversion process. Any validators attached to this component are then run, passing the converted value. The old value of this component is then fetched (possibly involving the evaluation of a value-binding expression, ie invoking a method on a user object). The old value is compared to the new validated value, and if they are different then a ValueChangeEvent is queued for later processing. On successful completion of this method: - isValid() is true
- isLocalValueSet() is true
- submittedValue is reset to null
- a ValueChangeEvent is queued if the new value != old value
 
 - 
getConvertedValueprotected Object getConvertedValue(FacesContext context, Object submittedValue) throws ConverterException Convert the provided object to the desired value.If there is a renderer for this component, then call the renderer's getConvertedValue method. While this can of course be implemented in any way the renderer desires, it typically performs exactly the same processing that this method would have done anyway (ie that described below for the no-renderer case). Otherwise: - If the submittedValue is not a String then just return the submittedValue unconverted.
- If there is no "value" value-binding then just return the submittedValue unconverted.
- Use introspection to determine the type of the target property specified by the value-binding, and then use Application.createConverter to find a converter that can map from String to the required type. Apply the converter to the submittedValue and return the result.
 - Throws:
- ConverterException
 
 - 
resetValuepublic void resetValue() Description copied from interface:EditableValueHolderConvenience method to reset this component's value to an uninitialized state, by resetting the local value and submitted values to null (ensuring thatEditableValueHolder.isLocalValueSet()is false), and setting "valid" to true.- Specified by:
- resetValuein interface- EditableValueHolder
- Overrides:
- resetValuein class- UIOutput
- Since:
- 1.2
 
 - 
isImmediate@JSFProperty public boolean isImmediate() A boolean value that identifies the phase during which action events should fire.During normal event processing, action methods and action listener methods are fired during the "invoke application" phase of request processing. If this attribute is set to "true", these methods are fired instead at the end of the "apply request values" phase. - Specified by:
- isImmediatein interface- EditableValueHolder
 
 - 
setImmediatepublic void setImmediate(boolean immediate) - Specified by:
- setImmediatein interface- EditableValueHolder
 
 - 
isRequired@JSFProperty(defaultValue="false") public boolean isRequired() A boolean value that indicates whether an input value is required.If this value is true and no input value is provided by a postback operation, then the "requiredMessage" text is registered as a FacesMessage for the request, and validation fails. Default value: false. - Specified by:
- isRequiredin interface- EditableValueHolder
 
 - 
setRequiredpublic void setRequired(boolean required) Description copied from interface:EditableValueHolderSet to true to cause validation failure when a form containing this component is submitted and there is no value selected for this component.- Specified by:
- setRequiredin interface- EditableValueHolder
 
 - 
getConverterMessage@JSFProperty public String getConverterMessage() Text to be displayed to the user as an error message when conversion of a submitted value to the target type fails.
 - 
setConverterMessagepublic void setConverterMessage(String converterMessage) 
 - 
getRequiredMessage@JSFProperty public String getRequiredMessage() Text to be displayed to the user as an error message when this component is marked as "required" but no input data is present during a postback (ie the user left the required field blank).
 - 
setRequiredMessagepublic void setRequiredMessage(String requiredMessage) 
 - 
addValidatorpublic void addValidator(Validator validator) See getValidator.- Specified by:
- addValidatorin interface- EditableValueHolder
 
 - 
removeValidatorpublic void removeValidator(Validator validator) See getValidator.- Specified by:
- removeValidatorin interface- EditableValueHolder
 
 - 
getValidatorspublic Validator[] getValidators() See getValidator.- Specified by:
- getValidatorsin interface- EditableValueHolder
 
 - 
getValidatorMessage@JSFProperty public String getValidatorMessage() Text which will be shown if validation fails.
 - 
setValidatorMessagepublic void setValidatorMessage(String validatorMessage) 
 - 
isValid@JSFProperty(defaultValue="true", tagExcluded=true) public boolean isValid()Specifies whether the component's value is currently valid, ie whether the validators attached to this component have allowed it.- Specified by:
- isValidin interface- EditableValueHolder
 
 - 
setValidpublic void setValid(boolean valid) - Specified by:
- setValidin interface- EditableValueHolder
 
 - 
isLocalValueSet@JSFProperty(defaultValue="false", tagExcluded=true) public boolean isLocalValueSet()Specifies whether a local value is currently set.If false, values are being retrieved from any attached ValueBinding. - Specified by:
- isLocalValueSetin interface- EditableValueHolder
 
 - 
setLocalValueSetpublic void setLocalValueSet(boolean localValueSet) Description copied from interface:EditableValueHolderSpecify the return value of method isLocalValueSet. This is called after the local value member has been set from the converted and validated "submitted value". It is cleared after that value has been pushed to the user model via the value-binding named "value".- Specified by:
- setLocalValueSetin interface- EditableValueHolder
 
 - 
getSubmittedValue@JSFProperty(tagExcluded=true) public Object getSubmittedValue() Gets the current submitted value. This value, if non-null, is set by the Renderer to store a possibly invalid value for later conversion or redisplay, and has not yet been converted into the proper type for this component instance. This method should only be used by the decode() and validate() method of this component, or its corresponding Renderer; however, user code may manually set it to null to erase any submitted value.- Specified by:
- getSubmittedValuein interface- EditableValueHolder
 
 - 
setSubmittedValuepublic void setSubmittedValue(Object submittedValue) Description copied from interface:EditableValueHolderInvoked during the "decode" phase of processing to inform this component what data was received from the user.In many cases the submitted value is a plain string extracted from the current servlet request object. In cases where a component is rendered as multiple input components (eg a calendar control with separate day/month/year fields), the submittedValue may be some custom object wrapping the data. However the provided object must be able to represent all possible user input values, not just valid ones. - Specified by:
- setSubmittedValuein interface- EditableValueHolder
 
 - 
addValueChangeListenerpublic void addValueChangeListener(ValueChangeListener listener) - Specified by:
- addValueChangeListenerin interface- EditableValueHolder
 
 - 
removeValueChangeListenerpublic void removeValueChangeListener(ValueChangeListener listener) - Specified by:
- removeValueChangeListenerin interface- EditableValueHolder
 
 - 
getValueChangeListeners@JSFListener(event="jakarta.faces.event.ValueChangeEvent") public ValueChangeListener[] getValueChangeListeners() The valueChange event is delivered when the value attribute is changed.- Specified by:
- getValueChangeListenersin interface- EditableValueHolder
 
 - 
markInitialStatepublic void markInitialState() - Specified by:
- markInitialStatein interface- PartialStateHolder
- Overrides:
- markInitialStatein class- UIOutput
 
 - 
clearInitialStatepublic void clearInitialState() Description copied from class:UIComponent- Specified by:
- clearInitialStatein interface- PartialStateHolder
- Overrides:
- clearInitialStatein class- UIOutput
 
 - 
saveStatepublic Object saveState(FacesContext facesContext) Description copied from class:UIComponentBaseInvoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.- Specified by:
- saveStatein interface- StateHolder
- Overrides:
- saveStatein class- UIOutput
 
 - 
restoreStatepublic void restoreState(FacesContext facesContext, Object state) Description copied from class:UIComponentBaseInvoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.- Specified by:
- restoreStatein interface- StateHolder
- Overrides:
- restoreStatein class- UIOutput
- state- is an object previously returned by the saveState method of this class.
 
 - 
isEmptypublic static boolean isEmpty(Object value) Check if a value is empty or not. Since we don't know the class of value we have to check and deal with it properly.- Parameters:
- value-
- Returns:
- Since:
- 2.0
 
 
- 
 
-