Package com.vaadin.ui

Class AbstractField<T>

    • Constructor Detail

      • AbstractField

        public AbstractField()

    • Method Detail

      • shouldHideErrors

        protected boolean shouldHideErrors()
        Returns true if the error indicator be hidden when painting the component even when there are errors. This is a mostly internal method, but can be overridden in subclasses e.g. if the error indicator should also be shown for empty fields in some cases.
        Returns:
        true to hide the error indicator, false to use the normal logic to show it when there are errors

      • getType

        public abstract Class<? extends T> getType()
        Returns the type of the Field. The methods getValue and setValue must be compatible with this type: one must be able to safely cast the value returned from getValue to the given type and pass any variable assignable to this type as an argument to setValue.
        Specified by:
        getType in interface Property<T>
        Returns:
        the type of the Field

      • isInvalidCommitted

        public boolean isInvalidCommitted()
        Tests if the invalid data is committed to datasource.
        Specified by:
        isInvalidCommitted in interface BufferedValidatable
        See Also:
        BufferedValidatable#isInvalidCommitted()

      • setInvalidCommitted

        public void setInvalidCommitted​(boolean isCommitted)
        Sets if the invalid data should be committed to datasource.
        Specified by:
        setInvalidCommitted in interface BufferedValidatable
        See Also:
        BufferedValidatable#setInvalidCommitted(boolean)

      • discard

        public void discard()
             throws Buffered.SourceException
        Description copied from interface: Buffered
        Discards all changes since last commit. The object updates its value from the data source.
        Specified by:
        discard in interface Buffered
        Throws:
        Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

      • isModified

        public boolean isModified()
        Description copied from interface: Buffered
        Tests if the value stored in the object has been modified since it was last updated from the data source.
        Specified by:
        isModified in interface Buffered
        Returns:
        true if the value in the object has been modified since the last data source update, false if not.

      • setBuffered

        public void setBuffered​(boolean buffered)
        Sets the buffered mode of this Field.

        When the field is in buffered mode, changes will not be committed to the property data source until commit() is called.

        Setting buffered mode from true to false will commit any pending changes.

        Specified by:
        setBuffered in interface Buffered
        Parameters:
        buffered - true if buffered mode should be turned on, false otherwise
        Since:
        7.0.0

      • isBuffered

        public boolean isBuffered()
        Checks the buffered mode of this Field.
        Specified by:
        isBuffered in interface Buffered
        Returns:
        true if buffered mode is on, false otherwise

      • toString

        @Deprecated
