Documentation

framework/src/main/java/org/toop/framework/networking/events/NetworkEvents.java

@@ -3,163 +3,215 @@ package org.toop.framework.networking.events;
 import java.util.*;
 import java.util.concurrent.CompletableFuture;
 
-import org.toop.framework.eventbus.events.GenericEvent;
-import org.toop.framework.eventbus.events.ResponseToUniqueEvent;
-import org.toop.framework.eventbus.events.UniqueEvent;
-import org.toop.framework.eventbus.events.EventsBase;
 import org.toop.annotations.AutoResponseResult;
+import org.toop.framework.eventbus.events.*;
 import org.toop.framework.networking.interfaces.NetworkingClient;
 import org.toop.framework.networking.types.NetworkingConnector;
 
 /**
- * A collection of networking-related event records for use with the {@link
+ * Defines all event types related to the networking subsystem.
- * org.toop.framework.eventbus.GlobalEventBus}.
+ * <p>
+ * These events are used in conjunction with the {@link org.toop.framework.eventbus.GlobalEventBus}
+ * and {@link org.toop.framework.eventbus.EventFlow} to communicate between components
+ * such as networking clients, managers, and listeners.
+ * </p>
  *
- * <p>This class defines all the events that can be posted or listened to in the networking
+ * <h2>Important</h2>
- * subsystem. Events are separated into those with unique IDs (UniqueEvent) and those without
+ * For all {@link UniqueEvent} and {@link ResponseToUniqueEvent} types:
- * (GenericEvent).
+ * the {@code identifier} field is automatically generated and injected
+ * by {@link org.toop.framework.eventbus.EventFlow}. It should <strong>never</strong>
+ * be manually assigned by user code. (Exceptions may apply)
  */
 public class NetworkEvents extends EventsBase {
 
+    // ------------------------------------------------------
+    // Generic Request & Response Events (no identifier)
+    // ------------------------------------------------------
+
     /**
-     * Requests all active client connections.
+     * Requests a list of all active networking clients.
-     *
+     * <p>
-     * <p>This is a blocking event. The result will be delivered via the provided {@link
+     * This is a blocking request that returns the list asynchronously
-     * CompletableFuture}.
+     * via the provided {@link CompletableFuture}.
-     *
-     * @param future CompletableFuture to receive the list of active {@link NetworkingClient}
-     *     instances.
      */
     public record RequestsAllClients(CompletableFuture<List<NetworkingClient>> future)
             implements GenericEvent {}
 
-    /** Forces all active client connections to close immediately. */
+    /** Signals all active clients should be forcefully closed. */
     public record ForceCloseAllClients() implements GenericEvent {}
 
-    /** Response indicating a challenge was cancelled. */
+    /** Indicates a challenge was cancelled by the server. */
-    public record ChallengeCancelledResponse(long clientId, String challengeId) implements GenericEvent {}
+    public record ChallengeCancelledResponse(long clientId, String challengeId)
+            implements GenericEvent {}
 
-    /** Response indicating a challenge was received. */
+    /** Indicates an incoming challenge from another player. */
     public record ChallengeResponse(long clientId, String challengerName, String challengeId, String gameType)
             implements GenericEvent {}
 
-    /** Response containing a list of players for a client. */
+    /** Contains the list of players currently available on the server. */
-    public record PlayerlistResponse(long clientId, String[] playerlist) implements GenericEvent {}
+    public record PlayerlistResponse(long clientId, String[] playerlist)
+            implements GenericEvent {}
 
-    /** Response containing a list of games for a client. */
+    /** Contains the list of available game types for a client. */
-    public record GamelistResponse(long clientId, String[] gamelist) implements GenericEvent {}
+    public record GamelistResponse(long clientId, String[] gamelist)
+            implements GenericEvent {}
 
-    /** Response indicating a game match information for a client. */
+    /** Provides match information when a new game starts. */
     public record GameMatchResponse(long clientId, String playerToMove, String gameType, String opponent)
             implements GenericEvent {}
 
-    /** Response indicating the result of a game. */
+    /** Indicates the outcome or completion of a game. */
-    public record GameResultResponse(long clientId, String condition) implements GenericEvent {}
+    public record GameResultResponse(long clientId, String condition)
+            implements GenericEvent {}
 
-    /** Response indicating a game move occurred. */
+    /** Indicates that a game move has been processed or received. */
-    public record GameMoveResponse(long clientId, String player, String move, String details) implements GenericEvent {}
+    public record GameMoveResponse(long clientId, String player, String move, String details)
+            implements GenericEvent {}
 
-    /** Response indicating it is the player's turn. */
+    /** Indicates it is the current player's turn to move. */
     public record YourTurnResponse(long clientId, String message)
             implements GenericEvent {}
 
-    /** Request to send login credentials for a client. */
+    /** Requests a login operation for the given client. */
-    public record SendLogin(long clientId, String username) implements GenericEvent {}
+    public record SendLogin(long clientId, String username)
+            implements GenericEvent {}
 
-    /** Request to log out a client. */
+    /** Requests logout for the specified client. */
-    public record SendLogout(long clientId) implements GenericEvent {}
+    public record SendLogout(long clientId)
+            implements GenericEvent {}
 
-    /** Request to retrieve the player list for a client. */
+    /** Requests the player list from the server. */
-    public record SendGetPlayerlist(long clientId) implements GenericEvent {}
+    public record SendGetPlayerlist(long clientId)
+            implements GenericEvent {}
 
-    /** Request to retrieve the game list for a client. */
+    /** Requests the game list from the server. */
-    public record SendGetGamelist(long clientId) implements GenericEvent {}
+    public record SendGetGamelist(long clientId)
+            implements GenericEvent {}
 
-    /** Request to subscribe a client to a game type. */
+    /** Requests a subscription to updates for a given game type. */
-    public record SendSubscribe(long clientId, String gameType) implements GenericEvent {}
+    public record SendSubscribe(long clientId, String gameType)
+            implements GenericEvent {}
 
-    /** Request to make a move in a game. */
+    /** Sends a game move command to the server. */
-    public record SendMove(long clientId, short moveNumber) implements GenericEvent {}
+    public record SendMove(long clientId, short moveNumber)
+            implements GenericEvent {}
 
-    /** Request to challenge another player. */
+    /** Requests to challenge another player to a game. */
-    public record SendChallenge(long clientId, String usernameToChallenge, String gameType) implements GenericEvent {}
+    public record SendChallenge(long clientId, String usernameToChallenge, String gameType)
+            implements GenericEvent {}
 
-    /** Request to accept a challenge. */
+    /** Requests to accept an existing challenge. */
-    public record SendAcceptChallenge(long clientId, int challengeId) implements GenericEvent {}
+    public record SendAcceptChallenge(long clientId, int challengeId)
+            implements GenericEvent {}
 
-    /** Request to forfeit a game. */
+    /** Requests to forfeit the current game. */
-    public record SendForfeit(long clientId) implements GenericEvent {}
+    public record SendForfeit(long clientId)
+            implements GenericEvent {}
 
-    /** Request to send a message from a client. */
+    /** Sends a chat or informational message from a client. */
-    public record SendMessage(long clientId, String message) implements GenericEvent {}
+    public record SendMessage(long clientId, String message)
+            implements GenericEvent {}
 
-    /** Request to display help to a client. */
+    /** Requests general help information from the server. */
-    public record SendHelp(long clientId) implements GenericEvent {}
+    public record SendHelp(long clientId)
+            implements GenericEvent {}
 
-    /** Request to display help for a specific command. */
+    /** Requests help information specific to a given command. */
-    public record SendHelpForCommand(long clientId, String command) implements GenericEvent {}
+    public record SendHelpForCommand(long clientId, String command)
+            implements GenericEvent {}
 
-    /** Request to close a specific client connection. */
+    /** Requests to close an active client connection. */
-    public record CloseClient(long clientId) implements GenericEvent {}
+    public record CloseClient(long clientId)
+            implements GenericEvent {}
 
-    /** Generic server response. */
+    /** A generic event indicating a raw server response. */
-    public record ServerResponse(long clientId) implements GenericEvent {}
+    public record ServerResponse(long clientId)
+            implements GenericEvent {}
 
     /**
-     * Request to send a command to a server.
+     * Sends a raw command string to the server.
      *
-     * @param clientId The client connection ID.
+     * @param clientId The client ID to send the command from.
      * @param args The command arguments.
      */
-    public record SendCommand(long clientId, String... args) implements GenericEvent {}
+    public record SendCommand(long clientId, String... args)
+            implements GenericEvent {}
+
+    /** Event fired when a message is received from the server. */
+    public record ReceivedMessage(long clientId, String message)
+            implements GenericEvent {}
+
+    /** Indicates that a client connection has been closed. */
+    public record ClosedConnection(long clientId)
+            implements GenericEvent {}
+
+    // ------------------------------------------------------
+    // Unique Request & Response Events (with identifier)
+    // ------------------------------------------------------
 
     /**
-     * Event to start a new client connection.
+     * Requests creation and connection of a new client.
+     * <p>
+     * The {@code identifier} is automatically assigned by {@link org.toop.framework.eventbus.EventFlow}
+     * to correlate with its corresponding {@link StartClientResponse}.
+     * </p>
      *
-     * <p>Carries IP, port, and a unique event ID for correlation with responses.
+     * @param networkingClient The client instance to start.
-     *
+     * @param networkingConnector Connection details (host, port, etc.).
-     * @param networkingClient
+     * @param identifier Automatically injected unique identifier.
-     * @param networkingConnector
      */
     public record StartClient(
             NetworkingClient networkingClient,
             NetworkingConnector networkingConnector,
-            long identifier) implements UniqueEvent {}
+            long identifier)
+            implements UniqueEvent {}
 
     /**
-     * Response confirming a client was started.
+     * Response confirming that a client has been successfully started.
+     * <p>
+     * The {@code identifier} value is automatically propagated from
+     * the original {@link StartClient} request by {@link org.toop.framework.eventbus.EventFlow}.
+     * </p>
      *
-     * @param clientId   The client ID assigned to the new connection.
+     * @param clientId The newly assigned client ID.
-     * @param successful If successfully connected or not. If not clientId will also be -1.
+     * @param successful Whether the connection succeeded.
+     * @param identifier Automatically injected correlation ID.
      */
     @AutoResponseResult
