public class UIInput extends UIOutput implements EditableValueHolder
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 and Description |
---|
UIInput() |
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) |
getConverter, getLocalValue, getValue, setConverter
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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getConverter, getLocalValue, getValue, setConverter
public static final String CONVERSION_MESSAGE_ID
public static final String REQUIRED_MESSAGE_ID
public static final String COMPONENT_TYPE
public static final String COMPONENT_FAMILY
public Object getSubmittedValue()
EditableValueHolder
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.
getSubmittedValue
in interface EditableValueHolder
public void setSubmittedValue(Object submittedValue)
EditableValueHolder
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.
setSubmittedValue
in interface EditableValueHolder
public void setValue(Object value)
setValue
in interface ValueHolder
setValue
in class UIOutput
public boolean isLocalValueSet()
EditableValueHolder
isLocalValueSet
in interface EditableValueHolder
public void setLocalValueSet(boolean localValueSet)
EditableValueHolder
setLocalValueSet
in interface EditableValueHolder
public boolean isValid()
EditableValueHolder
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.
isValid
in interface EditableValueHolder
public void setValid(boolean valid)
setValid
in interface EditableValueHolder
public MethodBinding getValidator()
EditableValueHolder
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.
getValidator
in interface EditableValueHolder
public void setValidator(MethodBinding validator)
setValidator
in interface EditableValueHolder
public MethodBinding getValueChangeListener()
EditableValueHolder
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.
getValueChangeListener
in interface EditableValueHolder
public void setValueChangeListener(MethodBinding valueChangeListener)
setValueChangeListener
in interface EditableValueHolder
public void processDecodes(FacesContext context)
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.
processDecodes
in class UIComponentBase
public void processValidators(FacesContext context)
processValidators
in class UIComponentBase
public void processUpdates(FacesContext context)
UIComponentBase
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.
processUpdates
in class UIComponentBase
public void decode(FacesContext context)
UIComponentBase
decode
in class UIComponentBase
public void broadcast(FacesEvent event) throws AbortProcessingException
UIComponentBase
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.
broadcast
in class UIComponentBase
event
- must not be null.AbortProcessingException
public void updateModel(FacesContext context)
protected void validateValue(FacesContext context, Object convertedValue)
public void validate(FacesContext context)
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:
protected Object getConvertedValue(FacesContext context, Object submittedValue)
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:
public void addValidator(Validator validator)
addValidator
in interface EditableValueHolder
public Validator[] getValidators()
getValidators
in interface EditableValueHolder
public void removeValidator(Validator validator)
removeValidator
in interface EditableValueHolder
public void addValueChangeListener(ValueChangeListener listener)
addValueChangeListener
in interface EditableValueHolder
public ValueChangeListener[] getValueChangeListeners()
getValueChangeListeners
in interface EditableValueHolder
public void removeValueChangeListener(ValueChangeListener listener)
removeValueChangeListener
in interface EditableValueHolder
public Object saveState(FacesContext context)
UIComponentBase
saveState
in interface StateHolder
saveState
in class UIOutput
public void restoreState(FacesContext context, Object state)
UIComponentBase
restoreState
in interface StateHolder
restoreState
in class UIOutput
state
- is an object previously returned by
the saveState method of this class.public void setImmediate(boolean immediate)
setImmediate
in interface EditableValueHolder
public boolean isImmediate()
EditableValueHolder
isImmediate
in interface EditableValueHolder
public void setRequired(boolean required)
EditableValueHolder
setRequired
in interface EditableValueHolder
public boolean isRequired()
EditableValueHolder
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.
isRequired
in interface EditableValueHolder
Copyright © 2012 Apache Software Foundation. All Rights Reserved.