javax.faces.component

Class UIInput

java.lang.Object

javax.faces.component.UIComponent

javax.faces.component.UIComponentBase

javax.faces.component.UIOutput

javax.faces.component.UIInput

All Implemented Interfaces:

EditableValueHolder, StateHolder, ValueHolder

Direct Known Subclasses:

HtmlInputHidden, HtmlInputSecret, HtmlInputText, HtmlInputTextarea, UISelectBoolean, UISelectMany, UISelectOne

public class UIInput
extends UIOutput
implements EditableValueHolder

see Javadoc of JSF Specification

Version:

$Revision: 499699 $ $Date: 2007-01-25 09:41:01 +0100 (Do, 25 Jan 2007) $

Author:

Manfred Geiler (latest modification by $Author: matzew $)

Field Summary

Fields

Modifier and Type	Field and Description
static String	COMPONENT_FAMILY
static String	COMPONENT_TYPE
static String	CONVERSION_MESSAGE_ID
static String	REQUIRED_MESSAGE_ID

Constructor Summary

Constructors

Constructor and Description
UIInput()

Method Summary

Methods

Modifier and Type	Method and Description
void	addValidator(Validator validator)
void	addValueChangeListener(ValueChangeListener listener)
void	broadcast(FacesEvent event) Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.
protected boolean	compareValues(Object previous, Object value)
void	decode(FacesContext context) Check the submitted form parameters for data associated with this component.
protected Object	getConvertedValue(FacesContext context, Object submittedValue) Convert the provided object to the desired value.
String	getFamily()
Object	getSubmittedValue() Get an object representing the most recent raw user input received for this component.
MethodBinding	getValidator() Get the single validator defined directly on this component.
Validator[]	getValidators()
MethodBinding	getValueChangeListener() Get the single value-change defined directly on this component.
ValueChangeListener[]	getValueChangeListeners()
boolean	isImmediate() When true, the validation step for this component will also invoke any associated actionListeners.
boolean	isLocalValueSet() Determine whether the value member variable of this component has been set from the converted and validated "submitted value".
boolean	isRequired() Return true if this component must have a non-empty submitted value.
boolean	isValid() This returns false if validation has been run for this component and has failed.
void	processDecodes(FacesContext context) Set the "submitted value" of this component from the relevant data in the current servlet request object.
void	processUpdates(FacesContext context) This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.
void	processValidators(FacesContext context)
void	removeValidator(Validator validator)
void	removeValueChangeListener(ValueChangeListener listener)
void	restoreState(FacesContext context, Object state) Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.
Object	saveState(FacesContext context) Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.
void	setImmediate(boolean immediate)
void	setLocalValueSet(boolean localValueSet) Specify the return value of method isLocalValueSet.
void	setRequired(boolean required) Set to true to cause validation failure when a form containing this component is submitted and there is no value selected for this component.
void	setSubmittedValue(Object submittedValue) Invoked during the "decode" phase of processing to inform this component what data was received from the user.
void	setValid(boolean valid)
void	setValidator(MethodBinding validator)
void	setValue(Object value) Store the specified object as the "local value" of this component.
void	setValueChangeListener(MethodBinding valueChangeListener)
void	updateModel(FacesContext context)
void	validate(FacesContext context) Determine whether the new value is valid, and queue a ValueChangeEvent if necessary.
protected void	validateValue(FacesContext context, Object convertedValue)

Methods inherited from class javax.faces.component.UIOutput

getConverter, getLocalValue, getValue, setConverter

Methods inherited from class javax.faces.component.UIComponentBase

addFacesListener, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientId, getFacesContext, getFacesListeners, getFacet, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding

Methods inherited from class 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

Field Detail

CONVERSION_MESSAGE_ID

public static final String CONVERSION_MESSAGE_ID

See Also:

Constant Field Values

REQUIRED_MESSAGE_ID

public static final String REQUIRED_MESSAGE_ID

See Also:

Constant Field Values

COMPONENT_TYPE

public static final String COMPONENT_TYPE

See Also:

Constant Field Values

COMPONENT_FAMILY

public static final String COMPONENT_FAMILY

See Also:

Constant Field Values

Constructor Detail

UIInput

public UIInput()

Method Detail

getSubmittedValue

public Object getSubmittedValue()

Description copied from interface: EditableValueHolder

Get an object representing the most recent raw user input received for this component.

This is non-null only between decode and validate phases, or when validation for the component has not succeeded. Once conversion and validation has succeeded, the (converted) value is stored in the local "value" property of this component, and the submitted value is reset to null.

Specified by:

getSubmittedValue in interface EditableValueHolder

setSubmittedValue

