Kava Pava Gava Tava Nava Zava Java

Vaadin arose me much of interests.

(1) It uses GWT on browser side, good choice!
(2) Writting web application very much like writting a desktop application. That means you work with components - button, tree, table, panel, layout, not HTML tags. Deal with events and listeners, not javascripts and HTML forms.
(3) Contrast to GWT, it's a server end solution. Events from GUI rendered at browser side by GWT are sent to server, the counterpart of those browser-side components receive the events and propogate those events at server side. This means processing of these events - validation, update business entities and database - are handled at server side, therefore avoid the developer needs to deal with client - server communication and security concerns.

This article examine what's found in com.vaadin.data pacakge - the data source model for vaadin - and provide a summary as follows. It also examine the relationship between data source and some UI classes.

In short:

(1) com.vaadin.data.Property - correspond to a value, a property in a pojo object, a data field in a row of data from database, etc.

Property has a type (get/setType(Class<?>), can get/setValue (Object), can set/isReadOnly(),

Property has embeded interface Editor and Viewer which can use a Property as datasource. It may throw ConversionException when the value provided to it cannot be converted to the type of the Property.

Classes implemented Property
        UI side - Property has a sub-interface Field. Field is a property. CheckBox, DateField, Tree, name just a few.
        Data side - ObjectProperty map to an object, MethodProperty proxy on a pair of getter and setter methods. 
        Proxy - PropertyFormatter proxy between UI and datasource to convert between them.

Many classes implementing Property also implements Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeNotifier, to propogate property events.

(2) Property.Viewer, Property.Editor, Field

Property.Viewer <- Property.Editor <- Field <- CheckBox, Tree, TextField, etc.

Property.Viewer - this interface only has get/setDataSource(Property) to receive / provide property data source

Property.Editor - this interface adds nothing to Property.Viewer, only as a marker that implementors can also edit the data source.

Field extends Property.Editor, therefore all fields are a property editor. So all fields can have another property as its data source. Mind that fields are themselves properties.

(3) Field - Field is top-level interface for editable UI, implements the whole lots of vaadin interfaces. Field is both Property and Property.Editor, and Component. See below what Field is.

Buffered - interface to commit() or discard() changes, support set/isReadThrough() and set/isWriteThrough() modes. Mind the warnings about the read-through and write-through.

Validable - interface for add/removeValidators(), test with validate() which may throw exception or isValid() with returns boolean,  the object may accept invalid value, somehow, so set()/is() InvalidAllowed.

BufferedValidable - combine the behavior of buffering and validation together, is/setInvalidCommitted(), default false.

Paintable - as name suggested, objects know how to output themselves to UIDL stream describing how to paint itself to browser. It seems that this interface is quite low-level, concern only component developers and not application developers. Provides add/removeListener(Paintable.RepaintRequestListener), paint(PaintTarget), requestRepaint(), requestRepaintRequests(), set/getDebugId().

VariableOwner - Listener interface for UI variable changes. So called "variables" are basic unit which user send changes to server. Provides isEnabled(), isImmediate(), changeVariables(Object source, Map variables), the last one "called when one or more variables handled by the implementing class are changed". Therefore, the last one is i) not called by application user ii) should be implemented by implementing classes

Component - a Paintable and VariableOwner, the top-level UI component interface. Provides:
        relationships with other UI parts:
                getApplication(), get/setParent(), get/setWindow(), 
        visual elements: 
                get/add/removeStyleName(), get/setCaption(), get/setIcon, get/setLocale(), 
        behaviors:
                get/setEnabled(), set/isReadOnly(), is/setVisible()
        events:
                add/removeListener(Component.Listener), 
        call-backs from framework:
                attach() before painted, detach() when detached from window

Component.Focusable - focus(), get/setTabIndex()

java.util.EventListener - a tagging interface

Property - Field is a property

Property.Editor - Field is a property editor, it has a data source.

Property.ValueChangeListener - can be notified of value change event (valueChange()) from other property

Property.ValueChangeNotifier - will notify others of value change event (addListener(), removeListener())

Sizable - something can be resized, provides:
    get/set dimensions on Hight/Width/Full/Undefined
    get/set HightUnits/WidthUnits
    static int UNIT_CM, PIXELS, etc.

(4) com.vaadin.data.Item - correspond to an item, a pojo object with a set of properties, a row of data with fields, etc.

Item interface manages a collection of properties identified by ids. add/get/removeItemProperty(Object id, Property property)

Item contains interfaces Item.Viewer and Item.Editor, both are able to use an Item as datasource to edit or view the data.
Item.Viewer provides get/setItemDataSource(), Item.Editor extends Item.Viewer, only a marker that the item can be edited.
Form is the only class implements Item.Editor and / or Item.Viewer. Form is at the same time a Field, therefore Property.Editor.

Classes implementing Item interface: 
        datasource implementations: 
            Item <- PropertysetItem <- BeanItem
            Item <- FilesystemContainer.FileItem
        UI component holding Item: Form

class PropertysetItem is the concrete implementation of Item interface and provides the follows:

        add/removeListener() - add / remove Item.PropertySetChangeListener

class BeanItem extends PropertysetItem so it can wrap around any Java Bean.

(5) com.vaadin.data.Container - correspond to a collection of items, a database table, etc., identified by id

First, Container can hold items identified by id, add/get/removeItem(), size(), boolean containsItem(itemId).

Items contained in Container have properties. add/removeContainerProperty() can manage those properties. getContainerPropertyIds() obtain current property ids.

Container interface further holds Container.Viewer and Container.Editor interfaces.

Container.Viewer only define methods to set Container as datasource - get/setContainerDataSource()
Container.Editor extends Container.Viewer and provides no additional methods, just a marker.
Container.Viewer is implemented by various UI controls such as ComboBox, ListSelect, OptionGroup, Select, Table, Tree, etc.
Container.Editor has no implementation at this time.

Sub-interfaces - Container.Filterable, Container.Hierarchical, Container.Indexed, Container.Ordered, Container.Sortable provides further interfaces for special type of containers.

Classes implementing Container includes:
    datasource containers: BeanItemContainer, QueryContainer (JDBC), FilesystemContainer...
    UI components holding data: Select, Table, Tree... They mostly also implement Container.Viewer, but not Container.Editor
    container with special feature: HierarchicalContainer, IndexedContainer
    wrapper containers: ContainerHierarchicalWrapper, ContainerOrderedWrapper