Top Description Inners Fields Constructors Methods
javax.faces.component

public Class UIInput

extends UIOutput
implements EditableValueHolder
Class Inheritance
All Implemented Interfaces
javax.faces.component.EditableValueHolder, javax.faces.component.ValueHolder
Known Direct Subclasses
javax.faces.component.html.HtmlInputTextarea, javax.faces.component.html.HtmlInputText, javax.faces.component.html.HtmlInputSecret, javax.faces.component.html.HtmlInputHidden, javax.faces.component.html.HtmlInputFile, javax.faces.component.UIViewParameter, javax.faces.component.UISelectOne, javax.faces.component.UISelectMany, javax.faces.component.UISelectBoolean
Imports
java.util.Collection, .Iterator, .List, .Map, javax.el.ELException, .ValueExpression, javax.faces.FacesException, javax.faces.application.Application, .FacesMessage, javax.faces.context.ExceptionHandler, .ExternalContext, .FacesContext, javax.faces.convert.Converter, .ConverterException, javax.faces.el.MethodBinding, javax.faces.event.ExceptionQueuedEvent, .ExceptionQueuedEventContext, .PhaseId, .PostValidateEvent, .PreValidateEvent, .ValueChangeEvent, .ValueChangeListener, javax.faces.render.Renderer, javax.faces.validator.BeanValidator, .Validator, .ValidatorException

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 javax.faces.render.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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static enum
UIInput.PropertyKeys

Field Summary

Modifier and TypeField and Description
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.

private static final String
BEANS_VALIDATION_AVAILABLE

public static final String
COMPONENT_FAMILY

Hides javax.faces.component.UIOutput.COMPONENT_FAMILY.

The standard component family for this component.

public static final String
COMPONENT_TYPE

Hides javax.faces.component.UIOutput.COMPONENT_TYPE.

The standard component type for this component.

public static final String
CONVERSION_MESSAGE_ID

The message identifier of the javax.faces.application.FacesMessage to be created if a conversion error occurs, and neither the page author nor the ConverterException provides a message.

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.

private static final Validator<T>[]
EMPTY_VALIDATOR

private transient Boolean
emptyStringIsNull

private transient Boolean
isSetAlwaysValidateRequired

public static final String
REQUIRED_MESSAGE_ID

The message identifier of the javax.faces.application.FacesMessage to be created if a required check fails.

private transient Object
submittedValue

The submittedValue value of this UIInput component.

public static final String
UPDATE_MESSAGE_ID

The message identifier of the javax.faces.application.FacesMessage to be created if a model update error occurs, and the thrown exception has no message.

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.

private transient Boolean
validateEmptyFields

pack-priv AttachedObjectListHolder<Validator<T>>
validators

The set of Validators associated with this UIComponent.

Constructor Summary

AccessConstructor and Description
public
UIInput()

Create a new UIInput instance with default property values.

Method Summary

Modifier and TypeMethod and Description
private void
addConversionErrorMessage(FacesContext context, ConverterException ce)

public void
addValidator(Validator<T>
The Validator to add
validator)

Implements javax.faces.component.EditableValueHolder.addValidator.

Add a Validator instance to the set associated with this UIInput.

public void
addValueChangeListener(ValueChangeListener
The ValueChangeListener to be added
listener)

Implements javax.faces.component.EditableValueHolder.addValueChangeListener.

Add a new ValueChangeListener to the set of listeners interested in being notified when ValueChangeEvents occur.

public void
clearInitialState()

Overrides javax.faces.component.UIOutput.clearInitialState.

Implements javax.faces.component.PartialStateHolder.clearInitialState.

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

protected boolean

Returns:

true if the new value is different from the previous value, false otherwise.
compareValues(Object
old value of this component (if any)
previous, Object
new value of this component (if any)
value)

Return true if the new value is different from the previous value.

private boolean
considerEmptyStringNull(FacesContext ctx)

public void
decode(FacesContext
FacesContext for the request we are processing
context)

Overrides javax.faces.component.UIComponentBase.decode.

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

private void
executeValidate(FacesContext context)

Executes validation logic.

protected Object

Returns:

the converted value.
getConvertedValue(FacesContext
the Faces context.
context, Object
the new submitted value.
newSubmittedValue)

Convert the submitted value into a "local value" of the appropriate data type, if necessary.

public String

Returns:

the converter message.
getConverterMessage()

If there has been a call to setConverterMessage on this instance, return the message.

private Converter<T>
getConverterWithType(FacesContext context)

public String
getFamily()

Overrides javax.faces.component.UIOutput.getFamily.

Return the identifier of the component family to which this component belongs.

public String

Returns:

the required message.
getRequiredMessage()

If there has been a call to setRequiredMessage on this instance, return the message.

public Object
getSubmittedValue()

Implements javax.faces.component.EditableValueHolder.getSubmittedValue.

Return the submittedValue value of this UIInput component.

public MethodBinding
getValidator()

Implements javax.faces.component.EditableValueHolder.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.

public String

Returns:

the validator message.
getValidatorMessage()

If there has been a call to setValidatorMessage on this instance, return the message.

public Validator<T>[]
getValidators()

Implements javax.faces.component.EditableValueHolder.getValidators.

Return the set of registered Validators for this UIInput instance.

public Object
getValue()

Overrides javax.faces.component.UIOutput.getValue.

Implements javax.faces.component.ValueHolder.getValue.

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

public MethodBinding
getValueChangeListener()

Implements javax.faces.component.EditableValueHolder.getValueChangeListener.

Deprecated as a consequence of MethodBinding being deprecated.

