Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 112 insertions, 0 deletions

diff --git a/documentation/gwt/gwt-rpc.asciidoc b/documentation/gwt/gwt-rpc.asciidoc
new file mode 100644
index 0000000000..b67773dbfe
--- /dev/null
+++ b/documentation/gwt/gwt-rpc.asciidoc
@@ -0,0 +1,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]#clicks()# RPC call, which takes
+a [classname]#MouseEventDetails# 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()#. 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);
+    }
+}
+----
+
+
+
+
+