UIInput (Java EE 5)

UIInput 是表示某个组件的 UIComponent，该组件既向用户显示输出（就像 UIOutput 组件所做的），又处理需要解码的后续请求的请求参数。对本地值的数据类型或值绑定表达式引用的对象（如果有）没有限制；但是，各 javax.faces.render.Renderer 通常会对其知道如何显示的数据类型施加限制。

在请求处理生命周期的应用请求值 阶段，必须使用 setSubmittedValue() 存储（但尚未转换）此组件的解码值（通常但并非一定为 String）。如果该组件要指示没有提交过特定的值，则它可以不执行任何操作，也可以将提交的值设置为 null。

默认情况下，在请求处理生命周期的处理验证器 阶段，提交的值将被转换为类型安全对象，而且如果验证成功，则使用 setValue() 将其存储为本地值。但是，如果 immediate 属性设置为 true，则此处理将会改在应用请求值 阶段的末尾进行。

在请求处理生命周期的呈现响应 阶段，进行输出转换，这与 UIOutput 相同。

当此 UIInput 的 validate() 方法检测到实际已发生值更改，而且已成功通过所有验证，它会将 ValueChangeEvent 排队。之后，broadcast() 方法将确保此事件广播到所有感兴趣的侦听器。默认情况下，此事件将在处理验证器 阶段传送，但如果 immediate 属性设置为 true，也可改在应用请求值 阶段传送。

默认情况下，rendererType 属性必须设置为 "Text"。可以调用 setRendererType() 方法更改此值。

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.

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

英文文档：

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

public UIInput()

使用默认属性值创建新的 UIInput 实例。

英文文档：

UIInput

public UIInput()

Create a new UIInput instance with default property values.

public String getFamily()

英文文档：

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

public Object getSubmittedValue()

返回此 UIInput 组件的 submittedValue 值。此方法仅供此组件或其相应 Renderer 的 decode() 和 validate() 方法使用。

英文文档：

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

public void setSubmittedValue(Object submittedValue)

设置此 UIInput 组件的 submittedValue 值。此方法仅供此组件或其相应 Renderer 的 decode() 和 validate() 方法使用。

submittedValue

新提交的值

英文文档：

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

public void setValue(Object value)

英文文档：

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

public void resetValue()

将此组件的值重置为非初始化状态的便捷方法。此方法执行以下步骤：

调用 #setValue，同时传递 null。

调用 #setSubmittedValue，同时传递 null。

调用 #setLocalValueSet，同时传递 false。

调用 #setValid，同时传递 true。

从此调用返回时，如果该实例的 "value" 属性有与其关联的 ValueBinding，则调用 UIOutput#getValue 时对此绑定求值。否则，从 getValue() 返回 null。

英文文档：

resetValue

public void resetValue()

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

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

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

public boolean isLocalValueSet()
返回此组件的 "local value set" 状态。调用 setValue() 自动将此属性重置为 true。

英文文档：

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

public void setLocalValueSet(boolean localValueSet)
设置此组件的 "local value set" 状态。

英文文档：

setLocalValueSet

public void setLocalValueSet(boolean localValueSet)

Sets the "local value set" state for this component.

Specified by:

setLocalValueSet in interface EditableValueHolder

public boolean isRequired()

返回此组件的 "required field" 状态。

英文文档：

isRequired

public boolean isRequired()

Return the "required field" state for this component.

Specified by:

isRequired in interface EditableValueHolder

public String getRequiredMessage()

如果曾调用过此实例的 #setRequiredMessage，则返回该消息。否则，调用 #getValueExpression，同时传递键 "requiredMessage"，获取该表达式的结果并将其返回。任何在调用 getValue() 期间抛出的 ELException 都必须在 FacesException 中包装并重新抛出。

英文文档：

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.

public void setRequiredMessage(String message)

使用提供给此方法的字面值参数重写任何为 "requiredMessage" 设置的 ValueExpression。随后调用 #getRequiredMessage 将返回此值；

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.

public String getConverterMessage()

如果曾调用过此实例的 #setConverterMessage，则返回该消息。否则，调用 #getValueExpression，同时传递键 "converterMessage"，获取该表达式的结果并将其返回。任何在调用 getValue() 期间抛出的 ELException 都必须在 FacesException 中包装并重新抛出。

英文文档：

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.

public void setConverterMessage(String message)

使用提供给此方法的字面值参数重写任何为 "converterMessage" 设置的 ValueExpression。随后调用 #getConverterMessage 将返回此值；

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.

public String getValidatorMessage()

如果曾调用过此实例的 #setRequiredMessage，则返回该消息。否则，调用 #getValueExpression，同时传递键 "requiredMessage"，获取该表达式的结果并将其返回。任何在调用 getValue() 期间抛出的 ELException 都必须在 FacesException 中包装并重新抛出。

英文文档：

getValidatorMessage

public String getValidatorMessage()

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.

public void setValidatorMessage(String message)

使用提供给此方法的字面值参数重写任何为 "validatorMessage" 设置的 ValueExpression。随后调用 #getValidatorMessage 将返回此值；

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.

