From 73757635ed01889079bce4719689fce8b0360457 Mon Sep 17 00:00:00 2001
From: Damien Arrachequesne <damien.arrachequesne@gmail.com>
Date: Fri, 8 Jul 2022 09:26:40 +0200
Subject: [PATCH] docs: multiplexing

Related: https://github.com/socketio/socket.io-client-java/pull/716
---
 src/site/markdown/initialization.md | 49 +++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/src/site/markdown/initialization.md b/src/site/markdown/initialization.md
index 717ad63..0311b39 100644
--- a/src/site/markdown/initialization.md
+++ b/src/site/markdown/initialization.md
@@ -475,3 +475,52 @@ options.webSocketFactory = okHttpClient;
 
 Socket socket = IO.socket(URI.create("https://example.com"), options);
 ```
+
+## Multiplexing
+
+The Java client does support multiplexing: this allows to split the logic of your application into distinct modules, while using one single WebSocket connection to the server.
+
+Reference: https://socket.io/docs/v4/namespaces/
+
+```java
+Socket socket = IO.socket(URI.create("https://example.com")); // the main namespace
+Socket productSocket = IO.socket(URI.create("https://example.com/product")); // the "product" namespace
+Socket orderSocket = IO.socket(URI.create("https://example.com/order")); // the "order" namespace
+
+// all 3 sockets share the same Manager
+System.out.println(socket.io() == productSocket.io()); // true
+System.out.println(socket.io() == orderSocket.io()); // true
+```
+
+Please note that multiplexing will be disabled in the following cases:
+
+- multiple creation for the same namespace
+
+```java
+Socket socket = IO.socket(URI.create("https://example.com"));
+Socket socket2 = IO.socket(URI.create("https://example.com"));
+
+System.out.println(socket.io() == socket2.io()); // false
+```
+
+- different domains
+
+```java
+Socket socket = IO.socket(URI.create("https://first.example.com"));
+Socket socket2 = IO.socket(URI.create("https://second.example.com"));
+
+System.out.println(socket.io() == socket2.io()); // false
+```
+
+- usage of the [forceNew](#forceNew) option
+
+```java
+IO.Options options = IO.Options.builder()
+    .setForceNew(true)
+    .build();
+
+Socket socket = IO.socket(URI.create("https://example.com"));
+Socket socket2 = IO.socket(URI.create("https://example.com/admin"), options);
+
+System.out.println(socket.io() == socket2.io()); // false
+```