UIInput (Java EE 5 SDK)

Java

Java EE 5 SDK

深圳电信培训中心.徐海蛟老师.


javax.faces.component Class UIInput

java.lang.Object
  extended by javax.faces.component.UIComponent
      extended by javax.faces.component.UIComponentBase
          extended by javax.faces.component.UIOutput
              extended by javax.faces.component.UIInput
所有已实现的接口:
EditableValueHolder, StateHolder, ValueHolder
直接已知子类:
HtmlInputHidden, HtmlInputSecret, HtmlInputText, HtmlInputTextarea, UISelectBoolean, UISelectMany, UISelectOne

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.

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


字段摘要
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 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.
 
Fields inherited from class javax.faces.component.UIComponent
bindings
 
构造器摘要
UIInput()
          Create a new UIInput instance with default property values.
 
方法摘要
 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 ValueChangeEvents occur.
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 setRequiredMessage(java.lang.String) on this instance, return the message.
 Validator[] getValidators()
          Return the set of registered Validators for this UIInput instance.
 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 ValueChangeListeners for this UIInput instance.
 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 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 ValueChangeEvents 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.
 
类方法继承 javax.faces.component.UIOutput
getConverter, getLocalValue, getValue, setConverter
 
类方法继承 javax.faces.component.UIComponentBase
addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding
 
类方法继承 javax.faces.component.UIComponent
encodeAll, getContainerClientId, getValueExpression, setValueExpression
 
类方法继承 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.faces.component.ValueHolder
getConverter, getLocalValue, getValue, setConverter
 

字段详细信息

COMPONENT_TYPE

public static final String COMPONENT_TYPE

The standard component type for this component.

另请参见:
常量字段


COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

The standard component family for this component.

另请参见:
常量字段


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.

另请参见:
常量字段


REQUIRED_MESSAGE_ID

public static final String REQUIRED_MESSAGE_ID

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

另请参见:
常量字段


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.

另请参见:
常量字段

构造器详细信息

UIInput

public UIInput()

Create a new UIInput instance with default property values.

方法详细信息

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.

重写:
getFamily in class UIOutput

getSubmittedValue

public Object getSubmittedValue()

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

规范说明:
getSubmittedValue in interface EditableValueHolder

setSubmittedValue

public void setSubmittedValue(Object submittedValue)

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

规范说明:
setSubmittedValue in interface EditableValueHolder
参数:
submittedValue - The new submitted value

setValue

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

Set the value of this UIComponent (if any).

规范说明:
setValue in interface ValueHolder
重写:
setValue in class UIOutput
参数:
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 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().


isLocalValueSet

public boolean isLocalValueSet()
Return the "local value set" state for this component. Calls to setValue() automatically reset this property to true.

规范说明:
isLocalValueSet in interface EditableValueHolder

setLocalValueSet

public void setLocalValueSet(boolean localValueSet)
Sets the "local value set" state for this component.

规范说明:
setLocalValueSet in interface EditableValueHolder

isRequired

public boolean isRequired()

Return the "required field" state for this component.

规范说明:
isRequired in interface EditableValueHolder

getRequiredMessage

public String getRequiredMessage()

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


setRequiredMessage

public void setRequiredMessage(String message)

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

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

getConverterMessage

public String getConverterMessage()

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


setConverterMessage

public void setConverterMessage(String message)

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

参数:
message - the literal message value to be displayed in the event conversion fails.

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.


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;

参数:
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).

规范说明:
isValid in interface EditableValueHolder

setValid

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

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

规范说明:
setValid in interface EditableValueHolder
参数:
valid - The new valid flag

setRequired

public void setRequired(boolean required)

Set the "required field" state for this component.

规范说明:
setRequired in interface EditableValueHolder
参数:
required - The new "required field" state

isImmediate

public boolean isImmediate()
Description copied from interface: EditableValueHolder

Return the "immediate" state for this component.

规范说明:
isImmediate in interface EditableValueHolder

setImmediate

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

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

规范说明:
setImmediate in interface EditableValueHolder
参数:
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.

规范说明:
getValidator in interface EditableValueHolder

setValidator

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

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

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

规范说明:
setValidator in interface EditableValueHolder
参数:
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).

规范说明:
getValueChangeListener in interface EditableValueHolder

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.

规范说明:
setValueChangeListener in interface EditableValueHolder
参数:
valueChangeListener - The new method binding instance

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

重写:
processDecodes in class UIComponentBase
参数:
context - FacesContext for the request we are processing
抛出异常:
NullPointerException - if context is null

processValidators

public void processValidators(FacesContext context)

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

重写:
processValidators in class UIComponentBase
参数:
context - FacesContext for the request we are processing
抛出异常:
NullPointerException - if context is null

processUpdates

public void processUpdates(FacesContext context)

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

重写:
processUpdates in class UIComponentBase
参数:
context - FacesContext for the request we are processing
抛出异常:
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().

重写:
decode in class UIComponentBase
参数:
context - FacesContext for the request we are processing
抛出异常:
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 call fails:
    • Enqueue an error message by calling addMessage() on the specified FacesContext instance.
    • Set the valid property of this UIInput to false.

参数:
context - FacesContext for the request we are processing
抛出异常:
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, 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.

参数:
context - The FacesContext for the current request
抛出异常:
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:
    • 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.

抛出异常:
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 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.


compareValues

protected boolean compareValues(Object previous,
                                Object value)

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

参数:
previous - old value of this component (if any)
value - new value of this component (if any)

addValidator

public void addValidator(Validator validator)

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

规范说明:
addValidator in interface EditableValueHolder
参数:
validator - The Validator to add
抛出异常:
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.

规范说明:
getValidators in interface EditableValueHolder

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.

规范说明:
removeValidator in interface EditableValueHolder
参数:
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.

规范说明:
addValueChangeListener in interface EditableValueHolder
参数:
listener - The ValueChangeListener to be added
抛出异常:
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.

规范说明:
getValueChangeListeners in interface EditableValueHolder

removeValueChangeListener

public void removeValueChangeListener(ValueChangeListener listener)

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

规范说明:
removeValueChangeListener in interface EditableValueHolder
参数:
listener - The ValueChangeListener to be removed
抛出异常:
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

规范说明:
saveState in interface StateHolder
重写:
saveState in class UIOutput

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.

规范说明:
restoreState in interface StateHolder
重写:
restoreState in class UIOutput

Java EE 5 SDK

深圳电信培训中心.徐海蛟老师.


提交错误或意见

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。深圳电信培训中心.徐海蛟老师教学参考.