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
All Implemented Interfaces:
EventListener, EditableValueHolder, PartialStateHolder, StateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder
Direct Known Subclasses:
HtmlInputHidden, UISelectBoolean, UISelectMany, UISelectOne, UIViewParameter

@JSFComponent(defaultRendererType="javax.faces.Text")
public class UIInput
extends UIOutput
implements EditableValueHolder

UICommand is a base abstraction for components that implement ActionSource.

See the javadoc for this class in the JSF Specification for further details.


Field Summary
static String COMPONENT_FAMILY
           
static String COMPONENT_TYPE
           
static String CONVERSION_MESSAGE_ID
           
static String REQUIRED_MESSAGE_ID
           
static String UPDATE_MESSAGE_ID
           
static String VALIDATE_EMPTY_FIELDS_PARAM_NAME
          Force validation on empty fields (By default is auto, which means it is only enabled when Bean Validation binaries are available on the current classpath).
 
Fields inherited from class javax.faces.component.UIComponent
BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, VIEW_LOCATION_KEY
 
Constructor Summary
UIInput()
          Construct an instance of the UIInput.
 
Method Summary
 void addValidator(Validator validator)
          See getValidator.
 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.
 void clearInitialState()
          
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 getConverterMessage()
          Text to be displayed to the user as an error message when conversion of a submitted value to the target type fails.
 String getFamily()
           
 String getRequiredMessage()
          Text to be displayed to the user as an error message when this component is marked as "required" but no input data is present during a postback (ie the user left the required field blank).
 Object getSubmittedValue()
          Gets the current submitted value.
 MethodBinding getValidator()
          Deprecated.  
 String getValidatorMessage()
          Text which will be shown if validation fails.
 Validator[] getValidators()
          See getValidator.
 Object getValue()
          Return the current value of this component.
 MethodBinding getValueChangeListener()
          Deprecated.  
 ValueChangeListener[] getValueChangeListeners()
          The valueChange event is delivered when the value attribute is changed.
static boolean isEmpty(Object value)
          Check if a value is empty or not.
 boolean isImmediate()
          A boolean value that identifies the phase during which action events should fire.
 boolean isLocalValueSet()
          Specifies whether a local value is currently set.
 boolean isRequired()
          A boolean value that indicates whether an input value is required.
 boolean isValid()
          Specifies whether the component's value is currently valid, ie whether the validators attached to this component have allowed it.
 void markInitialState()
           
 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)
          See getValidator.
 void removeValueChangeListener(ValueChangeListener listener)
           
 void resetValue()
          Convenience method to reset this component's value to an uninitialized state, by resetting the local value and submitted values to null (ensuring that EditableValueHolder.isLocalValueSet() is false), and setting "valid" to true.
 void restoreState(FacesContext facesContext, 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 facesContext)
          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 setConverterMessage(String converterMessage)
           
 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 setRequiredMessage(String requiredMessage)
           
 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)
          Deprecated.  
 void setValidatorMessage(String validatorMessage)
           
 void setValue(Object value)
          Store the specified object as the "local value" of this component.
 void setValueChangeListener(MethodBinding valueChangeListener)
          Deprecated.  
 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, setConverter
 
Methods inherited from class javax.faces.component.UIComponentBase
addClientBehavior, addFacesListener, encodeAll, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getParent, getRenderer, getRendererType, getRendersChildren, getValueBinding, initialStateMarked, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, visitTree
 
Methods inherited from class javax.faces.component.UIComponent
getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getListenersForEventClass, getNamingContainer, getResourceBundleMap, getStateHelper, getStateHelper, getValueExpression, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, setInView, setValueExpression, subscribeToEvent, unsubscribeFromEvent
 
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, setConverter
 

Field Detail

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

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

UPDATE_MESSAGE_ID

public static final String UPDATE_MESSAGE_ID
See Also:
Constant Field Values

VALIDATE_EMPTY_FIELDS_PARAM_NAME

@JSFWebConfigParam(defaultValue="auto",
                   expectedValues="auto, true, false",
                   since="2.0",
                   group="validation")
public static final String VALIDATE_EMPTY_FIELDS_PARAM_NAME
Force validation on empty fields (By default is auto, which means it is only enabled when Bean Validation binaries are available on the current classpath).

See Also:
Constant Field Values
Constructor Detail

UIInput

public UIInput()
Construct an instance of the UIInput.

Method Detail

getFamily

public String getFamily()
Overrides:
getFamily in class UIOutput

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

getValue

public Object getValue()
Return the current value of this component.

If a submitted value has been converted but not yet pushed into the model, then return that locally-cached value (see isLocalValueSet).

Otherwise, evaluate an EL expression to fetch a value from the model.

Specified by:
getValue in interface ValueHolder
Overrides:
getValue in class UIOutput
Returns:
the new value value

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:


getConvertedValue

protected Object getConvertedValue(FacesContext context,
                                   Object submittedValue)
                            throws ConverterException
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:

Throws:
ConverterException

compareValues

protected boolean compareValues(Object previous,
                                Object value)

resetValue

public void resetValue()
Description copied from interface: EditableValueHolder
Convenience method to reset this component's value to an uninitialized state, by resetting the local value and submitted values to null (ensuring that EditableValueHolder.isLocalValueSet() is false), and setting "valid" to true.

Specified by:
resetValue in interface EditableValueHolder
Since:
1.2

isImmediate

