Class Hierarchy All Classes All Fields and Methods

 

Class javax.faces.component.UIInput

java.lang.Object
        javax.faces.component.UIComponent
                javax.faces.component.UIComponentBase
                        javax.faces.component.UIOutput
                                javax.faces.component.UIInput

public class UIInput
implements EditableValueHolder
extends UIOutput

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.

Field Index

Field	Description
COMPONENT_FAMILY	The standard component family for this component.
COMPONENT_TYPE	The standard component type for this component.
CONVERSION_MESSAGE_ID	The message identifier of the FacesMessage to be created if a conversion error occurs, and the ConverterException does not provide a message.
REQUIRED_MESSAGE_ID	The message identifier of the FacesMessage to be created if a required check fails.

Constructor Index

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

Method Index

Method	Description
void addValidator(Validator)	Add a Validator instance to the set associated with this UIInput.
void addValueChangeListener(ValueChangeListener)	Add a new ValueChangeListener to the set of listeners interested in being notified when ValueChangeEvents occur.
void broadcast(FacesEvent)	In addition to to the default broadcast processing, pass the ValueChangeEvent being broadcast to the method referenced by valueChangeListener (if any).
boolean compareValues(Object, Object)	Return true if the new value is different from the previous value.
void decode(FacesContext)
String getFamily()
Object getSubmittedValue()	Return the submittedValue value of this UIInput component.
MethodBinding getValidator()	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.
Validator[] getValidators()	Return the set of registered Validators for this UIInput instance.
MethodBinding getValueChangeListener()	Return a MethodBinding instance method that will be called during Process Validations phase of he request processing lifecycle, after any registered ValueChangeListeners have been notified of a value change.
ValueChangeListener[] getValueChangeListeners()	Return the set of registered ValueChangeListeners for this UIInput instance.
boolean isImmediate()
boolean isLocalValueSet()	Return the "local value set" state for this component.
boolean isRequired()	Return the "required field" state for this component.
boolean isValid()
void processDecodes(FacesContext)	Specialized decode behavior on top of that provided by the superclass.
void processUpdates(FacesContext)	In addition to the standard processUpdates behavior inherited from UIComponentBase, calls updateModel().
void processValidators(FacesContext)	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 renderResponse.
void removeValidator(Validator)	Remove a Validator instance from the set associated with this UIInput, if it was previously associated.
void removeValueChangeListener(ValueChangeListener)	Remove an existing ValueChangeListener (if any) from the set of listeners interested in being notified when ValueChangeEvents occur.
void restoreState(FacesContext, Object)
Object saveState(FacesContext)
void setImmediate(boolean)
void setLocalValueSet(boolean)	Sets the "local value set" state for this component.
void setRequired(boolean)	Set the "required field" state for this component.
void setSubmittedValue(Object)	Set the submittedValue value of this UIInput component.
void setValid(boolean)
void setValidator(MethodBinding)	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.
void setValue(Object)
void setValueChangeListener(MethodBinding)	Set a MethodBinding instance a that will be called during Process Validations phase of he request processing lifecycle, after any registered ValueChangeListeners have been notified of a value change.
void updateModel(FacesContext)	Perform the following algorithm to update the model data associated with this UIInput, if any, as appropriate.
void validate(FacesContext)	Perform the following algorithm to validate the local value of this UIInput.

 

Fields

 

COMPONENT_FAMILY

public static final java.lang.String COMPONENT_FAMILY

The standard component family for this component.

 

COMPONENT_TYPE

public static final java.lang.String COMPONENT_TYPE

The standard component type for this component.

 

CONVERSION_MESSAGE_ID

public static final java.lang.String CONVERSION_MESSAGE_ID

The message identifier of the FacesMessage to be created if a conversion error occurs, and the ConverterException does not provide a message.

 

REQUIRED_MESSAGE_ID

public static final java.lang.String REQUIRED_MESSAGE_ID

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

 

Constructors

 

UIInput

