documentation/gwt/gwt-rpc.asciidoc


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

---
title: RPC Calls Between Client- and Server-Side
order: 6
layout: page
---

[[gwt.rpc]]
= 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.

[[gwt.rpc.server-side]]
== 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 [interfacename]#ServerRpc# interface. A server RPC
interface simply defines any methods that can be called through the interface.

For example:


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

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

You can pass the most common standard Java types, such as primitive and boxed
primitive types, [classname]#String#, and arrays and some collections (
[classname]#List#, [classname]#Set#, and [classname]#Map#) of the supported
types. Also the Vaadin [classname]#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.

[[gwt.rpc.server-side.calling]]
=== Making a Call

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


----
@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());
            }
        });
    }
}
----


[[gwt.rpc.server-side.handling]]
=== 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.


----
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);
    }
}
----