javax.faces.component
Interface EditableValueHolder

All Superinterfaces:

ValueHolder

All Known Implementing Classes:

HtmlInputHidden, UIInput, UISelectBoolean, UISelectMany, UISelectOne

public interface EditableValueHolder
extends ValueHolder

Defines the methods required for a component whose value can be modified by the user.

When a component implementing this interface is rendered, the value output is (in order):

• The "submitted value" if non-null.
• The component's "local value" if non-null.
• The result of evaluating the value-binding expression with name "value" for this component.

Rendering the submitted value if non-null allows a component to redisplay a user-provided value when validation fails for the component. The submitted value is usually just the plain string extracted from the servlet request. During successful validation of the component, the submitted value is converted to an appropriate datatype, and stored as the component's "local value", and then the "submitted value" is immediately reset to null.

Rendering the "local value" if non-null allows a component to redisplay a page when validation fails for some other component; the model can't be updated unless all components have passed validation. This also allows components to work without a defined "value" value-binding expression. When all components validate, the update model phase runs; all components with "value" value-bindings store the "local value" into the specified property then reset their local value to null.

Rendering the value-binding expression named "value" allows components to display data from the user's model classes. This is the most common way a component's renderer obtains the value to display. see Javadoc of JSF Specification for more.

Version:

$Revision: 676298 $ $Date: 2008-07-13 05:31:48 -0500 (Sun, 13 Jul 2008) $

Author:

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

Method Summary

void	addValidator(Validator validator)
void	addValueChangeListener(ValueChangeListener listener)
Object	getSubmittedValue() Get an object representing the most recent raw user input received for this component.
MethodBinding	getValidator() Deprecated. Use getValidators() instead.
Validator[]	getValidators()
MethodBinding	getValueChangeListener() Deprecated. Use getValueChangeLIsteners() instead.
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	removeValidator(Validator validator)
void	removeValueChangeListener(ValueChangeListener listener)
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 validatorBinding) Deprecated. Use addValidator(MethodExpressionValidaotr) instead.
void	setValueChangeListener(MethodBinding valueChangeMethod) Deprecated. use addValueChangeListener(MethodExpressionValueChangeListener) instead.

Methods inherited from interface javax.faces.component.ValueHolder

getConverter, getLocalValue, getValue, setConverter, setValue

Method Detail

getSubmittedValue

Object getSubmittedValue()

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.

setSubmittedValue

void setSubmittedValue(Object submittedValue)

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.

isLocalValueSet

boolean isLocalValueSet()

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

setLocalValueSet

void setLocalValueSet(boolean localValueSet)

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

isValid

boolean isValid()

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.

setValid

void setValid(boolean valid)

isRequired

boolean isRequired()

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.

setRequired

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.

isImmediate

boolean isImmediate()

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.

setImmediate

void setImmediate(boolean immediate)

getValidator

MethodBinding getValidator()

Deprecated. Use getValidators() instead.

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.

setValidator

void setValidator(MethodBinding validatorBinding)

Deprecated. Use addValidator(MethodExpressionValidaotr) instead.

getValueChangeListener

MethodBinding getValueChangeListener()

Deprecated. Use getValueChangeLIsteners() instead.

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.

setValueChangeListener

void setValueChangeListener(MethodBinding valueChangeMethod)

Deprecated. use addValueChangeListener(MethodExpressionValueChangeListener) instead.

addValidator

void addValidator(Validator validator)

getValidators

Validator[] getValidators()

removeValidator

void removeValidator(Validator validator)

addValueChangeListener

void addValueChangeListener(ValueChangeListener listener)

getValueChangeListeners

ValueChangeListener[] getValueChangeListeners()

removeValueChangeListener

void removeValueChangeListener(ValueChangeListener listener)