public void setSubmittedValue(Object submittedValue)

Description copied from interface: EditableValueHolder

Invoked during the "decode" phase of processing to inform this component what data was received from the user.

In many cases the submitted value is a plain string extracted from the current servlet request object.

In cases where a component is rendered as multiple input components (eg a calendar control with separate day/month/year fields), the submittedValue may be some custom object wrapping the data. However the provided object must be able to represent all possible user input values, not just valid ones.

Specified by:

setSubmittedValue in interface EditableValueHolder

setValue

public void setValue(Object value)

Store the specified object as the "local value" of this component. The value-binding named "value" (if any) is ignored; the object is only stored locally on this component. During the "update model" phase, if there is a value-binding named "value" then this local value will be stored via that value-binding and the "local value" reset to null.

Specified by:

setValue in interface ValueHolder

Overrides:

setValue in class UIOutput

isLocalValueSet

public boolean isLocalValueSet()

Description copied from interface: EditableValueHolder

Determine whether the value member variable of this component has been set from the converted and validated "submitted value". This property is needed because EditableValueHolder components need to distinguish between the value local member and the value property (which may involve a value-binding to the user model).

Specified by:

isLocalValueSet in interface EditableValueHolder

setLocalValueSet

public void setLocalValueSet(boolean localValueSet)

Description copied from interface: EditableValueHolder

Specify the return value of method isLocalValueSet. This is called after the local value member has been set from the converted and validated "submitted value". It is cleared after that value has been pushed to the user model via the value-binding named "value".

Specified by:

setLocalValueSet in interface EditableValueHolder

isValid

public boolean isValid()

Description copied from interface: EditableValueHolder

This returns false if validation has been run for this component and has failed.

It is also set to false if the validated value could not be passed to the model during the update model phase.

All input components are marked as valid during the "restore view" phase, so this will return true for components whose validation has not been executed.

Specified by:

isValid in interface EditableValueHolder

setValid

public void setValid(boolean valid)

Specified by:

setValid in interface EditableValueHolder

getValidator

public MethodBinding getValidator()

Description copied from interface: EditableValueHolder

Get the single validator defined directly on this component.

In addition to this validator, there may be a list of validators associated with this component.

This validator is executed after all validators in the validator list.

Specified by:

getValidator in interface EditableValueHolder

setValidator

public void setValidator(MethodBinding validator)

Specified by:

setValidator in interface EditableValueHolder

getValueChangeListener

public MethodBinding getValueChangeListener()

Description copied from interface: EditableValueHolder

Get the single value-change defined directly on this component.

In addition to this listener, there may be a list of listeners associated with this component.

This listeners is executed after all listeners in the list.

Specified by:

getValueChangeListener in interface EditableValueHolder

setValueChangeListener

public void setValueChangeListener(MethodBinding valueChangeListener)

Specified by:

setValueChangeListener in interface EditableValueHolder

processDecodes

public void processDecodes(FacesContext context)

Set the "submitted value" of this component from the relevant data in the current servlet request object.

If this component is not rendered, then do nothing; no output would have been sent to the client so no input is expected.

Invoke the inherited functionality, which typically invokes the renderer associated with this component to extract and set this component's "submitted value".

If this component is marked "immediate", then immediately apply validation to the submitted value found. On error, call context method "renderResponse" which will force processing to leap to the "render response" phase as soon as the "decode" step has completed for all other components.

Overrides:

processDecodes in class UIComponentBase

processValidators

public void processValidators(FacesContext context)

Overrides:

processValidators in class UIComponentBase

processUpdates

public void processUpdates(FacesContext context)

Description copied from class: UIComponentBase

This isn't an input component, so just pass on the processUpdates call to child components and facets that might be input components.

Components that were never rendered can't possibly be receiving update data (no corresponding fields were ever put into the response) so if this component is not rendered then this method does not invoke processUpdates on its children.

Overrides:

processUpdates in class UIComponentBase

decode

public void decode(FacesContext context)

Description copied from class: UIComponentBase

Check the submitted form parameters for data associated with this component. This default implementation delegates to this component's renderer if there is one, and otherwise ignores the call.

Overrides:

decode in class UIComponentBase

broadcast

public void broadcast(FacesEvent event)
               throws AbortProcessingException

Description copied from class: UIComponentBase

Invoke any listeners attached to this object which are listening for an event whose type matches the specified event's runtime type.

This method does not propagate the event up to parent components, ie listeners attached to parent components don't automatically get called.

If any of the listeners throws AbortProcessingException then that exception will prevent any further listener callbacks from occurring, and the exception propagates out of this method without alteration.