public boolean isValid()

英文文档：

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

public void setValid(boolean valid)

英文文档：

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

public void setRequired(boolean required)

设置此组件的 "required field" 状态。

required

新的 "required field" 状态

英文文档：

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

public boolean isImmediate()

英文文档：

isImmediate

public boolean isImmediate()

Description copied from interface: EditableValueHolder

Return the "immediate" state for this component.

Specified by:

isImmediate in interface EditableValueHolder

public void setImmediate(boolean immediate)

英文文档：

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

public MethodBinding getValidator()

返回指向将在请求处理生命周期的处理验证 阶段调用的方法的 MethodBinding，以验证此组件的当前值。

deprecated

应改用 #getValidators。

英文文档：

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

public void setValidator(MethodBinding validatorBinding)

设置指向将在请求处理生命周期的处理验证 阶段调用的方法的 MethodBinding，以验证此组件的当前值。

此表达式所引用的任何方法都必须是公共的，返回类型为 void，并接受类型为 FacesContext、UIComponent 和 Object 的参数。

validatorBinding	新的 MethodBinding 实例
deprecated	请改用 #addValidator，通过创建 javax.faces.validator.MethodExpressionValidator 的实例获取参数 Validator。

英文文档：

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

public MethodBinding getValueChangeListener()

英文文档：

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

public void setValueChangeListener(MethodBinding valueChangeListener)
NullPointerException

在 ValueChangeListener 的实现中包装参数 valueChangeMethod，并将其存储在支持 #getValueChangeListeners 方法的内部数据结构中，小心地重写通过以前调用 setValueChangeListener 存储的任何实例。

此参数方法将在处理验证 或应用请求值 阶段（取决于 immediate 属性的值）调用。

此表达式所引用的任何方法都必须是公共的，返回类型为 void，并接受类型为 javax.faces.event.ValueChangeEvent 的参数。

deprecated

请改用 #addValueChangeListener，通过创建 javax.faces.event.MethodExpressionValueChangeListener 的实例获取参数 ValueChangeListener。

英文文档：

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 new method binding instance

public void processDecodes(FacesContext context)

在超类提供的解码行为之上的专门解码行为。除继承自 UIComponentBase 的标准 processDecodes 行为外，如果 immediate 属性为 true，则还调用 validate()；之后，如果组件无效，或抛出 RuntimeException，则调用 FacesContext#renderResponse。

Throws

NullPointerException: NullPointerException NullPointerException 如果 context 为 null

英文文档：

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

public void processValidators(FacesContext context)

除继承自 UIComponentBase 的标准 processValidators 行为外，如果 immediate 属性为 false（默认值），则还调用 validate()；之后，如果组件无效，则调用 FacesContext#renderResponse。如果在验证处理期间抛出 RuntimeException，则调用 FacesContext#renderResponse 并重新抛出该异常。

Throws

NullPointerException: NullPointerException NullPointerException 如果 context 为 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

public void processUpdates(FacesContext context)

除继承自 UIComponentBase 的标准 processUpdates 行为外，还调用 updateModel()。之后，如果组件无效，则调用 FacesContext#renderResponse。如果在更新处理期间抛出 RuntimeException，则调用 FacesContext#renderResponse 并重新抛出该异常。

Throws

NullPointerException: NullPointerException NullPointerException 如果 context 为 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

public void decode(FacesContext context)

Throws

NullPointerException: NullPointerException NullPointerException 如果 context 为 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

public void updateModel(FacesContext context)

根据需要，执行下面的算法来更新与此 UIInput 关联的模型数据（如果有）。

• 如果此组件的 valid 属性为 false，则不采取进一步操作。
• 如果此组件的 localValueSet 属性为 false，则不采取进一步操作。
• 如果不存在 value 的 ValueExpression，则不采取进一步操作。
• 调用 ValueExpression 的 setValue() 方法以更新 ValueExpression 指向的值。
• 如果 setValue() 方法成功返回：
  • 清除此 UIInput 的本地值。
  • 将此 UIInput 的 localValueSet 属性设置为 false。
• 如果 setValue() 方法调用失败：
  • 通过调用指定 FacesContext 实例的 addMessage()，将错误消息加入队列。
  • 将此 UIInput 的 valid 属性设置为 false。

context	要处理的请求的 FacesContext
Throws	NullPointerException: 如果 context 为 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 call fails:
  • Enqueue an error message by calling addMessage() on the specified FacesContext instance.
  • Set the valid property of this UIInput to false.

Parameters:

context - FacesContext for the request we are processing

Throws:

NullPointerException - if context is null

public void validate(FacesContext context)

执行下面的算法来验证此 UIInput 的本地值。

• 通过 getSubmittedValue() 获取提交的值。如果此方法返回 null，则退出而不做进一步处理。（这指示没有为此组件提交任何值。）
• 通过调用 #getConvertedValue 将提交的值转换为相应数据类型的 "local value"。
• 通过调用 #validateValue 验证该属性。
• 如果此组件的 valid 属性仍为 true，则获取该组件以前的值（使用 getValue())，使用 setValue() 存储新本地值，并将提交的值重置为 null。如果本地值与此组件以前的值不同，则触发 ValueChangeEvent 以广播到所有感兴趣的侦听器。

