Class UIInput
- java.lang.Object
-
- jakarta.faces.component.UIComponent
-
- jakarta.faces.component.UIComponentBase
-
- jakarta.faces.component.UIOutput
-
- jakarta.faces.component.UIInput
-
- All Implemented Interfaces:
EditableValueHolder
,PartialStateHolder
,StateHolder
,TransientStateHolder
,ValueHolder
,ComponentSystemEventListener
,FacesListener
,SystemEventListenerHolder
,EventListener
- Direct Known Subclasses:
HtmlInputFile
,HtmlInputHidden
,HtmlInputSecret
,HtmlInputText
,HtmlInputTextarea
,UISelectBoolean
,UISelectMany
,UISelectOne
,UIViewParameter
public class UIInput extends UIOutput implements EditableValueHolder
UIInput is a
UIComponent
that represents a component that both displays output to the user (likeUIOutput
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, individualRenderer
s 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 tonull
.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 theimmediate
property is set totrue
, 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 thisUIInput
detects that a value change has actually occurred, and that all validations have been successfully passed, it will queue aValueChangeEvent
. Later on, thebroadcast()
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 theimmediate
property is set totrue
. If the validation fails, the implementation must callFacesContext.validationFailed()
.By default, the
rendererType
property must be set to "Text
". This value can be changed by calling thesetRendererType()
method.
-
-
Field Summary
Fields Modifier and Type Field Description static String
ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE
If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, validation must be performed, even when there is no corresponding value for this component in the incoming request.static String
COMPONENT_FAMILY
The standard component family for this component.static String
COMPONENT_TYPE
The standard component type for this component.static String
CONVERSION_MESSAGE_ID
The message identifier of theFacesMessage
to be created if a conversion error occurs, and neither the page author nor theConverterException
provides a message.static String
EMPTY_STRING_AS_NULL_PARAM_NAME
The name of a context parameter that indicates how empty strings need to be interpreted.static String
REQUIRED_MESSAGE_ID
The message identifier of theFacesMessage
to be created if a required check fails.static String
UPDATE_MESSAGE_ID
The message identifier of theFacesMessage
to be created if a model update error occurs, and the thrown exception has no message.static String
VALIDATE_EMPTY_FIELDS_PARAM_NAME
The name of a context parameter that indicates how empty values should be handled with respect to validation.-
Fields inherited from class jakarta.faces.component.UIComponent
ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, FACETS_KEY, VIEW_LOCATION_KEY
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addValidator(Validator validator)
void
addValueChangeListener(ValueChangeListener listener)
Add a newValueChangeListener
to the set of listeners interested in being notified whenValueChangeEvent
s occur.void
clearInitialState()
For each of the attached objects on this instance that implementPartialStateHolder
, callPartialStateHolder.clearInitialState()
on the attached object.protected boolean
compareValues(Object previous, Object value)
Returntrue
if the new value is different from the previous value.void
decode(FacesContext context)
Decode any new state of thisUIComponent
from the request contained in the specifiedFacesContext
, and store this state as needed.protected Object
getConvertedValue(FacesContext context, Object newSubmittedValue)
Convert the submitted value into a "local value" of the appropriate data type, if necessary.String
getConverterMessage()
If there has been a call tosetConverterMessage(java.lang.String)
on this instance, return the message.String
getFamily()
Return the identifier of the component family to which this component belongs.String
getRequiredMessage()
If there has been a call tosetRequiredMessage(java.lang.String)
on this instance, return the message.Object
getSubmittedValue()
Return the submittedValue value of thisUIInput
component.String
getValidatorMessage()
If there has been a call tosetValidatorMessage(java.lang.String)
on this instance, return the message.Validator[]
getValidators()
Object
getValue()
If there is a local value, return it, otherwise return the result of callingsuper.getVaue()
.ValueChangeListener[]
getValueChangeListeners()
Return the set of registeredValueChangeListener
s for thisUIInput
instance.static boolean
isEmpty(Object value)
Is the value denoting an empty value.boolean
isImmediate()
Return the "immediate" state for this component.boolean
isLocalValueSet()
Return the "local value set" state for this component.boolean
isRequired()
Return the "required field" state for this component.boolean
isValid()
Return a flag indicating whether the local value of this component is valid (no conversion error has occurred).void
markInitialState()
In addition to the actions taken inUIOutput
whenPartialStateHolder.markInitialState()
is called, check if any of the installedValidator
s are PartialStateHolders and if so, callPartialStateHolder.markInitialState()
as appropriate.void
processDecodes(FacesContext context)
Specialized decode behavior on top of that provided by the superclass.void
processUpdates(FacesContext context)
In addition to the standardprocessUpdates
behavior inherited fromUIComponentBase
, callsupdateModel()
.void
processValidators(FacesContext context)
In addition to the standardprocessValidators
behavior inherited fromUIComponentBase
, callsvalidate()
if theimmediate
property is false (which is the default); if the component is invalid afterwards, callsFacesContext.renderResponse()
.void
removeValidator(Validator validator)
void
removeValueChangeListener(ValueChangeListener listener)
Remove an existingValueChangeListener
(if any) from the set of listeners interested in being notified whenValueChangeEvent
s occur.void
resetValue()
Convenience method to reset this component's value to the un-initialized state.void
restoreState(FacesContext context, Object state)
Perform any processing required to restore the state from the entries in the state Object.Object
saveState(FacesContext context)
Gets the state of the instance as aSerializable
Object.void
setConverterMessage(String message)
Override anyValueExpression
set for the "converterMessage" with the literal argument provided to this method.void
setImmediate(boolean immediate)
Set the "immediate" state for this component.void
setLocalValueSet(boolean localValueSet)
Sets the "local value set" state for this component.void
setRequired(boolean required)
Set the "required field" state for this component.void
setRequiredMessage(String message)
Override anyValueExpression
set for the "requiredMessage" with the literal argument provided to this method.void
setSubmittedValue(Object submittedValue)
Set the submittedValue value of thisUIInput
component.void
setValid(boolean valid)
Set a flag indicating whether the local value of this component is valid (no conversion error has occurred).void
setValidatorMessage(String message)
Override anyValueExpression
set for the "validatorMessage" with the literal argument provided to this method.void
setValue(Object value)
Set the value of thisUIComponent
(if any).void
updateModel(FacesContext context)
Perform the following algorithm to update the model data associated with thisUIInput
, if any, as appropriate.void
validate(FacesContext context)
Perform the following algorithm to validate the local value of thisUIInput
.protected void
validateValue(FacesContext context, Object newValue)
Set the "valid" property according to the below algorithm.-
Methods inherited from class jakarta.faces.component.UIOutput
getConverter, getLocalValue, setConverter
-
Methods inherited from class jakarta.faces.component.UIComponentBase
addClientBehavior, addFacesListener, broadcast, encodeBegin, encodeChildren, encodeEnd, findComponent, getAttributes, getChildCount, getChildren, getClientBehaviors, getClientId, getDefaultEventName, getEventNames, getFacesContext, getFacesListeners, getFacet, getFacetCount, getFacets, getFacetsAndChildren, getId, getListenersForEventClass, getParent, getPassThroughAttributes, getRenderer, getRendererType, getRendersChildren, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, subscribeToEvent, unsubscribeFromEvent
-
Methods inherited from class jakarta.faces.component.UIComponent
encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, getPassThroughAttributes, getResourceBundleMap, getStateHelper, getStateHelper, getTransientStateHelper, getTransientStateHelper, getValueExpression, initialStateMarked, isCompositeComponent, isInView, isVisitable, popComponentFromEL, processEvent, pushComponentToEL, restoreTransientState, saveTransientState, setInView, setValueExpression, visitTree
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface jakarta.faces.component.ValueHolder
getConverter, getLocalValue, setConverter
-
-
-
-
Field Detail
-
COMPONENT_TYPE
public static final String COMPONENT_TYPE
The standard component type for this component.
- See Also:
- Constant Field Values
-
COMPONENT_FAMILY
public static final String COMPONENT_FAMILY
The standard component family for this component.
- See Also:
- Constant Field Values
-
CONVERSION_MESSAGE_ID
public static final String CONVERSION_MESSAGE_ID
The message identifier of the
FacesMessage
to be created if a conversion error occurs, and neither the page author nor theConverterException
provides a message.- See Also:
- Constant Field Values
-
REQUIRED_MESSAGE_ID
public static final String REQUIRED_MESSAGE_ID
The message identifier of the
FacesMessage
to be created if a required check fails.- See Also:
- Constant Field Values
-
UPDATE_MESSAGE_ID
public static final String UPDATE_MESSAGE_ID
The message identifier of the
FacesMessage
to be created if a model update error occurs, and the thrown exception has no message.- See Also:
- Constant Field Values
-
VALIDATE_EMPTY_FIELDS_PARAM_NAME
public static final String VALIDATE_EMPTY_FIELDS_PARAM_NAME
The name of a context parameter that indicates how empty values should be handled with respect to validation. See
validateValue(jakarta.faces.context.FacesContext, java.lang.Object)
for the allowable values and specification of how they should be interpreted.- See Also:
- Constant Field Values
-
EMPTY_STRING_AS_NULL_PARAM_NAME
public static final String EMPTY_STRING_AS_NULL_PARAM_NAME
The name of a context parameter that indicates how empty strings need to be interpreted.
- See Also:
- Constant Field Values
-
ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE
public static final String ALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE
If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, validation must be performed, even when there is no corresponding value for this component in the incoming request. See
validate(jakarta.faces.context.FacesContext)
.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
UIInput
public UIInput()
Create a new
UIInput
instance with default property values.
-
-
Method Detail
-
getFamily
public String getFamily()
Description copied from class:UIComponent
Return the identifier of the component family to which this component belongs. This identifier, in conjunction with the value of the
rendererType
property, may be used to select the appropriateRenderer
for this component instance. Note this method should NOT returnnull
-
getSubmittedValue
public Object getSubmittedValue()
Return the submittedValue value of this
UIInput
component. This method should only be used by thedecode()
andvalidate()
method of this component, or its correspondingRenderer
.- Specified by:
getSubmittedValue
in interfaceEditableValueHolder
- Returns:
- the submitted value.
-
setSubmittedValue
public void setSubmittedValue(Object submittedValue)
Set the submittedValue value of this
UIInput
component. This method should only be used by thedecode()
andvalidate()
method of this component, or its correspondingRenderer
.- Specified by:
setSubmittedValue
in interfaceEditableValueHolder
- Parameters:
submittedValue
- The new submitted value
-
getValue
public Object getValue()
If there is a local value, return it, otherwise return the result of calling
super.getVaue()
.- Specified by:
getValue
in interfaceValueHolder
- Overrides:
getValue
in classUIOutput
- Returns:
- the value.
- Since:
- 2.2
-
setValue
public void setValue(Object value)
Description copied from interface:ValueHolder
Set the value of this
UIComponent
(if any).- Specified by:
setValue
in interfaceValueHolder
- Overrides:
setValue
in classUIOutput
- Parameters:
value
- The new local value
-
resetValue
public void resetValue()
Convenience method to reset this component's value to the un-initialized state. This method does the following:
Call
UIOutput.setValue(java.lang.Object)
.Call
setSubmittedValue(java.lang.Object)
passingnull
.Clear state for property
localValueSet
.Clear state for property
valid
.Upon return from this call if the instance had a
ValueBinding
associated with it for the "value" property, this binding is evaluated whenUIOutput.getValue()
is called. Otherwise,null
is returned fromgetValue()
.- Specified by:
resetValue
in interfaceEditableValueHolder
- Overrides:
resetValue
in classUIOutput
-
isLocalValueSet
public boolean isLocalValueSet()
Return the "local value set" state for this component. Calls tosetValue()
automatically reset this property totrue
.- Specified by:
isLocalValueSet
in interfaceEditableValueHolder
- Returns:
true
if the local value is set,false
otherwise.
-
setLocalValueSet
public void setLocalValueSet(boolean localValueSet)
Sets the "local value set" state for this component.- Specified by:
setLocalValueSet
in interfaceEditableValueHolder
- Parameters:
localValueSet
- the "local value set" boolean.
-
isRequired
public boolean isRequired()
Return the "required field" state for this component.
- Specified by:
isRequired
in interfaceEditableValueHolder
- Returns:
true
if required,false
otherwise.
-
getRequiredMessage
public String getRequiredMessage()
If there has been a call to
setRequiredMessage(java.lang.String)
on this instance, return the message. Otherwise, callUIComponent.getValueExpression(java.lang.String)
passing the key "requiredMessage", get the result of the expression, and return it. AnyELException
s thrown during the call togetValue()
must be wrapped in aFacesException
and rethrown.- Returns:
- the required message.
-
setRequiredMessage
public void setRequiredMessage(String message)
Override any
ValueExpression
set for the "requiredMessage" with the literal argument provided to this method. Subsequent calls togetRequiredMessage()
will return this value;- Parameters:
message
- the literal message value to be displayed in the event the user hasn't supplied a value and one is required.
-
getConverterMessage
public String getConverterMessage()
If there has been a call to
setConverterMessage(java.lang.String)
on this instance, return the message. Otherwise, callUIComponent.getValueExpression(java.lang.String)
passing the key "converterMessage", get the result of the expression, and return it. AnyELException
s thrown during the call togetValue()
must be wrapped in aFacesException
and rethrown.- Returns:
- the converter message.
-
setConverterMessage
public void setConverterMessage(String message)
Override any
ValueExpression
set for the "converterMessage" with the literal argument provided to this method. Subsequent calls togetConverterMessage()
will return this value;- Parameters:
message
- the literal message value to be displayed in the event conversion fails.
-
getValidatorMessage
public String getValidatorMessage()
If there has been a call to
setValidatorMessage(java.lang.String)
on this instance, return the message. Otherwise, callUIComponent.getValueExpression(java.lang.String)
passing the key "validatorMessage", get the result of the expression, and return it. AnyELException
s thrown during the call togetValue()
must be wrapped in aFacesException
and rethrown.- Returns:
- the validator message.
-
setValidatorMessage
public void setValidatorMessage(String message)
Override any
ValueExpression
set for the "validatorMessage" with the literal argument provided to this method. Subsequent calls togetValidatorMessage()
will return this value;- Parameters:
message
- the literal message value to be displayed in the event validation fails.
-
isValid
public boolean isValid()
Description copied from interface:EditableValueHolder
Return a flag indicating whether the local value of this component is valid (no conversion error has occurred).
- Specified by:
isValid
in interfaceEditableValueHolder
- Returns:
true
if valid,false
otherwise.
-
setValid
public void setValid(boolean valid)
Description copied from interface:EditableValueHolder
Set a flag indicating whether the local value of this component is valid (no conversion error has occurred).
- Specified by:
setValid
in interfaceEditableValueHolder
- Parameters:
valid
- The new valid flag
-
setRequired
public void setRequired(boolean required)
Set the "required field" state for this component.
- Specified by:
setRequired
in interfaceEditableValueHolder
- Parameters:
required
- The new "required field" state
-
isImmediate
public boolean isImmediate()
Description copied from interface:EditableValueHolder
Return the "immediate" state for this component.
- Specified by:
isImmediate
in interfaceEditableValueHolder
- Returns:
true
if is immediate,false
otherwise.
-
setImmediate
public void setImmediate(boolean immediate)
Description copied from interface:EditableValueHolder
Set the "immediate" state for this component. When set to true, the component's value will be converted and validated immediately in the Apply Request Values phase, and
ValueChangeEvent
s will be delivered in that phase as well. The default value for this property must befalse
.- Specified by:
setImmediate
in interfaceEditableValueHolder
- Parameters:
immediate
- The new "immediate" state
-
markInitialState
public void markInitialState()
In addition to the actions taken in
UIOutput
whenPartialStateHolder.markInitialState()
is called, check if any of the installedValidator
s are PartialStateHolders and if so, callPartialStateHolder.markInitialState()
as appropriate.- Specified by:
markInitialState
in interfacePartialStateHolder
- Overrides:
markInitialState
in classUIOutput
-
clearInitialState
public void clearInitialState()
Description copied from class:UIComponentBase
For each of the attached objects on this instance that implement
PartialStateHolder
, callPartialStateHolder.clearInitialState()
on the attached object.- Specified by:
clearInitialState
in interfacePartialStateHolder
- Overrides:
clearInitialState
in classUIOutput
-
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 fromUIComponentBase
, callsvalidate()
if the theimmediate
property is true; if the component is invalid afterwards or aRuntimeException
is thrown, callsFacesContext.renderResponse()
.- Overrides:
processDecodes
in classUIComponentBase
- Parameters:
context
-FacesContext
for the request we are processing- Throws:
NullPointerException
- ifcontext
isnull
-
processValidators
public void processValidators(FacesContext context)
In addition to the standard
processValidators
behavior inherited fromUIComponentBase
, callsvalidate()
if theimmediate
property is false (which is the default); if the component is invalid afterwards, callsFacesContext.renderResponse()
. To ensure thePostValidateEvent
is published at the proper time, this component must be validated first, followed by the component's children and facets. If aRuntimeException
is thrown during validation processing, callsFacesContext.renderResponse()
and re-throw the exception.- Overrides:
processValidators
in classUIComponentBase
- Parameters:
context
-FacesContext
for the request we are processing- Throws:
NullPointerException
- ifcontext
isnull
- See Also:
PreValidateEvent
,PostValidateEvent
-
processUpdates
public void processUpdates(FacesContext context)
In addition to the standard
processUpdates
behavior inherited fromUIComponentBase
, callsupdateModel()
. If the component is invalid afterwards, callsFacesContext.renderResponse()
. If aRuntimeException
is thrown during update processing, callsFacesContext.renderResponse()
and re-throw the exception.- Overrides:
processUpdates
in classUIComponentBase
- Parameters:
context
-FacesContext
for the request we are processing- Throws:
NullPointerException
- ifcontext
isnull
-
decode
public void decode(FacesContext context)
Description copied from class:UIComponent
Decode any new state of this
UIComponent
from the request contained in the specifiedFacesContext
, and store this state as needed.During decoding, events may be enqueued for later processing (by event listeners who have registered an interest), by calling
queueEvent()
.- Overrides:
decode
in classUIComponentBase
- Parameters:
context
-FacesContext
for the request we are processing- Throws:
NullPointerException
- ifcontext
isnull
-
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 isfalse
, take no further action. - If the
localValueSet
property of this component isfalse
, take no further action. - If no
ValueExpression
forvalue
exists, take no further action. - Call
setValue()
method of theValueExpression
to update the value that theValueExpression
points at. - If the
setValue()
method returns successfully: - If the
setValue()
method throws an Exception:- Enqueue an error message. Create a
FacesMessage
with the idUPDATE_MESSAGE_ID
. Create aUpdateModelException
, passing theFacesMessage
and the caught exception to the constructor. Create anExceptionQueuedEventContext
, passing theFacesContext
, theUpdateModelException
, this component instance, andPhaseId.UPDATE_MODEL_VALUES
to its constructor. CallFacesContext.getExceptionHandler()
and then callExceptionHandler.processEvent(jakarta.faces.event.SystemEvent)
, passing theExceptionQueuedEventContext
. - Set the
valid
property of thisUIInput
tofalse
.
- Enqueue an error message. Create a
- Parameters:
context
-FacesContext
for the request we are processing- Throws:
NullPointerException
- ifcontext
isnull
- If the
-
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 returnsnull
, and the value of theALWAYS_PERFORM_VALIDATION_WHEN_REQUIRED_IS_TRUE
context-param is true (ignoring case), examine the value of the "required" property. If the value of "required" is true, continue as below. If the value of "required" is false or the required attribute is not set, exit without further processing. If the context-param is not set, or is set to false (ignoring case), exit without further processing. (This indicates that no value was submitted for this component.) - If the
jakarta.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL
context parameter value istrue
(ignoring case), andgetSubmittedValue()
returns a zero-lengthString
call
, passingsetSubmittedValue(java.lang.Object)
null
as the argument and continue processing usingnull
as the current submitted value. - Convert the submitted value into a "local value" of the appropriate data type by calling
getConvertedValue(jakarta.faces.context.FacesContext, java.lang.Object)
. - If conversion fails:
- Enqueue an appropriate error message by calling the
addMessage()
method on theFacesContext
. - Set the
valid
property on this component tofalse
- Enqueue an appropriate error message by calling the
- Validate the property by calling
validateValue(jakarta.faces.context.FacesContext, java.lang.Object)
. - If the
valid
property of this component is stilltrue
, retrieve the previous value of the component (withgetValue()
), store the new local value usingsetValue()
, and reset the submitted value to null with a call tosetSubmittedValue(java.lang.Object)
passingnull
as the argument. If the local value is different from the previous value of this component, as determined by a call tocompareValues(java.lang.Object, java.lang.Object)
, fire aValueChangeEvent
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 thesuper.validate()
method to perform the standard processing described above.- Parameters:
context
- TheFacesContext
for the current request- Throws:
NullPointerException
- ifcontext
is null
- Retrieve the submitted value with
-
getConvertedValue
protected Object getConvertedValue(FacesContext context, Object newSubmittedValue) throws ConverterException
Convert the submitted value into a "local value" of the appropriate data type, if necessary. Employ the following algorithm to do so:
- If a
Renderer
is present, callgetConvertedValue()
to convert the submitted value. - If no
Renderer
is present, and the submitted value is a String, locate aConverter
as follows:- If
getConverter()
returns a non-nullConverter
, use that instance. - Otherwise, if a value binding for
value
exists, callgetType()
on it.- If this call returns
null
, assume the output type isString
and perform no conversion. - Otherwise, call
Application.createConverter(Class)
to locate any registeredConverter
capable of converting data values of the specified type.
- If this call returns
- If
- If a
Converter
instance was located, call itsgetAsObject()
method to perform the conversion. If conversion fails, theConverter
will have thrown aConverterException
which is declared as a checked exception on this method, and thus must be handled by the caller. - Otherwise, use the submitted value without any conversion
This method can be overridden by subclasses for more specific behavior.
- Parameters:
context
- the Faces context.newSubmittedValue
- the new submitted value.- Returns:
- the converted value.
- Throws:
ConverterException
- If a
-
validateValue
protected void validateValue(FacesContext context, Object newValue)
Set the "valid" property according to the below algorithm.
-
If the
valid
property on this component is stilltrue
, and therequired
property is alsotrue
, ensure that the local value is not empty (where "empty" is defined asnull
or a zero-length String). If the local value is empty:-
Enqueue an appropriate error message by calling the
addMessage()
method on theFacesContext
instance for the current request. If thegetRequiredMessage()
returns non-null
, use the value as thesummary
anddetail
in theFacesMessage
that is enqueued on theFacesContext
, otherwise use the message for theREQUIRED_MESSAGE_ID
. - Set the
valid
property on this component tofalse
. -
If calling
ValidatorException.getFacesMessages()
returns non-null
, each message should be added to theFacesContext
. Otherwise the single message returned fromValidatorException.getFacesMessage()
should be added.
-
-
Otherwise, if the
valid
property on this component is stilltrue
, take the following action to determine if validation of this component should proceed.-
If the value is not empty, validation should proceed.
-
If the value is empty, but the system has been directed to validate empty fields, validation should proceed. The implementation must obtain the init parameter
Map
from theExternalContext
and inspect the value for the key given by the value of the symbolic constantVALIDATE_EMPTY_FIELDS_PARAM_NAME
. If there is no value under that key, use the same key and look in the application map from theExternalContext
. If the value isnull
or equal to the string “auto
” (without the quotes) take appropriate action to determine if Bean Validation is present in the runtime environment. If not, validation should not proceed. If so, validation should proceed. If the value is equal (ignoring case) to “true
” (without the quotes) validation should proceed. Otherwise, validation should not proceed.
If the above determination indicates that validation should proceed, call the
validate()
method of eachValidator
registered for thisUIInput
, followed by the method pointed at by thevalidatorBinding
property (if any). If any of these validators or the method throws aValidatorException
, catch the exception, add its message (if any) to theFacesContext
, and set thevalid
property of this component to false. -
- Parameters:
context
- the Faces context.newValue
- the new value.
-
-
compareValues
protected boolean compareValues(Object previous, Object value)
Return
true
if the new value is different from the previous value. First compare the two values by passing value to theequals
method on argument previous. If that method returnstrue
, returntrue
. If that method returnsfalse
, and both arguments implementjava.lang.Comparable
, compare the two values by passing value to thecompareTo
method on argument previous. Returntrue
if this method returns0
,false
otherwise.- Parameters:
previous
- old value of this component (if any)value
- new value of this component (if any)- Returns:
true
if the new value is different from the previous value,false
otherwise.
-
isEmpty
public static boolean isEmpty(Object value)
Is the value denoting an empty value.
If the value is null, return true. If the value is a String and it is the empty string, return true. If the value is an array and the array length is 0, return true. If the value is a List and the List is empty, return true. If the value is a Collection and the Collection is empty, return true. If the value is a Map and the Map is empty, return true. In all other cases, return false.
- Parameters:
value
- the value to check.- Returns:
- true if it is, false otherwise.
-
addValidator
public void addValidator(Validator validator)
- Specified by:
addValidator
in interfaceEditableValueHolder
- Parameters:
validator
- TheValidator
to add- Throws:
NullPointerException
- ifvalidator
is null
-
getValidators
public Validator[] getValidators()
Return the set of registered
Validator
s for thisUIInput
instance. If there are no registered validators, a zero-length array is returned.- Specified by:
getValidators
in interfaceEditableValueHolder
- Returns:
- the validators, or a zero-length array.
-
removeValidator
public void removeValidator(Validator validator)
Remove a
Validator
instance from the set associated with thisUIInput
, if it was previously associated. Otherwise, do nothing.- Specified by:
removeValidator
in interfaceEditableValueHolder
- Parameters:
validator
- TheValidator
to remove
-
addValueChangeListener
public void addValueChangeListener(ValueChangeListener listener)
Add a new
ValueChangeListener
to the set of listeners interested in being notified whenValueChangeEvent
s occur.- Specified by:
addValueChangeListener
in interfaceEditableValueHolder
- Parameters:
listener
- TheValueChangeListener
to be added- Throws:
NullPointerException
- iflistener
isnull
-
getValueChangeListeners
public ValueChangeListener[] getValueChangeListeners()
Return the set of registered
ValueChangeListener
s for thisUIInput
instance. If there are no registered listeners, a zero-length array is returned.- Specified by:
getValueChangeListeners
in interfaceEditableValueHolder
- Returns:
- the value change listeners, or a zero-length array.
-
removeValueChangeListener
public void removeValueChangeListener(ValueChangeListener listener)
Remove an existing
ValueChangeListener
(if any) from the set of listeners interested in being notified whenValueChangeEvent
s occur.- Specified by:
removeValueChangeListener
in interfaceEditableValueHolder
- Parameters:
listener
- TheValueChangeListener
to be removed- Throws:
NullPointerException
- iflistener
isnull
-
saveState
public Object saveState(FacesContext context)
Description copied from interface:StateHolder
Gets the state of the instance as a
Serializable
Object.If the class that implements this interface has references to instances that implement StateHolder (such as a
UIComponent
with event handlers, validators, etc.) this method must call theStateHolder.saveState(jakarta.faces.context.FacesContext)
method on all those instances as well. This method must not save the state of children and facets. That is done via theStateManager
This method must not alter the state of the implementing object. In other words, after executing this code:
Object state = component.saveState(facesContext);
component
should be the same as before executing it.The return from this method must be
Serializable
- Specified by:
saveState
in interfaceStateHolder
- Overrides:
saveState
in classUIOutput
- Parameters:
context
- the Faces context.- Returns:
- the saved state.
-
restoreState
public void restoreState(FacesContext context, Object state)
Description copied from interface:StateHolder
Perform any processing required to restore the state from the entries in the state Object.
If the class that implements this interface has references to instances that also implement StateHolder (such as a
UIComponent
with event handlers, validators, etc.) this method must call theStateHolder.restoreState(jakarta.faces.context.FacesContext, java.lang.Object)
method on all those instances as well.If the
state
argument isnull
, take no action and return.- Specified by:
restoreState
in interfaceStateHolder
- Overrides:
restoreState
in classUIOutput
- Parameters:
context
- the Faces context.state
- the state.
-
-