RPC Calls Between Client- and Server-Side

Vaadin supports making Remote Procedure Calls (RPC) between a server-side component and its client-side widget counterpart. RPC calls are normally used for communicating stateless events, such as button clicks or other user interaction, in contrast to changing the shared state. Either party can make an RPC call to the other side. When a client-side widget makes a call, a server request is made. Calls made from the server-side to the client-side are communicated in the response of the server request during which the call was made.

If you use Eclipse and enable the “Full-Fledged” widget in the New Vaadin Widget wizard, it automatically creates a component with an RPC stub.

RPC Calls to the Server-Side

RPC calls from the client-side to the server-side are made through an RPC interface that extends the ServerRpc interface. A server RPC interface simply defines any methods that can be called through the interface.

For example:

Java

public interface MyComponentServerRpc extends ServerRpc {
    public void clicked(String buttonName);
}

The above example defines a single clicked() RPC call, which takes a String object as the parameter.

You can pass the most common standard Java types, such as primitive and boxed primitive types, String, and arrays and some collections ( List, Set, and Map) of the supported types. Also the Vaadin Connector and some special internal types can be passed.

An RPC method must return void - the widget set compiler should complain if it doesn’t.

Making a Call

Before making a call, you need to instantiate the server RPC object with RpcProxy.create(). This is usually done transparently by using getRpcProxy(). After that, you can make calls through the server RPC interface that you defined, for example as follows:

Java

@Connect(MyComponent.class)
public class MyComponentConnector
       extends AbstractComponentConnector {
    public MyComponentConnector() {
        getWidget().addClickHandler(new ClickHandler() {
            public void onClick(ClickEvent event) {
                final MouseEventDetails mouseDetails =
                     MouseEventDetailsBuilder
                         .buildMouseEventDetails(
                                 event.getNativeEvent(),
                                 getWidget().getElement());
                MyComponentServerRpc rpc =
                    getRpcProxy(MyComponentServerRpc.class);
                // Make the call
                rpc.clicked(mouseDetails.getButtonName());
            }
        });
    }
}

Handling a Call

RPC calls are handled in a server-side implementation of the server RPC interface. The call and its parameters are serialized and passed to the server in an RPC request transparently.

Java

public class MyComponent extends AbstractComponent {
    private MyComponentServerRpc rpc =
    new MyComponentServerRpc() {
        private int clickCount = 0;
        public void clicked(String buttonName) {
            Notification.show("Clicked " + buttonName);
        }
    };
    public MyComponent() {
        ...
        registerRpc(rpc);
    }
}