public UIInput() 

Create a new UIInput instance with default property values.

 

Methods

 

addValidator

public void addValidator(Validator validator) 

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

• Parameters

  • validator - The Validator to add

• Throws

  • NullPointerException if validator is null

 

addValueChangeListener

public void addValueChangeListener(ValueChangeListener listener) 

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

• Parameters

  • listener - The ValueChangeListener to be added

• Throws

  • NullPointerException if listener is null

 

broadcast

public void broadcast(FacesEvent event) throws AbortProcessingException

In addition to to the default broadcast processing, pass the ValueChangeEvent being broadcast to the method referenced by valueChangeListener (if any).

• Parameters

  • event - FacesEvent to be broadcast

• Throws

  • AbortProcessingException Signal the JavaServer Faces implementation that no further processing on the current event should be performed

• Throws

  • IllegalArgumentException if the implementation class of this FacesEvent is not supported by this component

• Throws

  • NullPointerException if event is null

• Overrides

  • broadcast in class UIComponentBase

 

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)

 

decode

public void decode(FacesContext context) 

• Throws

  • NullPointerException {@inheritDoc}

• Overrides

  • decode in class UIComponentBase

 

getFamily

public String getFamily() 

 

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.

 

getValidator

public MethodBinding getValidator() 

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.

 

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.

 

getValueChangeListener

public MethodBinding getValueChangeListener() 

Return a MethodBinding instance method that will be called during Process Validations phase of he request processing lifecycle, after any registered ValueChangeListeners have been notified of a value change.

 

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.

 

isImmediate

public boolean isImmediate() 

 

isLocalValueSet

public boolean isLocalValueSet() 

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

 

isRequired

public boolean isRequired() 

Return the "required field" state for this component.

 

isValid

public boolean isValid() 

 

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 renderResponse.

• Throws

  • NullPointerException {@inheritDoc}

• Overrides

  • processDecodes in class UIComponentBase

 

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 renderResponse. If a RuntimeException is thrown during update processing, calls renderResponse and re-throw the exception.

• Throws

  • NullPointerException {@inheritDoc}

• Overrides

  • processUpdates in class UIComponentBase

 

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 renderResponse. If a RuntimeException is thrown during validation processing, calls renderResponse and re-throw the exception.

• Throws

  • NullPointerException {@inheritDoc}

• Overrides

  • processValidators in class UIComponentBase

 

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.

• Parameters

  • validator - The Validator to remove

 

removeValueChangeListener

public void removeValueChangeListener(ValueChangeListener listener) 

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

• Parameters

  • listener - The ValueChangeListener to be removed

• Throws

  • NullPointerException if listener is null

 

restoreState

public void restoreState(FacesContext context,
                         Object state) 

 

saveState

public Object saveState(FacesContext context) 

 

setImmediate

public void setImmediate(boolean immediate) 

 

setLocalValueSet

public void setLocalValueSet(boolean localValueSet) 

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

 

setRequired

public void setRequired(boolean required) 

Set the "required field" state for this component.

• Parameters

  • required - The new "required field" state

 

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.

• Parameters

  • submittedValue - The new submitted value

 

setValid

public void setValid(boolean valid) 

 

setValidator

public void setValidator(MethodBinding validatorBinding) 

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.

• Parameters

  • validatorBinding - The new MethodBinding instance

 

setValue

public void setValue(Object value) 

 

setValueChangeListener

public void setValueChangeListener(MethodBinding valueChangeMethod) 

Set a MethodBinding instance a that will be called during Process Validations phase of he request processing lifecycle, after any registered ValueChangeListeners have been notified of a value change.

• Parameters

  • valueChangeMethod - The new method binding instance

 

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 ValueBinding for value exists, take no further action.
• Call setValue() method of the ValueBinding to update the value that the ValueBinding 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

 

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, if necessary, according to the following rules:
  • 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

• 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.
  • 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.
• 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

Class Hierarchy All Classes All Fields and Methods