Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Integrating the Two Sides with a Connector

A client-side widget is integrated with a server-side component with a connector. A connector is a client-side class that communicates changes to the widget state and events to the server-side.

A connector normally gets the state of the server-side component by the shared state, described later in "Shared State".

A Basic Connector

The basic tasks of a connector is to hook up to the widget and handle events from user interaction and changes received from the server. A connector also has a number of routine infrastructure methods which need to be implemented.

public class MyComponentConnector
        extends AbstractComponentConnector {

    public MyComponentWidget getWidget() {
        return (MyComponentWidget) super.getWidget();

    public MyComponentState getState() {
        return (MyComponentState) super.getState();

    public void onStateChanged(StateChangeEvent stateChangeEvent)

        // Do something useful
        final String text = getState().text;

Here, we handled state change with the crude onStateChanged() method that is called when any of the state properties is changed. A finer and simpler handling is achieved by using the @OnStateChange annotation on a handler method for each property, or by @DelegateToWidget on a shared state property, as described later in "Shared State".

Communication with the Server-Side

The main task of a connector is to communicate user interaction with the widget to the server-side and receive state changes from the server-side and relay them to the widget.

Server-to-client communication is normally done using a shared state, as described in "Shared State", as well as RPC calls. The serialization of the state data is handled completely transparently.

Once the client-side engine receives the changes from the server, it reacts to them by creating and notifying connectors that in turn manage widgets. This is described in "Client-Side Processing Phases" in more detail.

For client-to-server communication, a connector can make remote procedure calls (RPC) to the server-side. Also, the server-side component can make RPC calls to the connector. For a thorough description of the RPC mechanism, refer to "RPC Calls Between Client- and Server-Side".