ActionEvent events are typically queued by the renderer associated with this component in its decode method; ValueChangeEvent events by the component's validate method. In either case the event's source property references a component. At some later time the UIViewRoot component iterates over its queued events and invokes the broadcast method on each event's source object.

Overrides:

broadcast in class UIComponentBase

Parameters:

event - must not be null.

Throws:

AbortProcessingException

updateModel

public void updateModel(FacesContext context)

validateValue

protected void validateValue(FacesContext context,
                 Object convertedValue)

validate

public void validate(FacesContext context)

Determine whether the new value is valid, and queue a ValueChangeEvent if necessary.

The "submitted value" is converted to the necessary type; conversion failure is reported as an error and validation processing terminates for this component. See documentation for method getConvertedValue for details on the conversion process.

Any validators attached to this component are then run, passing the converted value.

The old value of this component is then fetched (possibly involving the evaluation of a value-binding expression, ie invoking a method on a user object). The old value is compared to the new validated value, and if they are different then a ValueChangeEvent is queued for later processing.

On successful completion of this method:

• isValid() is true
• isLocalValueSet() is true
• submittedValue is reset to null
• a ValueChangeEvent is queued if the new value != old value

getConvertedValue

protected Object getConvertedValue(FacesContext context,
                       Object submittedValue)

Convert the provided object to the desired value.

If there is a renderer for this component, then call the renderer's getConvertedValue method. While this can of course be implemented in any way the renderer desires, it typically performs exactly the same processing that this method would have done anyway (ie that described below for the no-renderer case).

Otherwise:

• If the submittedValue is not a String then just return the submittedValue unconverted.
• If there is no "value" value-binding then just return the submittedValue unconverted.
• Use introspection to determine the type of the target property specified by the value-binding, and then use Application.createConverter to find a converter that can map from String to the required type. Apply the converter to the submittedValue and return the result.

compareValues

protected boolean compareValues(Object previous,
                    Object value)

addValidator

public void addValidator(Validator validator)

Specified by:

addValidator in interface EditableValueHolder

getValidators

public Validator[] getValidators()

Specified by:

getValidators in interface EditableValueHolder

removeValidator

public void removeValidator(Validator validator)

Specified by:

removeValidator in interface EditableValueHolder

addValueChangeListener

public void addValueChangeListener(ValueChangeListener listener)

Specified by:

addValueChangeListener in interface EditableValueHolder

getValueChangeListeners

public ValueChangeListener[] getValueChangeListeners()

Specified by:

getValueChangeListeners in interface EditableValueHolder

removeValueChangeListener

public void removeValueChangeListener(ValueChangeListener listener)

Specified by:

removeValueChangeListener in interface EditableValueHolder

saveState

public Object saveState(FacesContext context)

Description copied from class: UIComponentBase

Invoked after the render phase has completed, this method returns an object which can be passed to the restoreState of some other instance of UIComponentBase to reset that object's state to the same values as this object currently has.

Specified by:

saveState in interface StateHolder

Overrides:

saveState in class UIOutput

restoreState

public void restoreState(FacesContext context,
                Object state)

Description copied from class: UIComponentBase

Invoked in the "restore view" phase, this initialises this object's members from the values saved previously into the provided state object.

Specified by:

restoreState in interface StateHolder

Overrides:

restoreState in class UIOutput

state - is an object previously returned by the saveState method of this class.

getFamily

public String getFamily()

Overrides:

getFamily in class UIOutput

setImmediate

public void setImmediate(boolean immediate)

Specified by:

setImmediate in interface EditableValueHolder

isImmediate

public boolean isImmediate()

Description copied from interface: EditableValueHolder

When true, the validation step for this component will also invoke any associated actionListeners. Typically such listeners will call renderResponse, causing the rendering phase to begin immediately (including possible navigation) without performing validation on any following components.

Specified by:

isImmediate in interface EditableValueHolder

setRequired

public void setRequired(boolean required)

Description copied from interface: EditableValueHolder

Set to true to cause validation failure when a form containing this component is submitted and there is no value selected for this component.

Specified by:

setRequired in interface EditableValueHolder

isRequired

public boolean isRequired()

Description copied from interface: EditableValueHolder

Return true if this component must have a non-empty submitted value.

Note that even when a component is "required", it is not an error for some form to be submitted which does not contain the component. It is only an error when the form submitted does contain the component, but there is no data for the component in that request. A "submitted value" of null is set during the "decode" step to represent the case where the request map has no entry corresponding to this component's id. When the decode step finds an entry in the request, but the corresponding value represents "no data" (eg an empty string for a text input field) then some special non-null value must be set for the "submitted value"; validation for "required" fields must then check for that.

Specified by:

isRequired in interface EditableValueHolder