Properties

    You can set the value of a property with setValue() and read with getValue().

    In the following, we set and read the property value from a TextField component, which implements the Property interface to allow accessing the field value.

    Java

    See the on-line example.

    Changes in the property value usually fire a ValueChangeEvent, which can be handled with a ValueChangeListener. The event object provides reference to the property with getProperty(). Note that its getValue() method returns the value with Object type, so you need to cast it to the proper type.

    Properties are in themselves unnamed. They are collected in items, which associate the properties with names: the Property Identifiers or PIDs. Items can be further contained in containers and are identified with Item Identifiers or IIDs. In the spreadsheet analogy, Property Identifiers would correspond to column names and Item Identifiers to row names. The identifiers can be arbitrary objects, but must implement the equals(Object) and hashCode() methods so that they can be used in any standard Java Collection.

    The Property interface can be utilized either by implementing the interface or by using some of the built-in property implementations. Vaadin includes a Property interface implementation for arbitrary function pairs and bean properties, with the MethodProperty class, and for simple object properties, with the ObjectProperty class, as described later.

    In addition to the simple components, selection components provide their current selection as the property value. In single selection mode, the property is a single item identifier, while in multiple selection mode it is a set of item identifiers. See the documentation of the selection components for further details.

    Components that can be bound to a property have an internal default data source object, typically a ObjectProperty, which is described later. As all such components are viewers or editors, also described later, so you can rebind a component to any data source with setPropertyDataSource().

    The most important function of the Property as well as of the other data model interfaces is to connect classes implementing the interface directly to editor and viewer classes. This means connecting a data source (model) to a user interface component (views) to allow editing or viewing the data model.

    A property can be bound to a component implementing the Viewer interface with setPropertyDataSource().

    Java

    2. ObjectProperty property =
    3.     new ObjectProperty("Hello", String.class);
    5. // Have a component that implements Viewer
    6. Label viewer = new Label();
    8. // Bind it to the data
    9. viewer.setPropertyDataSource(property);

    You can use the same method in the Editor interface to bind a component that allows editing a particular property type to a property.

    Java

    1. // Have a data model
    2. ObjectProperty property =
    3.     new ObjectProperty("Hello", String.class);
    5. // Have a component that implements Viewer
    6. TextField editor = new TextField("Edit Greeting");
    8. // Bind it to the data
    9. editor.setPropertyDataSource(property);

    As all field components implement the Property interface, you can bind any component implementing the Viewer interface to any field, assuming that the viewer is able the view the object type of the field. Continuing from the above example, we can bind a Label to the TextField value:

    Java

    If a field has validators, as described in , the validators are executed before writing the value to the property data source, or by calling the validate() or commit() for the field.

    Java

    1. // Have a component that implements Viewer interface
    2. final TextField tf = new TextField("Name");
    4. // Have a data model with some data
    5. String myObject = "Hello";
    7. // Wrap it in an ObjectProperty
    8. ObjectProperty property =
    9.     new ObjectProperty(myObject, String.class);
    11. // Bind the property to the component
    12. tf.setPropertyDataSource(property);

    Fields allow editing a certain type, such as a String or Date. The bound property, on the other hand, could have some entirely different type. Conversion between a representation edited by the field and the model defined in the property is handler with a converter that implements the Converter interface.

    Most common type conversions, such as between string and integer, are handled by the default converters. They are created in a converter factory global in the application.

    The setConverter([interfacename]#Converter)# method sets the converter for a field. The method is defined in AbstractField.

    Java

    1. // Have an integer property
    2. final ObjectProperty<Integer> property =
    3.         new ObjectProperty<Integer>(42);
    5. final TextField tf = new TextField("Name");
    7. // Use a converter between String and Integer
    8. tf.setConverter(new StringToIntegerConverter());
    10. // And bind the field
    11. tf.setPropertyDataSource(property);

    The built-in converters are the following:

    In addition, there is a ReverseConverter that takes a converter as a parameter and reverses the conversion direction.

    If a converter already exists for a type, the setConverter([interfacename]#Class)# retrieves the converter for the given type from the converter factory, and then sets it for the field. This method is used implicitly when binding field to a property data source.

    A conversion always occurs between a representation type, edited by the field component, and a model type, that is, the type of the property data source. Converters implement the Converter interface defined in the com.vaadin.data.util.converter package.

    For example, let us assume that we have a simple Complex type for storing complex values.

    Java

    The conversion methods get the locale for the conversion as a parameter.

    If a field does not directly allow editing a property type, a default converter is attempted to create using an application-global converter factory. If you define your own converters that you wish to include in the converter factory, you need to implement one yourself. While you could implement the ConverterFactory interface, it is usually easier to just extend DefaultConverterFactory.

    Java

    1. class MyConverterFactory extends DefaultConverterFactory {
    2.     @Override
    3.     public <PRESENTATION, MODEL> Converter<PRESENTATION, MODEL>
    4.             createConverter(Class<PRESENTATION> presentationType,
    5.                             Class<MODEL> modelType) {
    6.         // Handle one particular type conversion
    7.         if (String.class == presentationType &&
    8.             Complex.class == modelType)
    9.             return (Converter<PRESENTATION, MODEL>)
    10.                    new ComplexConverter();
    12.         // Default to the supertype
    13.         return super.createConverter(presentationType,
    14.                                      modelType);
    15.     }
    16. }
    18. // Use the factory globally in the application
    19. UI.getCurrent().getSession().setConverterFactory(
    20.         new MyConverterFactory());

    Implementation of the Property interface requires defining setters and getters for the value and the read-only mode. Only a getter is needed for the property type, as the type is often fixed in property implementations.

    The following example shows a simple implementation of the Property interface:

    Java

    1. class MyProperty implements Property {
    2.     Integer data     = 0;
    3.     boolean readOnly = false;
    5.     // Return the data type of the model
    6.     public Class<?> getType() {
    7.         return Integer.class;
    8.     }
    10.     public Object getValue() {
    11.         return data;
    12.     }
    14.     // Override the default implementation in Object
    15.     public String toString() {
    17.     }
    19.     public boolean isReadOnly() {
    20.         return readOnly;
    21.     }
    23.     public void setReadOnly(boolean newStatus) {
    24.         readOnly = newStatus;
    25.     }
    27.     public void setValue(Object newValue)
    28.             throws ReadOnlyException, ConversionException {
    29.         if (readOnly)
    30.             throw new ReadOnlyException();
    32.         // Already the same type as the internal representation
    33.         if (newValue instanceof Integer)
    34.             data = (Integer) newValue;
    36.         // Conversion from a string is required
    37.         else if (newValue instanceof String)
    38.             try {
    39.                 data = Integer.parseInt((String) newValue, 16);
    40.             } catch (NumberFormatException e) {
    41.                 throw new ConversionException();
    42.             }
    43.         else
    44.              // Don't know how to convert any other types
    45.             throw new ConversionException();
    47.         // Reverse decode the hexadecimal value
    48.     }
    49. }
    51. // Instantiate the property and set its data
    52. MyProperty property = new MyProperty();
    53. property.setValue(42);

    The implementation example does not notify about changes in the property value or in the read-only mode. You should normally also implement at least the Property.ValueChangeNotifier and Property.ReadOnlyStatusChangeNotifier. See the ObjectProperty class for an example of the implementation.