要使用组件中嵌入的逻辑执行验证的实现 UIInput 的应用程序组件应执行其自己的正确性检查，然后调用 super.validate() 方法执行上述标准处理。

context	当前请求的 FacesContext
Throws	NullPointerException: 如果 context 为 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, exit without further processing. (This indicates that no value was submitted for this component.)
• Convert the submitted value into a "local value" of the appropriate data type by calling getConvertedValue(javax.faces.context.FacesContext, java.lang.Object).
• 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. If the local value is different from the previous value of this component, 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

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

如有必要，将提交的值转换为相应数据类型的 "local value"。可以使用下面的算法做到这一点：

• 如果存在 Renderer，则调用 getConvertedValue() 转换提交的值。
• 如果不存在 Renderer，且提交的值为 String，则定位到 Converter，如下所示：
  • 如果 getConverter() 返回非 null Converter，请使用该实例。
  • 否则，如果存在 value 的值绑定，则调用其上的 getType()。
    • 如果此调用返回 null，则假定输出类型是 String 且不执行转换。
    • 否则，调用 Application.createConverter(Class) 定位到可转换指定类型的数据值的任何已注册 Converter。
• 如果已定位到 Converter 实例，则调用其 getAsObject() 方法来执行转换。如果转换失败：
  • 通过调用 FacesContext 上的 addMessage() 方法将相应的错误消息加入队列。
  • 将此组件的 valid 属性设置为 false。
• 否则，使用提交的值，而不进行任何转换。

子类可以重写此方法得到更具体的行为。

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:
  • Enqueue an appropriate error message by calling the addMessage() method on the FacesContext.
  • Set the valid property on this component to false
• Otherwise, use the submitted value without any conversion

This method can be overridden by subclasses for more specific behavior.

protected void validateValue(FacesContext context, Object newValue)

根据下面的算法设置 "valid" 属性。

• 如果此组件的 valid 属性仍为 true，且 required 属性也为 true，则确保本地值不为空（其中，"empty" 定义为 null 或长度为 0 的 String）。如果本地值为空：
  • 通过调用当前请求的 FacesContext 实例上的 addMessage() 方法，将相应的错误消息加入队列。如果 #getRequiredMessage 返回非 null，则将该值用作在 FacesContext 中排队的 FacesMessage 中的 summary 和 detail，否则使用 #REQUIRED_MESSAGE_ID 的消息。
  • 将此组件的 valid 属性设置为 false。
• 如果此组件的 valid 属性仍为 true，且本地值不为空，则调用每个为此 UIInput 注册的 Validator 的 validate() 方法，接着调用 validatorBinding 属性指向的方法（如果有）。如果这些验证器中的任何一个或该方法抛出 ValidatorException，则捕获该异常，并将其消息（如果有）添加到 FacesContext，然后将此组件的 valid 属性设置为 false。

英文文档：

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 the valid property on this component is still true, and the local value is not empty, 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.

protected boolean compareValues(Object previous, Object value)

如果新值与以前的值不同，则返回 true。

previous	此组件以前的值（如果有）
value	此组件的新值（如果有）

英文文档：

compareValues

protected boolean compareValues(Object previous,
                                Object value)

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

Parameters:

previous - old value of this component (if any)

value - new value of this component (if any)

public void addValidator(Validator validator)

将 Validator 实例添加到与此 UIInput 关联的集合。

validator	要添加的 Validator
Throws	NullPointerException: 如果 validator 为 null

英文文档：

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

public Validator[] getValidators()

返回为此 UIInput 实例注册的 Validator 集合。如果不存在任何已注册验证器，则返回一个长度为 0 的数组。

英文文档：

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

public void removeValidator(Validator validator)

从与此 UIInput 关联的集合中移除 Validator 实例（如果以前将它们关联过）。其他情况下不执行任何操作。

validator

要移除的 Validator

英文文档：

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

public void addValueChangeListener(ValueChangeListener listener)

向希望在发生 ValueChangeEvent 时获得通知的侦听器集合中添加一个新的 ValueChangeListener。

listener	要添加的 ValueChangeListener
Throws	NullPointerException: 如果 listener 为 null

英文文档：

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

public ValueChangeListener[] getValueChangeListeners()

返回为此 UIInput 实例注册的 ValueChangeListener 集合。如果不存在任何已注册侦听器，则返回一个长度为 0 的数组。

英文文档：

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

public void removeValueChangeListener(ValueChangeListener listener)

从希望在发生 ValueChangeEvent 时获得通知的侦听器集合中移除一个现有的 ValueChangeListener（如果有）。

listener	要移除的 ValueChangeListener
Throws	NullPointerException: 如果 listener 为 null

英文文档：

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

public Object saveState(FacesContext context)

英文文档：

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

public void restoreState(FacesContext context,
                         Object state)