If setValueChangeListener was not previously called for this instance, this method must return null.

public ValueChangeListener[]
getValueChangeListeners()

Implements javax.faces.component.EditableValueHolder.getValueChangeListeners.

Return the set of registered ValueChangeListeners for this UIInput instance.

private boolean
isBeansValidationAvailable(FacesContext context)

public static boolean

Returns:

true if it is, false otherwise.
isEmpty(Object
the value to check.
value)

Is the value denoting an empty value.

public boolean
isImmediate()

Implements javax.faces.component.EditableValueHolder.isImmediate.

Return the "immediate" state for this component.

public boolean
isLocalValueSet()

Implements javax.faces.component.EditableValueHolder.isLocalValueSet.

Return the "local value set" state for this component.
public boolean
isRequired()

Implements javax.faces.component.EditableValueHolder.isRequired.

Return the "required field" state for this component.

private boolean
isSetAlwaysValidateRequired(FacesContext context)

public boolean
isValid()

Implements javax.faces.component.EditableValueHolder.isValid.

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

public void
markInitialState()

Overrides javax.faces.component.UIOutput.markInitialState.

Implements javax.faces.component.PartialStateHolder.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 javax.faces.component.PartialStateHolder#markInitialState() as appropriate.

public void
processDecodes(FacesContext
FacesContext for the request we are processing
context)

Overrides javax.faces.component.UIComponentBase.processDecodes.

Specialized decode behavior on top of that provided by the superclass.

public void
processUpdates(FacesContext
FacesContext for the request we are processing
context)

Overrides javax.faces.component.UIComponentBase.processUpdates.

In addition to the standard processUpdates behavior inherited from UIComponentBase, calls updateModel().

public void
processValidators(FacesContext
FacesContext for the request we are processing
context)

Overrides javax.faces.component.UIComponentBase.processValidators.

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.

public void
removeValidator(Validator<T>
The Validator to remove
validator)

Implements javax.faces.component.EditableValueHolder.removeValidator.

Remove a Validator instance from the set associated with this UIInput, if it was previously associated.

public void
removeValueChangeListener(ValueChangeListener
The ValueChangeListener to be removed
listener)

Implements javax.faces.component.EditableValueHolder.removeValueChangeListener.

Remove an existing ValueChangeListener (if any) from the set of listeners interested in being notified when ValueChangeEvents occur.

public void
resetValue()

Overrides javax.faces.component.UIOutput.resetValue.

Implements javax.faces.component.EditableValueHolder.resetValue.

Convenience method to reset this component's value to the un-initialized state.

public void
restoreState(FacesContext
the Faces context.
context, Object
the state.
state)

Overrides javax.faces.component.UIOutput.restoreState.

Implements javax.faces.component.StateHolder.restoreState.

Perform any processing required to restore the state from the entries in the state Object.

public Object
saveState(FacesContext
the Faces context.
context)

Overrides javax.faces.component.UIOutput.saveState.

Implements javax.faces.component.StateHolder.saveState.

Gets the state of the instance as a Serializable Object.

public void
setConverterMessage(String
the literal message value to be displayed in the event conversion fails.
message)

Override any ValueExpression set for the "converterMessage" with the literal argument provided to this method.

public void
setImmediate(boolean
The new "immediate" state
immediate)

Implements javax.faces.component.EditableValueHolder.setImmediate.

Set the "immediate" state for this component.

public void
setLocalValueSet(boolean
the "local value set" boolean.
localValueSet)

Implements javax.faces.component.EditableValueHolder.setLocalValueSet.

Sets the "local value set" state for this component.
public void
setRequired(boolean
The new "required field" state
required)

Implements javax.faces.component.EditableValueHolder.setRequired.

Set the "required field" state for this component.

public void
setRequiredMessage(String
the literal message value to be displayed in the event the user hasn't supplied a value and one is required.
message)

Override any ValueExpression set for the "requiredMessage" with the literal argument provided to this method.

public void
setSubmittedValue(Object
The new submitted value
submittedValue)

Implements javax.faces.component.EditableValueHolder.setSubmittedValue.

Set the submittedValue value of this UIInput component.

public void
setValid(boolean
The new valid flag
valid)

Implements javax.faces.component.EditableValueHolder.setValid.

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

public void
setValidator(MethodBinding
The new MethodBinding instance
validatorBinding)

Implements javax.faces.component.EditableValueHolder.setValidator.

Deprecated Use addValidator instead, obtaining the argument Validator by creating an instance of javax.faces.validator.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.

public void
setValidatorMessage(String
the literal message value to be displayed in the event validation fails.
message)

Override any ValueExpression set for the "validatorMessage" with the literal argument provided to this method.

public void
setValue(Object
The new local value
value)

Overrides javax.faces.component.UIOutput.setValue.

Implements javax.faces.component.ValueHolder.setValue.

Set the value of this UIComponent (if any).

public void
setValueChangeListener(MethodBinding
the value change listener.
valueChangeListener)

Implements javax.faces.component.EditableValueHolder.setValueChangeListener.

Deprecated Use addValueChangeListener instead, obtaining the argument ValueChangeListener by creating an instance of javax.faces.event.MethodExpressionValueChangeListener.

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

public void
updateModel(FacesContext
FacesContext for the request we are processing
context)

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

public void
validate(FacesContext
The FacesContext for the current request
context)

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

private boolean
validateEmptyFields(FacesContext ctx)

protected void
validateValue(FacesContext
the Faces context.
context, Object
the new value.
newValue)

Set the "valid" property according to the below algorithm.

Inherited from javax.faces.component.UIOutput:
getConvertergetLocalValuesetConverter