@JSFProperty
public boolean isImmediate()
A boolean value that identifies the phase during which action events should fire.

During normal event processing, action methods and action listener methods are fired during the "invoke application" phase of request processing. If this attribute is set to "true", these methods are fired instead at the end of the "apply request values" phase.

Specified by:
isImmediate in interface EditableValueHolder

setImmediate

public void setImmediate(boolean immediate)
Specified by:
setImmediate in interface EditableValueHolder

isRequired

@JSFProperty(defaultValue="false")
public boolean isRequired()
A boolean value that indicates whether an input value is required.

If this value is true and no input value is provided by a postback operation, then the "requiredMessage" text is registered as a FacesMessage for the request, and validation fails.

Default value: false.

Specified by:
isRequired 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

getConverterMessage

@JSFProperty
public String getConverterMessage()
Text to be displayed to the user as an error message when conversion of a submitted value to the target type fails.


setConverterMessage

public void setConverterMessage(String converterMessage)

getRequiredMessage

@JSFProperty
public String getRequiredMessage()
Text to be displayed to the user as an error message when this component is marked as "required" but no input data is present during a postback (ie the user left the required field blank).


setRequiredMessage

public void setRequiredMessage(String requiredMessage)

getValidator

@JSFProperty(stateHolder=true,
             returnSignature="void",
             methodSignature="javax.faces.context.FacesContext,javax.faces.component.UIComponent,java.lang.Object")
public MethodBinding getValidator()
Deprecated. 

A method-binding EL expression which is invoked during the validation phase for this component.

The invoked method is expected to check the submitted value for this component, and if not acceptable then report a validation error for the component.

The method is expected to have the prototype

public void aMethod(FacesContext, UIComponent,Object)

Specified by:
getValidator in interface EditableValueHolder

setValidator

public void setValidator(MethodBinding validator)
Deprecated. 

See getValidator.

Specified by:
setValidator in interface EditableValueHolder

addValidator

public void addValidator(Validator validator)
See getValidator.

Specified by:
addValidator in interface EditableValueHolder

removeValidator

public void removeValidator(Validator validator)
See getValidator.

Specified by:
removeValidator in interface EditableValueHolder

getValidators

public Validator[] getValidators()
See getValidator.

Specified by:
getValidators in interface EditableValueHolder

getValidatorMessage

@JSFProperty
public String getValidatorMessage()
Text which will be shown if validation fails.


setValidatorMessage

public void setValidatorMessage(String validatorMessage)

getValueChangeListener

@JSFProperty(stateHolder=true,
             returnSignature="void",
             methodSignature="javax.faces.event.ValueChangeEvent",
             clientEvent="valueChange")
public MethodBinding getValueChangeListener()
Deprecated. 

A method which is invoked during postback processing for the current view if the submitted value for this component is not equal to the value which the "value" expression for this component returns.

The phase in which this method is invoked can be controlled via the immediate attribute.

Specified by:
getValueChangeListener in interface EditableValueHolder

setValueChangeListener

public void setValueChangeListener(MethodBinding valueChangeListener)
Deprecated. 

See getValueChangeListener.

Specified by:
setValueChangeListener in interface EditableValueHolder

isValid

@JSFProperty(defaultValue="true",
             tagExcluded=true)
public boolean isValid()
Specifies whether the component's value is currently valid, ie whether the validators attached to this component have allowed it.

Specified by:
isValid in interface EditableValueHolder

setValid

public void setValid(boolean valid)
Specified by:
setValid in interface EditableValueHolder

isLocalValueSet

@JSFProperty(defaultValue="false",
             tagExcluded=true)
public boolean isLocalValueSet()
Specifies whether a local value is currently set.

If false, values are being retrieved from any attached ValueBinding.

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

getSubmittedValue

@JSFProperty(tagExcluded=true)
public Object getSubmittedValue()
Gets the current submitted value. This value, if non-null, is set by the Renderer to store a possibly invalid value for later conversion or redisplay, and has not yet been converted into the proper type for this component instance. This method should only be used by the decode() and validate() method of this component, or its corresponding Renderer; however, user code may manually set it to null to erase any submitted value.

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

addValueChangeListener

public void addValueChangeListener(ValueChangeListener listener)
Specified by:
addValueChangeListener in interface EditableValueHolder

removeValueChangeListener

public void removeValueChangeListener(ValueChangeListener listener)
Specified by:
removeValueChangeListener in interface EditableValueHolder

getValueChangeListeners

@JSFListener(event="javax.faces.event.ValueChangeEvent")
public ValueChangeListener[] getValueChangeListeners()
The valueChange event is delivered when the value attribute is changed.

Specified by:
getValueChangeListeners in interface EditableValueHolder

markInitialState

public void markInitialState()
Specified by:
markInitialState in interface PartialStateHolder
Overrides:
markInitialState in class UIOutput

clearInitialState

public void clearInitialState()
Description copied from class: UIComponent

Specified by:
clearInitialState in interface PartialStateHolder
Overrides:
clearInitialState in class UIOutput

saveState

public Object saveState(FacesContext facesContext)
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 facesContext,
                         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.

isEmpty

public static boolean isEmpty(Object value)
Check if a value is empty or not. Since we don't know the class of value we have to check and deal with it properly.

Parameters:
value -
Returns:
Since:
2.0


Copyright © 2014 The Apache Software Foundation. All Rights Reserved.