Package jakarta.faces.component

Interface EditableValueHolder

  • All Superinterfaces:
    ValueHolder
    All Known Implementing Classes:
    HtmlInputFile, HtmlInputHidden, HtmlInputSecret, HtmlInputText, HtmlInputTextarea, HtmlSelectBooleanCheckbox, HtmlSelectManyCheckbox, HtmlSelectManyListbox, HtmlSelectManyMenu, HtmlSelectOneListbox, HtmlSelectOneMenu, HtmlSelectOneRadio, UIInput, UISelectBoolean, UISelectMany, UISelectOne, UIViewParameter
    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.

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

      • addValidator

        void addValidator​(Validator validator)

      • removeValidator

        void removeValidator​(Validator validator)

      • resetValue

        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 isLocalValueSet() is false), and setting "valid" to true.
        Since:
        2.0