-    public record StartClientResponse(long clientId, boolean successful, long identifier) implements ResponseToUniqueEvent {}
+    public record StartClientResponse(long clientId, boolean successful, long identifier)
-
+            implements ResponseToUniqueEvent {}
-    /** WIP (Not working) Request to reconnect a client to a previous address. */
-    public record Reconnect(long clientId, NetworkingClient networkingClient, NetworkingConnector networkingConnector, long identifier)
-            implements UniqueEvent {}
-
-    public record ReconnectResponse(boolean successful, long identifier) implements ResponseToUniqueEvent {}
 
     /**
-     * Request to change a client connection to a new server.
+     * Requests reconnection of an existing client using its previous configuration.
-     *
+     * <p>
-     * @param clientId The client connection ID.
+     * The {@code identifier} is automatically injected by {@link org.toop.framework.eventbus.EventFlow}.
-     * @param networkingConnector
+     * </p>
      */
-    public record ChangeAddress(long clientId, NetworkingClient networkingClient, NetworkingConnector networkingConnector, long identifier)
+    public record Reconnect(
+            long clientId,
+            NetworkingClient networkingClient,
+            NetworkingConnector networkingConnector,
+            long identifier)
             implements UniqueEvent {}
 
-    public record ChangeAddressResponse(boolean successful, long identifier) implements ResponseToUniqueEvent {}
+    /** Response to a {@link Reconnect} event, carrying the success result. */
+    public record ReconnectResponse(boolean successful, long identifier)
+            implements ResponseToUniqueEvent {}
 
     /**
-     * Response triggered when a message is received from a server.
+     * Requests to change the connection target (host/port) for a client.
-     *
+     * <p>
-     * @param clientId The connection ID that received the message.
+     * The {@code identifier} is automatically injected by {@link org.toop.framework.eventbus.EventFlow}.
-     * @param message The message content.
+     * </p>
      */
-    public record ReceivedMessage(long clientId, String message) implements GenericEvent {}
+    public record ChangeAddress(
+            long clientId,
+            NetworkingClient networkingClient,
+            NetworkingConnector networkingConnector,
+            long identifier)
+            implements UniqueEvent {}
 
-    /** Event indicating a client connection was closed. */
+    /** Response to a {@link ChangeAddress} event, carrying the success result. */
-    public record ClosedConnection(long clientId) implements GenericEvent {}
+    public record ChangeAddressResponse(boolean successful, long identifier)
+            implements ResponseToUniqueEvent {}
 }