public String toString()
        Deprecated.
        As of 7.0. Use getValue() to get the value of the field, getConvertedValue() to get the field value converted to the data model type or getPropertyDataSource() .getValue() to get the value of the data source.
        Returns a string representation of this object. The returned string representation depends on if the legacy Property toString mode is enabled or disabled.

        If legacy Property toString mode is enabled, returns the value of this Field converted to a String.

        If legacy Property toString mode is disabled, the string representation has no special meaning

        Overrides:
        toString in class Object
        Returns:
        A string representation of the value value stored in the Property or a string representation of the Property object.
        See Also:
        LegacyPropertyHelper.isLegacyToStringEnabled()

      • getValue

        public T getValue()
        Gets the current value of the field.

        This is the visible, modified and possible invalid value the user have entered to the field.

        Note that the object returned is compatible with getType(). For example, if the type is String, this returns Strings even when the underlying datasource is of some other type. In order to access the converted value, use getConvertedValue() and to access the value of the property data source, use Property.getValue() for the property data source.

        Since Vaadin 7.0, no implicit conversions between other data types and String are performed, but a converter is used if set.

        Specified by:
        getValue in interface Property<T>
        Returns:
        the current value of the field.

      • getPropertyDataSource

        public Property getPropertyDataSource()
        Gets the current data source of the field, if any.
        Specified by:
        getPropertyDataSource in interface Property.Viewer
        Returns:
        the current data source as a Property, or null if none defined.

      • setPropertyDataSource

        public void setPropertyDataSource​(Property newDataSource)

        Sets the specified Property as the data source for the field. All uncommitted changes are replaced with a value from the new data source.

        If the datasource has any validators, the same validators are added to the field. Because the default behavior of the field is to allow invalid values, but not to allow committing them, this only adds visual error messages to fields and do not allow committing them as long as the value is invalid. After the value is valid, the error message is not shown and the commit can be done normally.

        If the data source implements Property.ValueChangeNotifier and/or Property.ReadOnlyStatusChangeNotifier, the field registers itself as a listener and updates itself according to the events it receives. To avoid memory leaks caused by references to a field no longer in use, the listener registrations are removed on detach and re-added on attach.

        Note: before 6.5 we actually called discard() method in the beginning of the method. This was removed to simplify implementation, avoid excess calls to backing property and to avoid odd value change events that were previously fired (developer expects 0-1 value change events if this method is called). Some complex field implementations might now need to override this method to do housekeeping similar to discard().

        Specified by:
        setPropertyDataSource in interface Property.Viewer
        Parameters:
        newDataSource - the new data source Property.

      • setConverter

        public void setConverter​(Class<?> datamodelType)
        Retrieves a converter for the field from the converter factory defined for the application. Clears the converter if no application reference is available or if the factory returns null.
        Parameters:
        datamodelType - The type of the data model that we want to be able to convert from

      • getModelType

        protected Class<?> getModelType()
        Retrieves the type of the currently used data model. If the field has no data source then the model type of the converter is used.
        Returns:
        The type of the currently used data model or null if no data source or converter is set.
        Since:
        7.1

      • getConversionError

        protected String getConversionError​(Class<?> dataSourceType,
                                    Converter.ConversionException e)
        Returns the conversion error with {0} replaced by the data source type and {1} replaced by the exception (localized) message.
        Parameters:
        dataSourceType - the type of the data source
        e - a conversion exception which can provide additional information
        Returns:
        The value conversion error string with parameters replaced.
        Since:
        7.1

      • getConvertedValue

        public Object getConvertedValue()
        Returns the current value (as returned by getValue()) converted to the data source type.

        This returns the same as getValue() if no converter has been set. The value is not necessarily the same as the data source value e.g. if the field is in buffered mode and has been modified.

        Returns:
        The converted value that is compatible with the data source type

      • setConvertedValue

        public void setConvertedValue​(Object value)
        Sets the value of the field using a value of the data source type. The value given is converted to the field type and then assigned to the field. This will update the property data source in the same way as when setValue(Object) is called.
        Parameters:
        value - The value to set. Must be the same type as the data source.

      • addValidator

        public void addValidator​(Validator validator)
        Adds a new validator for the field's value. All validators added to a field are checked each time the its value changes.
        Specified by:
        addValidator in interface Validatable
        Parameters:
        validator - the new validator to be added.

      • getValidators

        public Collection<Validator> getValidators()
        Gets the validators of the field.
        Specified by:
        getValidators in interface Validatable
        Returns:
        An unmodifiable collection that holds all validators for the field.

      • removeValidator

        public void removeValidator​(Validator validator)
        Removes the validator from the field.
        Specified by:
        removeValidator in interface Validatable
        Parameters:
        validator - the validator to remove.

      • removeAllValidators

        public void removeAllValidators()
        Removes all validators from the field.
        Specified by:
        removeAllValidators in interface Validatable

      • isValid

        public boolean isValid()
        Tests the current value against registered validators if the field is not empty. If the field is empty it is considered valid if it is not required and invalid otherwise. Validators are never checked for empty fields. In most cases, validate() should be used instead of isValid() to also get the error message.
        Specified by:
        isValid in interface Validatable
        Returns:
        true if all registered validators claim that the current value is valid or if the field is empty and not required, false otherwise.

      • validate

        protected void validate​(T fieldValue)
                 throws Validator.InvalidValueException
        Validates that the given value pass the validators for the field.

        This method does not check the requiredness of the field.

        Parameters:
        fieldValue - The value to check
        Throws:
        Validator.InvalidValueException - if one or several validators fail

      • isInvalidAllowed

        public boolean isInvalidAllowed()
        Fields allow invalid values by default. In most cases this is wanted, because the field otherwise visually forget the user input immediately.
        Specified by:
        isInvalidAllowed in interface Validatable
        Returns:
        true iff the invalid values are allowed.
        See Also:
        Validatable.isInvalidAllowed()

      • setInvalidAllowed

        public void setInvalidAllowed​(boolean invalidAllowed)
                       throws UnsupportedOperationException
        Fields allow invalid values by default. In most cases this is wanted, because the field otherwise visually forget the user input immediately.

        In common setting where the user wants to assure the correctness of the datasource, but allow temporarily invalid contents in the field, the user should add the validators to datasource, that should not allow invalid values. The validators are automatically copied to the field when the datasource is set.

        Specified by:
        setInvalidAllowed in interface Validatable
        Throws:
        UnsupportedOperationException - if the setInvalidAllowed is not supported.
        See Also:
        Validatable.setInvalidAllowed(boolean)

      • getErrorMessage

        public ErrorMessage getErrorMessage()
        Error messages shown by the fields are composites of the error message thrown by the superclasses (that is the component error message), validation errors and buffered source errors.
        Overrides:
        getErrorMessage in class AbstractComponent
        Returns:
        ErrorMessage containing the description of the error state of the component or null, if the component contains no errors. Extending classes should override this method if they support other error message types such as validation errors or buffering errors. The returned error message contains information about all the errors.
        See Also:
        AbstractComponent.getErrorMessage()

      • fireValueChange

        protected void fireValueChange​(boolean repaintIsNotNeeded)
        Emits the value change event. The value contained in the field is validated before the event is created.

      • fireReadOnlyStatusChange

        protected void fireReadOnlyStatusChange()
        Emits the read-only status change event. The value contained in the field is validated before the event is created.

      • valueChange

        public void valueChange​(Property.ValueChangeEvent event)
        This method listens to data source value changes and passes the changes forwards. Changes are not forwarded to the listeners of the field during internal operations of the field to avoid duplicate notifications.
        Specified by:
        valueChange in interface Property.ValueChangeListener
        Parameters:
        event - the value change event telling the data source contents have changed.

      • setTabIndex

        public void setTabIndex​(int tabIndex)
        Description copied from interface: Component.Focusable
        Sets the tabulator index of the Focusable component. The tab index property is used to specify the order in which the fields are focused when the user presses the Tab key. Components with a defined tab index are focused sequentially first, and then the components with no tab index. 
         Form loginBox = new Form();
 loginBox.setCaption("Login");
 layout.addComponent(loginBox);

 // Create the first field which will be focused
 TextField username = new TextField("User name");
 loginBox.addField("username", username);

 // Set focus to the user name
 username.focus();

 TextField password = new TextField("Password");
 loginBox.addField("password", password);

 Button login = new Button("Login");
 loginBox.getFooter().addComponent(login);

 // An additional component which natural focus order would
 // be after the button.
 CheckBox remember = new CheckBox("Remember me");
 loginBox.getFooter().addComponent(remember);

 username.setTabIndex(1);
 password.setTabIndex(2);
 remember.setTabIndex(3); // Different than natural place
 login.setTabIndex(4);

        After all focusable user interface components are done, the browser can begin again from the component with the smallest tab index, or it can take the focus out of the page, for example, to the location bar.

        If the tab index is not set (is set to zero), the default tab order is used. The order is somewhat browser-dependent, but generally follows the HTML structure of the page.

        A negative value means that the component is completely removed from the tabulation order and can not be reached by pressing the Tab key at all.

        Specified by:
        setTabIndex in interface Component.Focusable
        Parameters:
        tabIndex - the tab order of this component. Indexes usually start from 1. Zero means that default tab order should be used. A negative value means that the field should not be included in the tabbing sequence.
        See Also:
        Component.Focusable.getTabIndex()

      • getInternalValue

        protected T getInternalValue()
        Returns the internal field value, which might not match the data source value e.g. if the field has been modified and is not in write-through mode. This method can be overridden by subclasses together with setInternalValue(Object) to compute internal field value at runtime. When doing so, typically also isModified() needs to be overridden and care should be taken in the management of the empty state and buffering support.
        Returns:
        internal field value

      • setInternalValue

        protected void setInternalValue​(T newValue)
        Sets the internal field value. This is purely used by AbstractField to change the internal Field value. It does not trigger valuechange events. It can be overridden by the inheriting classes to update all dependent variables. Subclasses can also override getInternalValue() if necessary.
        Parameters:
        newValue - the new value to be set.

      • setLocale

        public void setLocale​(Locale locale)
        Description copied from class: AbstractComponent
        Sets the locale of this component. 
         // Component for which the locale is meaningful
 InlineDateField date = new InlineDateField("Datum");

 // German language specified with ISO 639-1 language
 // code and ISO 3166-1 alpha-2 country code.
 date.setLocale(new Locale("de", "DE"));

 date.setResolution(DateField.RESOLUTION_DAY);
 layout.addComponent(date);
        Overrides:
        setLocale in class AbstractComponent
        Parameters:
        locale - the locale to become this component's locale.

      • isRequired

        public boolean isRequired()
        Is this field required. Required fields must filled by the user. If the field is required, it is visually indicated in the user interface. Furthermore, setting field to be required implicitly adds "non-empty" validator and thus isValid() == false or any isEmpty() fields. In those cases validation errors are not painted as it is obvious that the user must fill in the required fields. On the other hand, for the non-required fields isValid() == true if the field isEmpty() regardless of any attached validators.
        Specified by:
        isRequired in interface Field<T>
        Returns:
        true if the field is required, otherwise false.

      • setRequired

        public void setRequired​(boolean required)
        Sets the field required. Required fields must filled by the user. If the field is required, it is visually indicated in the user interface. Furthermore, setting field to be required implicitly adds "non-empty" validator and thus isValid() == false or any isEmpty() fields. In those cases validation errors are not painted as it is obvious that the user must fill in the required fields. On the other hand, for the non-required fields isValid() == true if the field isEmpty() regardless of any attached validators.
        Specified by:
        setRequired in interface Field<T>
        Parameters:
        required - Is the field required.

      • setRequiredError

        public void setRequiredError​(String requiredMessage)
        Set the error that is show if this field is required, but empty. When setting requiredMessage to be "" or null, no error pop-up or exclamation mark is shown for a empty required field. This faults to "". Even in those cases isValid() returns false for empty required fields.
        Specified by:
        setRequiredError in interface Field<T>
        Parameters:
        requiredMessage - Message to be shown when this field is required, but empty.

      • getRequiredError

        public String getRequiredError()
        Description copied from interface: Field
        Gets the error message that is to be displayed if a required field is empty.
        Specified by:
        getRequiredError in interface Field<T>
        Returns:
        Error message.

      • getConversionError

        public String getConversionError()
        Gets the error that is shown if the field value cannot be converted to the data source type.
        Returns:
        The error that is shown if conversion of the field value fails

      • setConversionError

        public void setConversionError​(String valueConversionError)
        Sets the error that is shown if the field value cannot be converted to the data source type. If {0} is present in the message, it will be replaced by the simple name of the data source type. If {1} is present in the message, it will be replaced by the ConversionException message.
        Parameters:
        valueConversionError - Message to be shown when conversion of the value fails

      • isEmpty

        public boolean isEmpty()
        Description copied from interface: Field
        Is the field empty? In general, "empty" state is same as null. As an exception, TextField also treats empty string as "empty".
        Specified by:
        isEmpty in interface Field<T>
        Returns:
        true if the field is empty, false otherwise

      • clear

        public void clear()
        Description copied from interface: Field
        Clears the value of the field.

        The field value is typically reset to the initial value of the field. Calling Field.isEmpty() on a cleared field must always returns true.

        Specified by:
        clear in interface Field<T>

      • isValidationVisible

        public boolean isValidationVisible()
        Is automatic, visible validation enabled? If automatic validation is enabled, any validators connected to this component are evaluated while painting the component and potential error messages are sent to client. If the automatic validation is turned off, isValid() and validate() methods still work, but one must show the validation in their own code.
        Returns:
        True, if automatic validation is enabled.

      • setValidationVisible

        public void setValidationVisible​(boolean validateAutomatically)
        Enable or disable automatic, visible validation. If automatic validation is enabled, any validators connected to this component are evaluated while painting the component and potential error messages are sent to client. If the automatic validation is turned off, isValid() and validate() methods still work, but one must show the validation in their own code.
        Parameters:
        validateAutomatically - True, if automatic validation is enabled.

      • setCurrentBufferedSourceException

        public void setCurrentBufferedSourceException​(Buffered.SourceException currentBufferedSourceException)
        Sets the current buffered source exception.
        Parameters:
        currentBufferedSourceException -

      • getCurrentBufferedSourceException

        protected Buffered.SourceException getCurrentBufferedSourceException()
        Gets the current buffered source exception.
        Returns:
        The current source exception

      • getConverter

        public Converter<T,​Object> getConverter()
        Gets the converter used to convert the property data source value to the field value.
        Returns:
        The converter or null if none is set.

      • setConverter

        public void setConverter​(Converter<T,​?> converter)
        Sets the converter used to convert the field value to property data source type. The converter must have a presentation type that matches the field type.
        Parameters:
        converter - The new converter to use.

      • getState

        protected AbstractFieldState getState()
        Description copied from class: AbstractComponent
        Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().
        Overrides:
        getState in class AbstractComponent
        Returns:
        updated component shared state

      • beforeClientResponse

        public void beforeClientResponse​(boolean initial)
        Description copied from interface: ClientConnector
        Called before the shared state and RPC invocations are sent to the client. Gives the connector an opportunity to set computed/dynamic state values or to invoke last minute RPC methods depending on other component features.
        Specified by:
        beforeClientResponse in interface ClientConnector
        Overrides:
        beforeClientResponse in class AbstractComponent
        Parameters:
        initial - true if the client-side connector will be created and initialized after this method has been invoked. false if there is already an initialized client-side connector.

      • isImmediate

        public boolean isImmediate()
        Returns the immediate mode of the component.

        Certain operations such as adding a value change listener will set the component into immediate mode if AbstractComponent.setImmediate(boolean) has not been explicitly called with false.

        Fields are automatically set to immediate if validators have been added.

        Overrides:
        isImmediate in class AbstractComponent
        Returns:
        true if the component is in immediate mode (explicitly or implicitly set), false if the component if not in immediate mode

      • readDesign

        public void readDesign​(org.jsoup.nodes.Element design,
                       DesignContext designContext)
        Description copied from interface: Component
        Reads the component state from the given design.

        The component is responsible not only for updating its own state but also for ensuring that its children update their state based on the design.

        It is assumed that the component is in its default state when this method is called. Reading should only take into consideration attributes specified in the design and not reset any unspecified attributes to their defaults.

        This method must not modify the design.

        Specified by:
        readDesign in interface Component
        Overrides:
        readDesign in class AbstractComponent
        Parameters:
        design - The element to obtain the state from
        designContext - The DesignContext instance used for parsing the design

      • writeDesign

        public void writeDesign​(org.jsoup.nodes.Element design,
                        DesignContext designContext)
        Description copied from interface: Component
        Writes the component state to the given design.

        The component is responsible not only for writing its own state but also for ensuring that its children write their state to the design.

        This method must not modify the component state.

        Specified by:
        writeDesign in interface Component
        Overrides:
        writeDesign in class AbstractComponent
        Parameters:
        design - The element to write the component state to. Any previous attributes or child nodes are not cleared.
        designContext - The DesignContext instance used for writing the design