From 857edee9a1c806de4936b37abfa105861e213192 Mon Sep 17 00:00:00 2001
From: Scalbox <info@scalbox.com>
Date: Mon, 5 Jan 2026 16:42:15 +0100
Subject: [PATCH 1/4] example documentation

---
 README.md | 252 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 250 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9dcc414..03f8261 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ It empowers applications with easy integration capabilities with a Rust game ser
 translating internal server details into actionable events.
 
 By interfacing with Rust's native RCON payloads, the library efficiently captures and translates  
-in-game occurrences — such as player connections, chats, combat and more — into events.  
+in-game occurrences — such as player connections, chats, combat, and more — into events.  
 This reactive design allows user code to be promptly informed about player-driven and server-driven actions.
 
 Additionally, Rust RCON manages connection states intelligently, eliminating concerns about  
@@ -101,9 +101,257 @@ Rust RCON offers a plethora of events that give developers a detailed insight in
 - **WsErrorEvent**: Triggered when there's an error in the websocket communication.
 - **WsClosedEvent**: Emitted when the websocket connection is closed, either due to errors or deliberate actions.
 
+<hr>
+
 ## Examples :alembic:
 
-*Coming soon*
+**Difference between classes:** 
+
+```java
+public class DefaultRustRconService {}
+public class DefaultRustRconRouter {}
+public class DefaultRustRconClient {}
+```
+
+<hr>
+
+<h3> DefaultRustRconService </h3>
+
+```java
+public class DefaultRustRconService {}
+```
+
+The `DefaultRustRconService` class is the **operational core** and the main implementation of the connection and management logic for a Rust game server using the RCON protocol.
+
+Here are its main functions:
+
+1. **Component Orchestration**: Acts as a central "hub" that initializes and connects the WebSocket client (`RustWebSocketClient`), the event system (`EventBus`), the communication protocols (`Codec`), and the data mappers (`RustDtoMappers`). It uses the `Lazy` pattern to initialize these components only when necessary.
+2. **Lifecycle Management**: Manages the starting (`start()`) and stopping (`stop()`) of the server connection and the message router.
+3. **Automation (Polling)**: In the `configure()` method, set up scheduled tasks (`ScheduledExecutorService`) that automatically poll the server at regular intervals to keep local data up to date. Specifically:
+   * Server info (every 5 seconds).
+   * Player list (every 3 seconds).
+   * Team list (every 5 minutes).
+4. **State Management**: Maintains the current server state, such as the player list (`rustPlayers`), teams (`rustTeams`), and diagnostics, in memory (via `AtomicReference`), making them accessible to the application without having to make a network request each time.
+5. **API Facade**: Provides high-level methods to access specific functionality, such as player management (`playerManagement()`) or Oxide framework management (`oxideManagement()`).
+
+To use the `DefaultRustRconService` class, you must follow a standard lifecycle: configuration, startup, interaction, and shutdown.
+
+Here are the main steps:
+
+1. Instantiation: Create an instance by passing a `RustRconConfiguration` object with connection details (IP, port, password).
+2. Event Registration (Optional): If you want to react to events (e.g., chat messages, server logs), register your listeners before or after startup.
+3. Startup: Call the `start()` method. This opens the WebSocket connection and starts automatic tasks (polling players, server info, etc.).
+4. Interaction: Use the exposed methods to send commands or read state (e.g., `playerManagement()`, `codec()`, `players()`).
+5. Stoppage: Call `stop()` when the application terminates to close connections and threads.
+
+Here is a practical example of use:
+
+```java
+import com.scalbox.rust.rcon.DefaultRustRconService;
+import com.scalbox.rust.rcon.RustRconConfiguration;
+import com.scalbox.rust.rcon.protocol.dto.RustPlayerDTO;
+
+public class ExampleUsage { 
+
+   public static void main(String[] args) { 
+      // 1. Configuration 
+      RustRconConfiguration config = new RustRconConfiguration( 
+         "127.0.0.1", 
+         28016, 
+         "your_password_rcon"
+      ); 
+      
+      // 2. Instantiation of the service 
+      DefaultRustRconService rconService = new DefaultRustRconService(config); 
+      
+      // (Optional) Enable logging of all RCON traffic to the console
+      rconService.enableRconLogger();
+      
+      // 3. Start connection and background tasks
+      rconService.start();
+      
+      // 4. Interaction: Example of sending a command (banning a player)
+      // Note: playerManagement() offers high-level methods
+      // rconService.playerManagement().ban("steamId", "reason");
+      
+      // 4. Interaction: Read cached data (automatically updated every 3 seconds)
+      System.out.println("Online players: " + rconService.players().size());
+      
+      // 4. Interaction: Send raw command via Codec
+      rconService.codec().send("say Hello Server!");
+      
+      // 5. Stop (usually when the application shuts down)
+      rconService.stop();
+   }
+}
+```
+
+<hr>
+
+<h3> DefaultRustRconRouter </h3>
+
+```java
+public class DefaultRustRconRouter {}
+```
+
+The `DefaultRustRconRouter` class acts as a **transport and correlation layer** between your application and the raw RCON client. While the `Service` (seen previously) handles the high-level logic (players, teams), this `Router` handles the sending and receiving mechanics.
+
+Here's what it does specifically:
+
+1. **Identifier (ID) Management**: The RCON protocol requires each packet sent to have a unique ID to associate the response with the correct request. This class generates these IDs automatically (`identifierGenerator`) using an `AtomicInteger`.
+2. **Request/Response Correlation**: When you call `send()`, the class packages the message in a `RustRconRequest`, sends it, and returns a `CompletableFuture`. This allows the response to be handled asynchronously as soon as it arrives.
+3. **Audit and Logging (Event Bus)**: Using the `handleRconProtocolExchange` method, every time a request is completed (successfully or unsuccessfully), an `RconProtocolExchangeEvent` is published to the `EventBus`. This is essential for logging traffic or for plugins that need to analyze everything that passes "over the wire".
+4. **Client Abstraction**: Hides the connection details of the underlying `RustRconClient`, exposing only methods for sending messages and managing the lifecycle (`start`/`stop`).
+
+### How to use it
+
+Typically, this class is instantiated and managed internally by the `DefaultRustRconService`. However, if you're building a custom implementation or need to send raw commands bypassing the high-level logic, you can use it like this:
+
+1. Dependency Injection: Requires a RustRconClient (the physical connection) and an EventBus (for events).
+2. Lifecycle: You must call start() to connect and stop() to close.
+3. Command Sending: You use the send() method, which accepts a message and (optionally) a mapping function to transform the response.
+
+Here's an example of direct usage:
+
+```java
+import com.google.common.eventbus.EventBus;
+import com.scalbox.rust.rcon.DefaultRustRconRouter;
+import com.scalbox.rust.rcon.RustRconClient; // Hypothetical implementation
+import com.scalbox.rust.rcon.protocol.RustRconMessage;
+
+public class RouterUsageExample {
+
+   public void example(RustRconClient rawClient, EventBus eventBus) {
+      // 1. Instantiation
+      DefaultRustRconRouter router = new DefaultRustRconRouter(rawClient, eventBus);
+      
+      // 2. Starting the underlying connection
+      router.start();
+      
+      // 3. Creating a message (functional wrapper or object)
+      RustRconMessage message = () -> "status";
+      
+      // 4. Asynchronous sending and response handling
+      router.send(message).thenAccept(response -> {
+        System.out.println("Response from server: " + response.getMessage());
+      }).exceptional(ex -> {
+        System.err.println("Error sending: " + ex.getMessage());
+        return null;
+      });
+      
+      // 5. Stop
+      router.stop();
+   }
+}
+```
+
+<hr>
+
+<h3> DefaultRustRconClient </h3>
+
+```java
+public class DefaultRustRconClient {}
+```
+
+The `DefaultRustRconClient` class is the concrete, low-level implementation of the RCON client. It acts as a protocol adapter between the raw WebSocket connection and the Java application logic.
+
+Here are its main functions:
+
+1. **Asynchronous Request/Response Handling**: This component solves the complexity of asynchrony. When you send a command, the server responds at a future time. This class uses a `CompletableFuture` cache to "remember" which request is pending and completes the correct future when the response with the same ID arrives (`onWsMessage`).
+2. **Serialization/Deserialization**: Converts Java objects (`RustRconRequest`) to JSON for sending and converts the JSON received from the WebSocket into Java objects (`RustRconResponse`), using a `JsonMapper`.
+3. **WebSocket Event Handling**: Listens for low-level WebSocket events (`WsOpenedEvent`, `WsMessageEvent`, `WsClosedEvent`) via the `EventBus` and reacts accordingly (e.g., by setting the `isInitialized` flag or publishing an `RconReceivedEvent`).
+4. **Connection Management**: Controls the opening (`connect()`) and controlled closing (`close()`) of the underlying WebSocket connection.
+
+### How to use it
+
+Normally, this class is "hidden" within `DefaultRustRconRouter` or `DefaultRustRconService`. However, if you need to use it directly to manually manage the RCON protocol without the higher-level abstractions, here's how:
+
+1. **Dependencies**: Requires a `RustWebSocketClient` (the physical connection) and an `EventBus`.
+2. **Setup**: Instantiate the class and call `connect()`.
+3. **Send**: Use `send()`, which returns a `CompletableFuture`.
+4. **Closing**: Call `close()` to terminate.
+
+Example of direct usage:
+
+```java
+import com.google.common.eventbus.EventBus;
+import com.scalbox.rust.rcon.DefaultRustRconClient;
+import com.scalbox.rust.rcon.protocol.RustRconRequest;
+import com.scalbox.rust.rcon.ws.RustWebSocketClient; // Hypothetical implementation
+import java.net.URI;
+
+public class ClientUsage {
+
+   public void manualClientUsage() {
+      // 1. Prepare dependencies
+      EventBus eventBus = new EventBus();
+      RustWebSocketClient wsClient = new RustWebSocketClient(URI.create("ws://127.0.0.1:28016/password"), eventBus);
+      
+      // 2. Instantiation
+      DefaultRustRconClient client = new DefaultRustRconClient(wsClient, eventBus);
+      
+      // 3. Connection (register listeners on the EventBus internally)
+      client.connect();
+      
+      // 4. Manual request creation (note: you must manage the ID here if you don't use the Router)
+      RustRconRequest request = new RustRconRequest() {
+        @Override public int getIdentifier() { return 12345; }
+        @Override public String getMessage() { return "status"; }
+      };
+      
+      // 5. Sending and handling the response
+      client.send(request).thenAccept(response -> {
+        System.out.println("Raw Response: " + response.getMessage());
+      });
+      
+      // 6. Closing
+      client.close();
+   }
+}
+```
+
+<hr>
+
+<h3> What should be used between DefaultRustRconService, DefaultRustRconRouter, and DefaultRustRconClient? </h3>
+
+The choice depends on the level of abstraction and control you need for your application. Here's a quick guide to help you decide:
+
+1. **`DefaultRustRconClient`**: This is the lowest level. It only handles the raw socket connection. It's too primitive to handle complex business logic (such as request/response correlation).
+2. **`DefaultRustRconRouter`** (the file you're viewing): This is the communication "engine." As you can see from the code, it manages the `EventBus`, the correlation between requests and responses via IDs (`identifierGenerator`), and returns `CompletableFuture`. It's essential for asynchronous operation, but is intended to be used by a higher level.
+3. **`DefaultRustRconService`**: This is the highest-level abstraction. It typically encapsulates the `Router` and provides ready-made utility methods (e.g., getting the player list, server info, etc.) that you need for the dashboard.
+
+### 1. DefaultRustRconService (Recommended in 95% of cases)
+This is the "turnkey" solution. You should use this class if you're building a bot, a dashboard, or a standard management tool.
+
+* **Why use it:**
+* Automatically manages the connection lifecycle.
+* Performs **automatic polling** (updates player list, server info, team in the background).
+* Maintains a **local cache** of data for quick access without network calls.
+* Offers high-level APIs (e.g., `playerManagement().kick(...)` instead of writing raw commands).
+* **Hierarchy:** Internally, it instantiates and manages both the *Router* and the *Client*.
+
+### 2. DefaultRustRconRouter (Intermediate Level)
+You should use this class if you want lightweight control but aren't interested in the Service's automatic features.
+
+* **Why use it:**
+* You only need to send specific RCON commands and receive the asynchronous response (`CompletableFuture`).
+* You want to avoid the overhead of continuous polling (you don't want the app to ask for the player list every 3 seconds).
+* You want to manually manage when to send the commands.
+* **What it does:** Handles Request-Response correlation (packet ID) and serialization, but doesn't maintain state (no player cache).
+
+### 3. DefaultRustRconClient (Low Level)
+You should use this class **very rarely**, usually only if you're extending the library itself.
+
+* **Why use it:**
+* You need to implement completely custom routing logic.
+* Need direct access to WebSocket or raw connection events?
+* **What it does:** It's just an adapter that transforms Java objects to JSON and vice versa over a WebSocket. It doesn't know how to associate a response with the request that generated it.
+
+### Summary
+* Want a complete and easy app? Use **`DefaultRustRconService`**.
+* Want to just send raw commands without automation? Use **`DefaultRustRconRouter`**.
+
+<hr>
 
 ## Useful Resources
 

From bdef9c931e66a39b75f6e82c3f2ba881c812bdf9 Mon Sep 17 00:00:00 2001
From: Scalbox <info@scalbox.com>
Date: Mon, 5 Jan 2026 16:43:21 +0100
Subject: [PATCH 2/4] example documentation

---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 03f8261..ab6e191 100644
--- a/README.md
+++ b/README.md
@@ -186,7 +186,7 @@ public class ExampleUsage {
 }
 ```
 
-<hr>
+---
 
 <h3> DefaultRustRconRouter </h3>
 
@@ -245,7 +245,7 @@ public class RouterUsageExample {
 }
 ```
 
-<hr>
+---
 
 <h3> DefaultRustRconClient </h3>
 
@@ -310,7 +310,7 @@ public class ClientUsage {
 }
 ```
 
-<hr>
+---
 
 <h3> What should be used between DefaultRustRconService, DefaultRustRconRouter, and DefaultRustRconClient? </h3>
 

From 1087bbf9a48d6c74043601f7de81b6ab8d535b7b Mon Sep 17 00:00:00 2001
From: Scalbox <info@scalbox.com>
Date: Mon, 5 Jan 2026 16:49:33 +0100
Subject: [PATCH 3/4] example documentation

---
 README.md | 238 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 136 insertions(+), 102 deletions(-)

diff --git a/README.md b/README.md
index ab6e191..dd1b8d8 100644
--- a/README.md
+++ b/README.md
@@ -105,12 +105,17 @@ Rust RCON offers a plethora of events that give developers a detailed insight in
 
 ## Examples :alembic:
 
-**Difference between classes:** 
+**Difference between classes:**
 
 ```java
-public class DefaultRustRconService {}
-public class DefaultRustRconRouter {}
-public class DefaultRustRconClient {}
+public class DefaultRustRconService {
+}
+
+public class DefaultRustRconRouter {
+}
+
+public class DefaultRustRconClient {
+}
 ```
 
 <hr>
@@ -118,20 +123,24 @@ public class DefaultRustRconClient {}
 <h3> DefaultRustRconService </h3>
 
 ```java
-public class DefaultRustRconService {}
+public class DefaultRustRconService {
+}
 ```
 
 The `DefaultRustRconService` class is the **operational core** and the main implementation of the connection and management logic for a Rust game server using the RCON protocol.
 
 Here are its main functions:
 
-1. **Component Orchestration**: Acts as a central "hub" that initializes and connects the WebSocket client (`RustWebSocketClient`), the event system (`EventBus`), the communication protocols (`Codec`), and the data mappers (`RustDtoMappers`). It uses the `Lazy` pattern to initialize these components only when necessary.
+1. **Component Orchestration**: Acts as a central "hub" that initializes and connects the WebSocket client (`RustWebSocketClient`), the event system (`EventBus`), the communication protocols
+   (`Codec`), and the data mappers (`RustDtoMappers`). It uses the `Lazy` pattern to initialize these components only when necessary.
 2. **Lifecycle Management**: Manages the starting (`start()`) and stopping (`stop()`) of the server connection and the message router.
-3. **Automation (Polling)**: In the `configure()` method, set up scheduled tasks (`ScheduledExecutorService`) that automatically poll the server at regular intervals to keep local data up to date. Specifically:
-   * Server info (every 5 seconds).
-   * Player list (every 3 seconds).
-   * Team list (every 5 minutes).
-4. **State Management**: Maintains the current server state, such as the player list (`rustPlayers`), teams (`rustTeams`), and diagnostics, in memory (via `AtomicReference`), making them accessible to the application without having to make a network request each time.
+3. **Automation (Polling)**: In the `configure()` method, set up scheduled tasks (`ScheduledExecutorService`) that automatically poll the server at regular intervals to keep local data up to date.
+   Specifically:
+    * Server info (every 5 seconds).
+    * Player list (every 3 seconds).
+    * Team list (every 5 minutes).
+4. **State Management**: Maintains the current server state, such as the player list (`rustPlayers`), teams (`rustTeams`), and diagnostics, in memory (via `AtomicReference`), making them accessible to
+   the application without having to make a network request each time.
 5. **API Facade**: Provides high-level methods to access specific functionality, such as player management (`playerManagement()`) or Oxide framework management (`oxideManagement()`).
 
 To use the `DefaultRustRconService` class, you must follow a standard lifecycle: configuration, startup, interaction, and shutdown.
@@ -151,38 +160,38 @@ import com.scalbox.rust.rcon.DefaultRustRconService;
 import com.scalbox.rust.rcon.RustRconConfiguration;
 import com.scalbox.rust.rcon.protocol.dto.RustPlayerDTO;
 
-public class ExampleUsage { 
-
-   public static void main(String[] args) { 
-      // 1. Configuration 
-      RustRconConfiguration config = new RustRconConfiguration( 
-         "127.0.0.1", 
-         28016, 
-         "your_password_rcon"
-      ); 
-      
-      // 2. Instantiation of the service 
-      DefaultRustRconService rconService = new DefaultRustRconService(config); 
-      
-      // (Optional) Enable logging of all RCON traffic to the console
-      rconService.enableRconLogger();
-      
-      // 3. Start connection and background tasks
-      rconService.start();
-      
-      // 4. Interaction: Example of sending a command (banning a player)
-      // Note: playerManagement() offers high-level methods
-      // rconService.playerManagement().ban("steamId", "reason");
-      
-      // 4. Interaction: Read cached data (automatically updated every 3 seconds)
-      System.out.println("Online players: " + rconService.players().size());
-      
-      // 4. Interaction: Send raw command via Codec
-      rconService.codec().send("say Hello Server!");
-      
-      // 5. Stop (usually when the application shuts down)
-      rconService.stop();
-   }
+public class ExampleUsage {
+
+    public static void main(String[] args) {
+        // 1. Configuration 
+        RustRconConfiguration config = new RustRconConfiguration(
+                "127.0.0.1",
+                28016,
+                "your_password_rcon"
+        );
+
+        // 2. Instantiation of the service 
+        DefaultRustRconService rconService = new DefaultRustRconService(config);
+
+        // (Optional) Enable logging of all RCON traffic to the console
+        rconService.enableRconLogger();
+
+        // 3. Start connection and background tasks
+        rconService.start();
+
+        // 4. Interaction: Example of sending a command (banning a player)
+        // Note: playerManagement() offers high-level methods
+        // rconService.playerManagement().ban("steamId", "reason");
+
+        // 4. Interaction: Read cached data (automatically updated every 3 seconds)
+        System.out.println("Online players: " + rconService.players().size());
+
+        // 4. Interaction: Send raw command via Codec
+        rconService.codec().send("say Hello Server!");
+
+        // 5. Stop (usually when the application shuts down)
+        rconService.stop();
+    }
 }
 ```
 
@@ -191,21 +200,27 @@ public class ExampleUsage {
 <h3> DefaultRustRconRouter </h3>
 
 ```java
-public class DefaultRustRconRouter {}
+public class DefaultRustRconRouter {
+}
 ```
 
-The `DefaultRustRconRouter` class acts as a **transport and correlation layer** between your application and the raw RCON client. While the `Service` (seen previously) handles the high-level logic (players, teams), this `Router` handles the sending and receiving mechanics.
+The `DefaultRustRconRouter` class acts as a **transport and correlation layer** between your application and the raw RCON client. While the `Service` (seen previously) handles the high-level logic
+(players, teams), this `Router` handles the sending and receiving mechanics.
 
 Here's what it does specifically:
 
-1. **Identifier (ID) Management**: The RCON protocol requires each packet sent to have a unique ID to associate the response with the correct request. This class generates these IDs automatically (`identifierGenerator`) using an `AtomicInteger`.
-2. **Request/Response Correlation**: When you call `send()`, the class packages the message in a `RustRconRequest`, sends it, and returns a `CompletableFuture`. This allows the response to be handled asynchronously as soon as it arrives.
-3. **Audit and Logging (Event Bus)**: Using the `handleRconProtocolExchange` method, every time a request is completed (successfully or unsuccessfully), an `RconProtocolExchangeEvent` is published to the `EventBus`. This is essential for logging traffic or for plugins that need to analyze everything that passes "over the wire".
+1. **Identifier (ID) Management**: The RCON protocol requires each packet sent to have a unique ID to associate the response with the correct request. This class generates these IDs automatically
+   (`identifierGenerator`) using an `AtomicInteger`.
+2. **Request/Response Correlation**: When you call `send()`, the class packages the message in a `RustRconRequest`, sends it, and returns a `CompletableFuture`. This allows the response to be handled
+   asynchronously as soon as it arrives.
+3. **Audit and Logging (Event Bus)**: Using the `handleRconProtocolExchange` method, every time a request is completed (successfully or unsuccessfully), an `RconProtocolExchangeEvent` is published to
+   the `EventBus`. This is essential for logging traffic or for plugins that need to analyze everything that passes "over the wire".
 4. **Client Abstraction**: Hides the connection details of the underlying `RustRconClient`, exposing only methods for sending messages and managing the lifecycle (`start`/`stop`).
 
 ### How to use it
 
-Typically, this class is instantiated and managed internally by the `DefaultRustRconService`. However, if you're building a custom implementation or need to send raw commands bypassing the high-level logic, you can use it like this:
+Typically, this class is instantiated and managed internally by the `DefaultRustRconService`. However, if you're building a custom implementation or need to send raw commands bypassing the high-level
+logic, you can use it like this:
 
 1. Dependency Injection: Requires a RustRconClient (the physical connection) and an EventBus (for events).
 2. Lifecycle: You must call start() to connect and stop() to close.
@@ -221,27 +236,27 @@ import com.scalbox.rust.rcon.protocol.RustRconMessage;
 
 public class RouterUsageExample {
 
-   public void example(RustRconClient rawClient, EventBus eventBus) {
-      // 1. Instantiation
-      DefaultRustRconRouter router = new DefaultRustRconRouter(rawClient, eventBus);
-      
-      // 2. Starting the underlying connection
-      router.start();
-      
-      // 3. Creating a message (functional wrapper or object)
-      RustRconMessage message = () -> "status";
-      
-      // 4. Asynchronous sending and response handling
-      router.send(message).thenAccept(response -> {
-        System.out.println("Response from server: " + response.getMessage());
-      }).exceptional(ex -> {
-        System.err.println("Error sending: " + ex.getMessage());
-        return null;
-      });
-      
-      // 5. Stop
-      router.stop();
-   }
+    public void example(RustRconClient rawClient, EventBus eventBus) {
+        // 1. Instantiation
+        DefaultRustRconRouter router = new DefaultRustRconRouter(rawClient, eventBus);
+
+        // 2. Starting the underlying connection
+        router.start();
+
+        // 3. Creating a message (functional wrapper or object)
+        RustRconMessage message = () -> "status";
+
+        // 4. Asynchronous sending and response handling
+        router.send(message).thenAccept(response -> {
+            System.out.println("Response from server: " + response.getMessage());
+        }).exceptional(ex -> {
+            System.err.println("Error sending: " + ex.getMessage());
+            return null;
+        });
+
+        // 5. Stop
+        router.stop();
+    }
 }
 ```
 
@@ -250,21 +265,26 @@ public class RouterUsageExample {
 <h3> DefaultRustRconClient </h3>
 
 ```java
-public class DefaultRustRconClient {}
+public class DefaultRustRconClient {
+}
 ```
 
 The `DefaultRustRconClient` class is the concrete, low-level implementation of the RCON client. It acts as a protocol adapter between the raw WebSocket connection and the Java application logic.
 
 Here are its main functions:
 
-1. **Asynchronous Request/Response Handling**: This component solves the complexity of asynchrony. When you send a command, the server responds at a future time. This class uses a `CompletableFuture` cache to "remember" which request is pending and completes the correct future when the response with the same ID arrives (`onWsMessage`).
-2. **Serialization/Deserialization**: Converts Java objects (`RustRconRequest`) to JSON for sending and converts the JSON received from the WebSocket into Java objects (`RustRconResponse`), using a `JsonMapper`.
-3. **WebSocket Event Handling**: Listens for low-level WebSocket events (`WsOpenedEvent`, `WsMessageEvent`, `WsClosedEvent`) via the `EventBus` and reacts accordingly (e.g., by setting the `isInitialized` flag or publishing an `RconReceivedEvent`).
+1. **Asynchronous Request/Response Handling**: This component solves the complexity of asynchrony. When you send a command, the server responds at a future time. This class uses a `CompletableFuture`
+   cache to "remember" which request is pending and completes the correct future when the response with the same ID arrives (`onWsMessage`).
+2. **Serialization/Deserialization**: Converts Java objects (`RustRconRequest`) to JSON for sending and converts the JSON received from the WebSocket into Java objects (`RustRconResponse`), using a
+   `JsonMapper`.
+3. **WebSocket Event Handling**: Listens for low-level WebSocket events (`WsOpenedEvent`, `WsMessageEvent`, `WsClosedEvent`) via the `EventBus` and reacts accordingly (e.g., by setting the
+   `isInitialized` flag or publishing an `RconReceivedEvent`).
 4. **Connection Management**: Controls the opening (`connect()`) and controlled closing (`close()`) of the underlying WebSocket connection.
 
 ### How to use it
 
-Normally, this class is "hidden" within `DefaultRustRconRouter` or `DefaultRustRconService`. However, if you need to use it directly to manually manage the RCON protocol without the higher-level abstractions, here's how:
+Normally, this class is "hidden" within `DefaultRustRconRouter` or `DefaultRustRconService`. However, if you need to use it directly to manually manage the RCON protocol without the higher-level
+abstractions, here's how:
 
 1. **Dependencies**: Requires a `RustWebSocketClient` (the physical connection) and an `EventBus`.
 2. **Setup**: Instantiate the class and call `connect()`.
@@ -278,35 +298,43 @@ import com.google.common.eventbus.EventBus;
 import com.scalbox.rust.rcon.DefaultRustRconClient;
 import com.scalbox.rust.rcon.protocol.RustRconRequest;
 import com.scalbox.rust.rcon.ws.RustWebSocketClient; // Hypothetical implementation
+
 import java.net.URI;
 
 public class ClientUsage {
 
-   public void manualClientUsage() {
-      // 1. Prepare dependencies
-      EventBus eventBus = new EventBus();
-      RustWebSocketClient wsClient = new RustWebSocketClient(URI.create("ws://127.0.0.1:28016/password"), eventBus);
-      
-      // 2. Instantiation
-      DefaultRustRconClient client = new DefaultRustRconClient(wsClient, eventBus);
-      
-      // 3. Connection (register listeners on the EventBus internally)
-      client.connect();
-      
-      // 4. Manual request creation (note: you must manage the ID here if you don't use the Router)
-      RustRconRequest request = new RustRconRequest() {
-        @Override public int getIdentifier() { return 12345; }
-        @Override public String getMessage() { return "status"; }
-      };
-      
-      // 5. Sending and handling the response
-      client.send(request).thenAccept(response -> {
-        System.out.println("Raw Response: " + response.getMessage());
-      });
-      
-      // 6. Closing
-      client.close();
-   }
+    public void manualClientUsage() {
+        // 1. Prepare dependencies
+        EventBus eventBus = new EventBus();
+        RustWebSocketClient wsClient = new RustWebSocketClient(URI.create("ws://127.0.0.1:28016/password"), eventBus);
+
+        // 2. Instantiation
+        DefaultRustRconClient client = new DefaultRustRconClient(wsClient, eventBus);
+
+        // 3. Connection (register listeners on the EventBus internally)
+        client.connect();
+
+        // 4. Manual request creation (note: you must manage the ID here if you don't use the Router)
+        RustRconRequest request = new RustRconRequest() {
+            @Override
+            public int getIdentifier() {
+                return 12345;
+            }
+
+            @Override
+            public String getMessage() {
+                return "status";
+            }
+        };
+
+        // 5. Sending and handling the response
+        client.send(request).thenAccept(response -> {
+            System.out.println("Raw Response: " + response.getMessage());
+        });
+
+        // 6. Closing
+        client.close();
+    }
 }
 ```
 
@@ -317,10 +345,13 @@ public class ClientUsage {
 The choice depends on the level of abstraction and control you need for your application. Here's a quick guide to help you decide:
 
 1. **`DefaultRustRconClient`**: This is the lowest level. It only handles the raw socket connection. It's too primitive to handle complex business logic (such as request/response correlation).
-2. **`DefaultRustRconRouter`** (the file you're viewing): This is the communication "engine." As you can see from the code, it manages the `EventBus`, the correlation between requests and responses via IDs (`identifierGenerator`), and returns `CompletableFuture`. It's essential for asynchronous operation, but is intended to be used by a higher level.
-3. **`DefaultRustRconService`**: This is the highest-level abstraction. It typically encapsulates the `Router` and provides ready-made utility methods (e.g., getting the player list, server info, etc.) that you need for the dashboard.
+2. **`DefaultRustRconRouter`** (the file you're viewing): This is the communication "engine." As you can see from the code, it manages the `EventBus`, the correlation between requests and responses
+   via IDs (`identifierGenerator`), and returns `CompletableFuture`. It's essential for asynchronous operation, but is intended to be used by a higher level.
+3. **`DefaultRustRconService`**: This is the highest-level abstraction. It typically encapsulates the `Router` and provides ready-made utility methods (e.g., getting the player list, server info,
+   etc.) that you need for the dashboard.
 
 ### 1. DefaultRustRconService (Recommended in 95% of cases)
+
 This is the "turnkey" solution. You should use this class if you're building a bot, a dashboard, or a standard management tool.
 
 * **Why use it:**
@@ -331,6 +362,7 @@ This is the "turnkey" solution. You should use this class if you're building a b
 * **Hierarchy:** Internally, it instantiates and manages both the *Router* and the *Client*.
 
 ### 2. DefaultRustRconRouter (Intermediate Level)
+
 You should use this class if you want lightweight control but aren't interested in the Service's automatic features.
 
 * **Why use it:**
@@ -340,6 +372,7 @@ You should use this class if you want lightweight control but aren't interested
 * **What it does:** Handles Request-Response correlation (packet ID) and serialization, but doesn't maintain state (no player cache).
 
 ### 3. DefaultRustRconClient (Low Level)
+
 You should use this class **very rarely**, usually only if you're extending the library itself.
 
 * **Why use it:**
@@ -348,6 +381,7 @@ You should use this class **very rarely**, usually only if you're extending the
 * **What it does:** It's just an adapter that transforms Java objects to JSON and vice versa over a WebSocket. It doesn't know how to associate a response with the request that generated it.
 
 ### Summary
+
 * Want a complete and easy app? Use **`DefaultRustRconService`**.
 * Want to just send raw commands without automation? Use **`DefaultRustRconRouter`**.
 

From f903394fa6e7903492ea071474a2a8ddaedf73e5 Mon Sep 17 00:00:00 2001
From: Scalbox <info@scalbox.com>
Date: Mon, 5 Jan 2026 16:51:04 +0100
Subject: [PATCH 4/4] example documentation

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index dd1b8d8..49af59e 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ Rust RCON offers a plethora of events that give developers a detailed insight in
 - **WsErrorEvent**: Triggered when there's an error in the websocket communication.
 - **WsClosedEvent**: Emitted when the websocket connection is closed, either due to errors or deliberate actions.
 
-<hr>
+---
 
 ## Examples :alembic:
 
@@ -118,7 +118,7 @@ public class DefaultRustRconClient {
 }
 ```
 
-<hr>
+---
 
 <h3> DefaultRustRconService </h3>