Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  java.util.EventListener, EditableValueHolder, PartialStateHolder, StateHolder, TransientStateHolder, ValueHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder

Direct Known Subclasses:
  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 (like `UIOutput` 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, individual `Renderer`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 to `null`.

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 the `immediate` property is set to `true`, 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 this `UIInput` detects that a value change has actually occurred, and that all validations have been successfully passed, it will queue a `ValueChangeEvent`. Later on, the `broadcast()` 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 the `immediate` property is set to `true`. If the validation fails, the implementation must call `FacesContext.validationFailed()`.

By default, the `rendererType` property must be set to "`Text`". This value can be changed by calling the `setRendererType()` method.

Field Summary
`static java.lang.String` | `COMPONENT_FAMILY` The standard component family for this component.
`static java.lang.String` | `COMPONENT_TYPE` The standard component type for this component.
`static java.lang.String` | `CONVERSION_MESSAGE_ID` The message identifier of the `FacesMessage` to be created if a conversion error occurs, and neither the page author nor the `ConverterException` provides a message.
`static java.lang.String` | `REQUIRED_MESSAGE_ID` The message identifier of the `FacesMessage` to be created if a required check fails.
`static java.lang.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.
`static java.lang.String` | `VALIDATE_EMPTY_FIELDS_PARAM_NAME` The name of an application parameter that indicates how empty values should be handled with respect to validation.

Fields inherited from class javax.faces.component.UIComponent
`ATTRS_WITH_DECLARED_DEFAULT_VALUES, BEANINFO_KEY, bindings, COMPOSITE_COMPONENT_TYPE_KEY, COMPOSITE_FACET_NAME, CURRENT_COMPONENT, CURRENT_COMPOSITE_COMPONENT, FACETS_KEY, HONOR_CURRENT_COMPONENT_ATTRIBUTES_PARAM_NAME, VIEW_LOCATION_KEY`

Constructor Summary
`UIInput()` Create a new `UIInput` instance with default property values.

Method Summary
`void` | `addValidator(Validator validator)` Add a `Validator` instance to the set associated with this `UIInput`.
`void` | `addValueChangeListener(ValueChangeListener listener)` Add a new `ValueChangeListener` to the set of listeners interested in being notified when `ValueChangeEvent`s occur.
`void` | `clearInitialState()` For each of the attached objects on this instance that implement `PartialStateHolder`, call `PartialStateHolder.clearInitialState()` on the attached object.
`protected boolean` | `compareValues(java.lang.Object previous, java.lang.Object value)` Return `true` if the new value is different from the previous value.
`void` | `decode(FacesContext context)` Decode any new state of this `UIComponent` from the request contained in the specified `FacesContext`, and store this state as needed.
`protected java.lang.Object` | `getConvertedValue(FacesContext context, java.lang.Object newSubmittedValue)` Convert the submitted value into a "local value" of the appropriate data type, if necessary.
`java.lang.String` | `getConverterMessage()` If there has been a call to `setConverterMessage(java.lang.String)` on this instance, return the message.
`java.lang.String` | `getFamily()` Return the identifier of the component family to which this component belongs.
`java.lang.String` | `getRequiredMessage()` If there has been a call to `setRequiredMessage(java.lang.String)` on this instance, return the message.
`java.lang.Object` | `getSubmittedValue()` Return the submittedValue value of this `UIInput` component.
`MethodBinding` | `getValidator()` Deprecated. `getValidators()` should be used instead.
`java.lang.String` | `getValidatorMessage()` If there has been a call to `setValidatorMessage(java.lang.String)` on this instance, return the message.
`Validator[]` | `getValidators()` Return the set of registered `Validator`s for this `UIInput` instance.
`java.lang.Object` | `getValue()` Gets the value of this `UIComponent`.
`MethodBinding` | `getValueChangeListener()` If `EditableValueHolder.setValueChangeListener(javax.faces.el.MethodBinding)` was not previously called for this instance, this method must return `null`.
`ValueChangeListener[]` | `getValueChangeListeners()` Return the set of registered `ValueChangeListener`s for this `UIInput` instance.
`static boolean` | `isEmpty(java.lang.Object 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 in `UIOutput` when `PartialStateHolder.markInitialState()` is called, check if any of the installed `Validator`s are PartialStateHolders and if so, call `PartialStateHolder.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 standard `processUpdates` behavior inherited from `UIComponentBase`, calls `updateModel()`.
`void` | `processValidators(FacesContext context)` In addition to the standard `processValidators` behavior inherited from `UIComponentBase`, calls `validate()` if the `immediate` property is false (which is the default); if the component is invalid afterwards, calls `FacesContext.renderResponse()`.
`void` | `removeValidator(Validator validator)` Remove a `Validator` instance from the set associated with this `UIInput`, if it was previously associated.
`void` | `removeValueChangeListener(ValueChangeListener listener)` Remove an existing `ValueChangeListener` (if any) from the set of listeners interested in being notified when `ValueChangeEvent`s occur.
`void` | `resetValue()` Convenience method to reset this component's value to the un-initialized state.
`void` | `restoreState(FacesContext context, java.lang.Object state)` Perform any processing required to restore the state from the entries in the state Object.
`java.lang.Object` | `saveState(FacesContext context)` Gets the state of the instance as a `Serializable` Object.
`void` | `setConverterMessage(java.lang.String message)` Override any `ValueExpression` 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(java.lang.String message)` Override any `ValueExpression` set for the "requiredMessage" with the literal argument provided to this method.
`void` | `setSubmittedValue(java.lang.Object submittedValue)` Set the submittedValue value of this `UIInput` component.
`void` | `setValid(boolean valid)` Set a flag indicating whether the local value of this component is valid (no conversion error has occurred).
`void` | `setValidator(MethodBinding validatorBinding)` Deprecated. Use `addValidator(javax.faces.validator.Validator)` instead, obtaining the argument `Validator` by creating an instance of `MethodExpressionValidator`.
`void` | `setValidatorMessage(java.lang.String message)` Override any `ValueExpression` set for the "validatorMessage" with the literal argument provided to this method.
`void` | `setValue(java.lang.Object value)` Set the value of this `UIComponent` (if any).
`void` | `setValueChangeListener(MethodBinding valueChangeListener)` Deprecated. Use `addValueChangeListener(javax.faces.event.ValueChangeListener)` instead, obtaining the argument `ValueChangeListener` by creating an instance of `MethodExpressionValueChangeListener`.
`void` | `updateModel(FacesContext context)` Perform the following algorithm to update the model data associated with this `UIInput`, if any, as appropriate.
`void` | `validate(FacesContext context)` Perform the following algorithm to validate the local value of this `UIInput`.
`protected void` | `validateValue(FacesContext context, java.lang.Object newValue)` Set the "valid" property according to the below algorithm.

Methods inherited from class javax.faces.component.UIOutput
`getConverter, getLocalValue, setConverter`

Methods inherited from class javax.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, getRenderer, getRendererType, getRendersChildren, getValueBinding, invokeOnComponent, isRendered, isTransient, processRestoreState, processSaveState, queueEvent, removeFacesListener, restoreAttachedState, saveAttachedState, setId, setParent, setRendered, setRendererType, setTransient, setValueBinding, subscribeToEvent, unsubscribeFromEvent`

Methods inherited from class javax.faces.component.UIComponent
`encodeAll, getClientId, getCompositeComponentParent, getContainerClientId, getCurrentComponent, getCurrentCompositeComponent, getNamingContainer, 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 javax.faces.component.ValueHolder
`getConverter, getLocalValue, setConverter`

Field Detail

### COMPONENT_TYPE

    public static final java.lang.String COMPONENT_TYPE

  The standard component type for this component.

  See Also:
    Constant Field Values

### COMPONENT_FAMILY

    public static final java.lang.String COMPONENT_FAMILY

  The standard component family for this component.

  See Also:
    Constant Field Values

### CONVERSION_MESSAGE_ID

    public static final java.lang.String CONVERSION_MESSAGE_ID

  The message identifier of the `FacesMessage` to be created if a conversion error occurs, and neither the page author nor the `ConverterException` provides a message.

  See Also:
    Constant Field Values

### REQUIRED_MESSAGE_ID

    public static final java.lang.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 java.lang.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 java.lang.String VALIDATE_EMPTY_FIELDS_PARAM_NAME

  The name of an application parameter that indicates how empty values should be handled with respect to validation. See `validateValue(javax.faces.context.FacesContext, java.lang.Object)` for the allowable values and specification of how they should be interpreted.

  See Also:
    Constant Field Values

Constructor Detail

### UIInput

    public UIInput()

  Create a new `UIInput` instance with default property values.

Method Detail

### getFamily

    public java.lang.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 appropriate `Renderer` for this component instance.

  Overrides:
    `getFamily` in class `UIOutput`

### getSubmittedValue

    public java.lang.Object getSubmittedValue()

  Return the submittedValue value of this `UIInput` component. This method should only be used by the `decode()` and `validate()` method of this component, or its corresponding `Renderer`.

  Specified by:
    `getSubmittedValue` in interface `EditableValueHolder`

### setSubmittedValue

    public void setSubmittedValue(java.lang.Object submittedValue)

  Set the submittedValue value of this `UIInput` component. This method should only be used by the `decode()` and `validate()` method of this component, or its corresponding `Renderer`.

  Specified by:
    `setSubmittedValue` in interface `EditableValueHolder`
  Parameters:
    `submittedValue` - The new submitted value

### getValue

    public java.lang.Object getValue()

  Description copied from interface: `ValueHolder`

  Gets the value of this `UIComponent`. If validation failed, as indicated by `FacesContext.isValidationFailed()` returning `true`, always return the local value. Otherwise, first, consult the local value property of this component. If non-`null` return it. If `null`, see if we have a `ValueExpression` for the `value` property. If so, return the result of evaluating the property, otherwise return `null`. Note that because the specification for `UIComponent.setValueBinding(java.lang.String, javax.faces.el.ValueBinding)` requires a call through to `UIComponent.setValueExpression(java.lang.String, javax.el.ValueExpression)`, legacy tags will continue to work.

  Specified by:
    `getValue` in interface `ValueHolder`
  Overrides:
    `getValue` in class `UIOutput`

### setValue

    public void setValue(java.lang.Object value)

  Description copied from interface: `ValueHolder`

  Set the value of this `UIComponent` (if any).

  Specified by:
    `setValue` in interface `ValueHolder`
  Overrides:
    `setValue` in class `UIOutput`
  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 `setValue(java.lang.Object)` passing `null`.

  Call `setSubmittedValue(java.lang.Object)` passing `null`.

  Call `setLocalValueSet(boolean)` passing `false`.

  Call `setValid(boolean)` passing `true`.

  Upon return from this call if the instance had a `ValueBinding` associated with it for the "value" property, this binding is evaluated when `UIOutput.getValue()` is called. Otherwise, `null` is returned from `getValue()`.

  Specified by:
    `resetValue` in interface `EditableValueHolder`

### isLocalValueSet

    public boolean isLocalValueSet()

  Return the "local value set" state for this component. Calls to `setValue()` automatically reset this property to `true`.

  Specified by:
    `isLocalValueSet` in interface `EditableValueHolder`

### setLocalValueSet

    public void setLocalValueSet(boolean localValueSet)

  Sets the "local value set" state for this component.

  Specified by:
    `setLocalValueSet` in interface `EditableValueHolder`

### isRequired

    public boolean isRequired()

  Return the "required field" state for this component.

  Specified by:
    `isRequired` in interface `EditableValueHolder`

### getRequiredMessage

    public java.lang.String getRequiredMessage()

  If there has been a call to `setRequiredMessage(java.lang.String)` on this instance, return the message. Otherwise, call `UIComponent.getValueExpression(java.lang.String)` passing the key "requiredMessage", get the result of the expression, and return it. Any `ELException`s thrown during the call to `getValue()` must be wrapped in a `FacesException` and rethrown.

### setRequiredMessage

    public void setRequiredMessage(java.lang.String message)

  Override any `ValueExpression` set for the "requiredMessage" with the literal argument provided to this method. Subsequent calls to `getRequiredMessage()` 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 java.lang.String getConverterMessage()

  If there has been a call to `setConverterMessage(java.lang.String)` on this instance, return the message. Otherwise, call `UIComponent.getValueExpression(java.lang.String)` passing the key "converterMessage", get the result of the expression, and return it. Any `ELException`s thrown during the call to `getValue()` must be wrapped in a `FacesException` and rethrown.

### setConverterMessage

    public void setConverterMessage(java.lang.String message)

  Override any `ValueExpression` set for the "converterMessage" with the literal argument provided to this method. Subsequent calls to `getConverterMessage()` will return this value;

  Parameters:
    `message` - the literal message value to be displayed in the event conversion fails.

### getValidatorMessage

    public java.lang.String getValidatorMessage()

  If there has been a call to `setValidatorMessage(java.lang.String)` on this instance, return the message. Otherwise, call `UIComponent.getValueExpression(java.lang.String)` passing the key "validatorMessage", get the result of the expression, and return it. Any `ELException`s thrown during the call to `getValue()` must be wrapped in a `FacesException` and rethrown.

### setValidatorMessage

    public void setValidatorMessage(java.lang.String message)

  Override any `ValueExpression` set for the "validatorMessage" with the literal argument provided to this method. Subsequent calls to `getValidatorMessage()` 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 interface `EditableValueHolder`

### 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 interface `EditableValueHolder`
  Parameters:
    `valid` - The new valid flag

### setRequired

    public void setRequired(boolean required)

  Set the "required field" state for this component.

  Specified by:
    `setRequired` in interface `EditableValueHolder`
  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 interface `EditableValueHolder`

### 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 be `false`.

  Specified by:
    `setImmediate` in interface `EditableValueHolder`
  Parameters:
    `immediate` - The new "immediate" state

### getValidator

    public MethodBinding getValidator()

  Deprecated. `getValidators()` should be used instead.

  Return a `MethodBinding` pointing at a method that will be called during Process Validations phase of the request processing lifecycle, to validate the current value of this component.

  Specified by:
    `getValidator` in interface `EditableValueHolder`

### setValidator

    public void setValidator(MethodBinding validatorBinding)

  Deprecated. Use `addValidator(javax.faces.validator.Validator)` instead, obtaining the argument `Validator` by creating an instance of `MethodExpressionValidator`.

  Set a `MethodBinding` pointing at a method that will be called during Process Validations phase of the request processing lifecycle, to validate the current value of this component.

  Any method referenced by such an expression must be public, with a return type of `void`, and accept parameters of type `FacesContext`, `UIComponent`, and `Object`.

  Specified by:
    `setValidator` in interface `EditableValueHolder`
  Parameters:
    `validatorBinding` - The new `MethodBinding` instance

### getValueChangeListener

    public MethodBinding getValueChangeListener()

  Description copied from interface: `EditableValueHolder`

  If `EditableValueHolder.setValueChangeListener(javax.faces.el.MethodBinding)` was not previously called for this instance, this method must return `null`. If it was called, this method must return the exact `MethodBinding` instance that was passed to `EditableValueHolder.setValueChangeListener(javax.faces.el.MethodBinding)`.

  Specified by:
    `getValueChangeListener` in interface `EditableValueHolder`

### setValueChangeListener

    public void setValueChangeListener(MethodBinding valueChangeListener)

  Deprecated. Use `addValueChangeListener(javax.faces.event.ValueChangeListener)` instead, obtaining the argument `ValueChangeListener` by creating an instance of `MethodExpressionValueChangeListener`.

  Wrap the argument `valueChangeMethod` in an implementation of `ValueChangeListener` and store it in the internal data structure that backs the `EditableValueHolder.getValueChangeListeners()` method, taking care to over-write any instance that was stored by a previous call to `setValueChangeListener`.

  This argument method will be called during the Process Validations or Apply Request Values phases (depending on the value of the `immediate` property).

  Any method referenced by such an expression must be public, with a return type of `void`, and accept a parameter of type `ValueChangeEvent`.

  Specified by:
    `setValueChangeListener` in interface `EditableValueHolder`
  Parameters:
    `valueChangeListener` - The new method binding instance

### markInitialState

    public void markInitialState()

  In addition to the actions taken in `UIOutput` when `PartialStateHolder.markInitialState()` is called, check if any of the installed `Validator`s are PartialStateHolders and if so, call `PartialStateHolder.markInitialState()` as appropriate.

  Specified by:
    `markInitialState` in interface `PartialStateHolder`
  Overrides:
    `markInitialState` in class `UIOutput`

### clearInitialState

    public void clearInitialState()

  Description copied from class: `UIComponentBase`

  For each of the attached objects on this instance that implement `PartialStateHolder`, call `PartialStateHolder.clearInitialState()` on the attached object.

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

### 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 from `UIComponentBase`, calls `validate()` if the the `immediate` property is true; if the component is invalid afterwards or a `RuntimeException` is thrown, calls `FacesContext.renderResponse()`.

  Overrides:
    `processDecodes` in class `UIComponentBase`
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `java.lang.NullPointerException` - if `context` is `null`

### processValidators

    public void processValidators(FacesContext context)

  In addition to the standard `processValidators` behavior inherited from `UIComponentBase`, calls `validate()` if the `immediate` property is false (which is the default); if the component is invalid afterwards, calls `FacesContext.renderResponse()`. If a `RuntimeException` is thrown during validation processing, calls `FacesContext.renderResponse()` and re-throw the exception.

  Overrides:
    `processValidators` in class `UIComponentBase`
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `java.lang.NullPointerException` - if `context` is `null`

### processUpdates

    public void processUpdates(FacesContext context)

  In addition to the standard `processUpdates` behavior inherited from `UIComponentBase`, calls `updateModel()`. If the component is invalid afterwards, calls `FacesContext.renderResponse()`. If a `RuntimeException` is thrown during update processing, calls `FacesContext.renderResponse()` and re-throw the exception.

  Overrides:
    `processUpdates` in class `UIComponentBase`
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `java.lang.NullPointerException` - if `context` is `null`

### decode

    public void decode(FacesContext context)

  Description copied from class: `UIComponent`

  Decode any new state of this `UIComponent` from the request contained in the specified `FacesContext`, 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 class `UIComponentBase`
  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `java.lang.NullPointerException` - if `context` is `null`

### 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 is `false`, take no further action.
  - If the `localValueSet` property of this component is `false`, take no further action.
  - If no `ValueExpression` for `value` exists, take no further action.
  - Call `setValue()` method of the `ValueExpression` to update the value that the `ValueExpression` points at.
  - If the `setValue()` method returns successfully:
    - Clear the local value of this `UIInput`.
    - Set the `localValueSet` property of this `UIInput` to false.
  - If the `setValue()` method throws an Exception:
    - Enqueue an error message. Create a `FacesMessage` with the id `UPDATE_MESSAGE_ID`. Create a `UpdateModelException`, passing the `FacesMessage` and the caught exception to the constructor. Create an `ExceptionQueuedEventContext`, passing the `FacesContext`, the `UpdateModelException`, this component instance, and `PhaseId.UPDATE_MODEL_VALUES` to its constructor. Call `FacesContext.getExceptionHandler()` and then call `ExceptionHandler.processEvent(javax.faces.event.SystemEvent)`, passing the `ExceptionQueuedEventContext`.
    - Set the `valid` property of this `UIInput` to `false`.
  The exception must not be re-thrown. This enables tree traversal to continue for this lifecycle phase, as in all the other lifecycle phases.

  Parameters:
    `context` - `FacesContext` for the request we are processing
  Throws:
    `java.lang.NullPointerException` - if `context` is `null`

### 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 returns `null`, exit without further processing. (This indicates that no value was submitted for this component.)

  - If the `javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL` context parameter value is `true` (ignoring case), and `getSubmittedValue()` returns a zero-length `String` call ``setSubmittedValue(java.lang.Object)``, passing `null` as the argument and continue processing using `null` as the current submitted value.

  - Convert the submitted value into a "local value" of the appropriate data type by calling `getConvertedValue(javax.faces.context.FacesContext, java.lang.Object)`.
  - If conversion fails:
    - Enqueue an appropriate error message by calling the `addMessage()` method on the `FacesContext`.
    - Set the `valid` property on this component to `false`

  - Validate the property by calling `validateValue(javax.faces.context.FacesContext, java.lang.Object)`.

  - If the `valid` property of this component is still `true`, retrieve the previous value of the component (with `getValue()`), store the new local value using `setValue()`, and reset the submitted value to null. If the local value is different from the previous value of this component, as determined by a call to `compareValues(java.lang.Object, java.lang.Object)`, fire a `ValueChangeEvent` 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 the `super.validate()` method to perform the standard processing described above.

  Parameters:
    `context` - The `FacesContext` for the current request
  Throws:
    `java.lang.NullPointerException` - if `context` is null

### getConvertedValue

    protected java.lang.Object getConvertedValue(FacesContext context,
                                                 java.lang.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, call `getConvertedValue()` to convert the submitted value.
  - If no `Renderer` is present, and the submitted value is a String, locate a `Converter` as follows:
    - If `getConverter()` returns a non-null `Converter`, use that instance.
    - Otherwise, if a value binding for `value` exists, call `getType()` on it.
      - If this call returns `null`, assume the output type is `String` and perform no conversion.
      - Otherwise, call `Application.createConverter(Class)` to locate any registered `Converter` capable of converting data values of the specified type.
  - If a `Converter` instance was located, call its `getAsObject()` method to perform the conversion. If conversion fails, the `Converter` will have thrown a `ConverterException` 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.

  Throws:
    `ConverterException`

### validateValue

    protected void validateValue(FacesContext context,
                                 java.lang.Object newValue)

  Set the "valid" property according to the below algorithm.

  - If the `valid` property on this component is still `true`, and the `required` property is also `true`, ensure that the local value is not empty (where "empty" is defined as `null` or a zero-length String). If the local value is empty:

    - Enqueue an appropriate error message by calling the `addMessage()` method on the `FacesContext` instance for the current request. If the `getRequiredMessage()` returns non-`null`, use the value as the `summary` and `detail` in the `FacesMessage` that is enqueued on the `FacesContext`, otherwise use the message for the `REQUIRED_MESSAGE_ID`.

    - Set the `valid` property on this component to `false`.

    - If calling `ValidatorException.getFacesMessages()` returns non-`null`, each message should be added to the `FacesContext`. Otherwise the single message returned from `ValidatorException.getFacesMessage()` should be added.

  - Otherwise, if the `valid` property on this component is still `true`, 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 the `ExternalContext` and inspect the value for the key given by the value of the symbolic constant `VALIDATE_EMPTY_FIELDS_PARAM_NAME`. If there is no value under that key, use the same key and look in the application map from the `ExternalContext`. If the value is `null` 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 each `Validator` registered for this `UIInput`, followed by the method pointed at by the `validatorBinding` property (if any). If any of these validators or the method throws a `ValidatorException`, catch the exception, add its message (if any) to the `FacesContext`, and set the `valid` property of this component to false.

### compareValues

    protected boolean compareValues(java.lang.Object previous,
                                    java.lang.Object value)

  Return `true` if the new value is different from the previous value. First compare the two values by passing value to the `equals` method on argument previous. If that method returns `true`, return `true`. If that method returns `false`, and both arguments implement `java.lang.Comparable`, compare the two values by passing value to the `compareTo` method on argument previous. Return `true` if this method returns `0`, `false` otherwise.

  Parameters:
    `previous` - old value of this component (if any)
    `value` - new value of this component (if any)

### isEmpty

    public static boolean isEmpty(java.lang.Object value)

### addValidator

    public void addValidator(Validator validator)

  Add a `Validator` instance to the set associated with this `UIInput`.

  Specified by:
    `addValidator` in interface `EditableValueHolder`
  Parameters:
    `validator` - The `Validator` to add
  Throws:
    `java.lang.NullPointerException` - if `validator` is null

### getValidators

    public Validator[] getValidators()

  Return the set of registered `Validator`s for this `UIInput` instance. If there are no registered validators, a zero-length array is returned.

  Specified by:
    `getValidators` in interface `EditableValueHolder`

### removeValidator

    public void removeValidator(Validator validator)

  Remove a `Validator` instance from the set associated with this `UIInput`, if it was previously associated. Otherwise, do nothing.

  Specified by:
    `removeValidator` in interface `EditableValueHolder`
  Parameters:
    `validator` - The `Validator` to remove

### addValueChangeListener

    public void addValueChangeListener(ValueChangeListener listener)

  Add a new `ValueChangeListener` to the set of listeners interested in being notified when `ValueChangeEvent`s occur.

  Specified by:
    `addValueChangeListener` in interface `EditableValueHolder`
  Parameters:
    `listener` - The `ValueChangeListener` to be added
  Throws:
    `java.lang.NullPointerException` - if `listener` is `null`

### getValueChangeListeners

    public ValueChangeListener[] getValueChangeListeners()

  Return the set of registered `ValueChangeListener`s for this `UIInput` instance. If there are no registered listeners, a zero-length array is returned.

  Specified by:
    `getValueChangeListeners` in interface `EditableValueHolder`

### removeValueChangeListener

    public void removeValueChangeListener(ValueChangeListener listener)

  Remove an existing `ValueChangeListener` (if any) from the set of listeners interested in being notified when `ValueChangeEvent`s occur.

  Specified by:
    `removeValueChangeListener` in interface `EditableValueHolder`
  Parameters:
    `listener` - The `ValueChangeListener` to be removed
  Throws:
    `java.lang.NullPointerException` - if `listener` is `null`

### saveState

    public java.lang.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 the `StateHolder.saveState(javax.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 the `StateManager`

  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 interface `StateHolder`
  Overrides:
    `saveState` in class `UIOutput`

### restoreState

    public void restoreState(FacesContext context,
                             java.lang.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 the `StateHolder.restoreState(javax.faces.context.FacesContext, java.lang.Object)` method on all those instances as well.

  If the `state` argument is `null`, take no action and return.

  Specified by:
    `restoreState` in interface `StateHolder`
  Overrides:
    `restoreState` in class `UIOutput`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright 2002-2010 Oracle America Inc, Inc. All Rights Reserved.