From aeecf9ecac54c4e03bef37be987b6ef13a30407d Mon Sep 17 00:00:00 2001
From: Damien Arrachequesne <damien.arrachequesne@gmail.com>
Date: Wed, 16 Dec 2020 01:55:30 +0100
Subject: [PATCH] docs: add "emitting and listening to events" pages

Imported from the javascript documentation:

- https://socket.io/docs/v3/emitting-events/
- https://socket.io/docs/v3/listening-to-events/
---
 src/site/markdown/emitting_events.md     | 105 +++++++++++++++++++++++
 src/site/markdown/listening_to_events.md |  71 +++++++++++++++
 src/site/site.xml                        |   2 +
 3 files changed, 178 insertions(+)
 create mode 100644 src/site/markdown/emitting_events.md
 create mode 100644 src/site/markdown/listening_to_events.md

diff --git a/src/site/markdown/emitting_events.md b/src/site/markdown/emitting_events.md
new file mode 100644
index 0000000..fce3109
--- /dev/null
+++ b/src/site/markdown/emitting_events.md
@@ -0,0 +1,105 @@
+# Emitting events
+
+See also: https://socket.io/docs/v3/emitting-events/
+
+**Table of content**
+
+<!-- MACRO{toc} -->
+
+There are several ways to send events between the server and the client.
+
+## Basic emit
+
+The Socket.IO API is inspired from the Node.js [EventEmitter](https://nodejs.org/docs/latest/api/events.html#events_events):
+
+*Server*
+
+```js
+io.on("connection", (socket) => {
+  socket.emit("hello", "world");
+});
+```
+
+*Client*
+
+```java
+socket.on("hello", new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        System.out.println(args[0]); // world
+    }
+});
+```
+
+This also works in the other direction:
+
+*Server*
+
+```js
+io.on("connection", (socket) => {
+  socket.on("hello", (arg) => {
+    console.log(arg); // world
+  });
+});
+```
+
+*Client*
+
+```java
+socket.emit("hello", "world");
+```
+
+You can send any number of arguments, and all serializable datastructures are supported, including binary objects like [Buffer](https://nodejs.org/docs/latest/api/buffer.html#buffer_buffer) or [TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray).
+
+*Server*
+
+```js
+io.on("connection", (socket) => {
+  socket.on("hello", (...args) => {
+    console.log(args); // [ 1, '2', <Buffer 61 62 63>, { test: '42' } ]
+  });
+});
+```
+
+*Client*
+
+```java
+byte[] buffer = "abc".getBytes(StandardCharsets.UTF_8);
+JSONObject object = new JSONObject();
+object.put("test", "42");
+
+socket.emit("hello", 1, "2", bytes, object);
+```
+
+## Acknowledgements
+
+Events are great, but in some cases you may want a more classic request-response API. In Socket.IO, this feature is named acknowledgements.
+
+You can add a callback as the last argument of the `emit()`, and this callback will be called once the other side acknowledges the event:
+
+*Server*
+
+```js
+io.on("connection", (socket) => {
+  socket.on("update item", (arg1, arg2, callback) => {
+    console.log(arg1); // 1
+    console.log(arg2); // { name: "updated" }
+    callback({
+      status: "ok"
+    });
+  });
+});
+```
+
+*Client*
+
+```java
+socket.emit("update item", 1, new JSONObject(singletonMap("name", "updated")), new Ack() {
+    @Override
+    public void call(Object... args) {
+        JSONObject response = (JSONObject) args[0];
+        System.out.println(response.getString("status")); // "ok"
+    }
+});
+```
+
diff --git a/src/site/markdown/listening_to_events.md b/src/site/markdown/listening_to_events.md
new file mode 100644
index 0000000..6caf0a6
--- /dev/null
+++ b/src/site/markdown/listening_to_events.md
@@ -0,0 +1,71 @@
+# Listening to events
+
+See also: https://socket.io/docs/v3/listening-to-events/
+
+**Table of content**
+
+<!-- MACRO{toc} -->
+
+There are several ways to handle events that are transmitted between the server and the client.
+
+## EventEmitter methods
+
+### socket.on(eventName, listener)
+
+Adds the *listener* function to the end of the listeners array for the event named *eventName*.
+
+```java
+socket.on("details", new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        // ...
+    }
+});
+```
+
+### socket.once(eventName, listener)
+
+Adds a **one-time** *listener* function for the event named *eventName*.
+
+```java
+socket.once("details", new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        // ...
+    }
+});
+```
+
+### socket.off(eventName, listener)
+
+Removes the specified *listener* from the listener array for the event named *eventName*.
+
+```java
+Emitter.Listener listener = new Emitter.Listener() {
+    @Override
+    public void call(Object... args) {
+        calls.add("two");
+    }
+};
+
+socket.on("details", listener);
+
+// and then later...
+socket.off("details", listener);
+```
+
+### socket.off(eventName)
+
+Removes all listeners for the specific *eventName*.
+
+```java
+socket.off("details");
+```
+
+### socket.off()
+
+Removes all listeners (for any event).
+
+```java
+socket.off();
+```
diff --git a/src/site/site.xml b/src/site/site.xml
index dc20b85..fbd329e 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -26,6 +26,8 @@
         <menu name="Overview">
             <item name="Installation" href="./installation.html"/>
             <item name="Usage" href="./usage.html"/>
+            <item name="Emitting events" href="./emitting_events.html"/>
+            <item name="Listening to events" href="./listening_to_events.html"/>
             <item name="Migrating from 1.x" href="./migrating_from_1_x.html"/>
         </menu>