From 1134649197140e3ad1ea8b04303979a0d9332936 Mon Sep 17 00:00:00 2001
From: lieght <49651652+BAFGdeJong@users.noreply.github.com>
Date: Wed, 15 Oct 2025 20:11:43 +0200
Subject: [PATCH] Documentation
---
.../networking/events/NetworkEvents.java | 232 +++++++++++-------
1 file changed, 142 insertions(+), 90 deletions(-)
diff --git a/framework/src/main/java/org/toop/framework/networking/events/NetworkEvents.java b/framework/src/main/java/org/toop/framework/networking/events/NetworkEvents.java
index 8938721..ac3de68 100644
--- a/framework/src/main/java/org/toop/framework/networking/events/NetworkEvents.java
+++ b/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
- * org.toop.framework.eventbus.GlobalEventBus}.
+ * Defines all event types related to the networking subsystem.
+ *
+ * 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.
+ *
*
- * This class defines all the events that can be posted or listened to in the networking
- * subsystem. Events are separated into those with unique IDs (UniqueEvent) and those without
- * (GenericEvent).
+ *
Important
+ * For all {@link UniqueEvent} and {@link ResponseToUniqueEvent} types:
+ * the {@code identifier} field is automatically generated and injected
+ * by {@link org.toop.framework.eventbus.EventFlow}. It should never
+ * 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.
- *
- * This is a blocking event. The result will be delivered via the provided {@link
- * CompletableFuture}.
- *
- * @param future CompletableFuture to receive the list of active {@link NetworkingClient}
- * instances.
+ * Requests a list of all active networking clients.
+ *
+ * This is a blocking request that returns the list asynchronously
+ * via the provided {@link CompletableFuture}.
*/
public record RequestsAllClients(CompletableFuture> 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. */
- public record ChallengeCancelledResponse(long clientId, String challengeId) implements GenericEvent {}
+ /** Indicates a challenge was cancelled by the server. */
+ 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. */
- public record PlayerlistResponse(long clientId, String[] playerlist) implements GenericEvent {}
+ /** Contains the list of players currently available on the server. */
+ public record PlayerlistResponse(long clientId, String[] playerlist)
+ implements GenericEvent {}
- /** Response containing a list of games for a client. */
- public record GamelistResponse(long clientId, String[] gamelist) implements GenericEvent {}
+ /** Contains the list of available game types for a client. */
+ 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. */
- public record GameResultResponse(long clientId, String condition) implements GenericEvent {}
+ /** Indicates the outcome or completion of a game. */
+ public record GameResultResponse(long clientId, String condition)
+ implements GenericEvent {}
- /** Response indicating a game move occurred. */
- public record GameMoveResponse(long clientId, String player, String move, String details) implements GenericEvent {}
+ /** Indicates that a game move has been processed or received. */
+ 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. */
- public record SendLogin(long clientId, String username) implements GenericEvent {}
+ /** Requests a login operation for the given client. */
+ public record SendLogin(long clientId, String username)
+ implements GenericEvent {}
- /** Request to log out a client. */
- public record SendLogout(long clientId) implements GenericEvent {}
+ /** Requests logout for the specified client. */
+ public record SendLogout(long clientId)
+ implements GenericEvent {}
- /** Request to retrieve the player list for a client. */
- public record SendGetPlayerlist(long clientId) implements GenericEvent {}
+ /** Requests the player list from the server. */
+ public record SendGetPlayerlist(long clientId)
+ implements GenericEvent {}
- /** Request to retrieve the game list for a client. */
- public record SendGetGamelist(long clientId) implements GenericEvent {}
+ /** Requests the game list from the server. */
+ public record SendGetGamelist(long clientId)
+ implements GenericEvent {}
- /** Request to subscribe a client to a game type. */
- public record SendSubscribe(long clientId, String gameType) implements GenericEvent {}
+ /** Requests a subscription to updates for a given game type. */
+ public record SendSubscribe(long clientId, String gameType)
+ implements GenericEvent {}
- /** Request to make a move in a game. */
- public record SendMove(long clientId, short moveNumber) implements GenericEvent {}
+ /** Sends a game move command to the server. */
+ public record SendMove(long clientId, short moveNumber)
+ implements GenericEvent {}
- /** Request to challenge another player. */
- public record SendChallenge(long clientId, String usernameToChallenge, String gameType) implements GenericEvent {}
+ /** Requests to challenge another player to a game. */
+ public record SendChallenge(long clientId, String usernameToChallenge, String gameType)
+ implements GenericEvent {}
- /** Request to accept a challenge. */
- public record SendAcceptChallenge(long clientId, int challengeId) implements GenericEvent {}
+ /** Requests to accept an existing challenge. */
+ public record SendAcceptChallenge(long clientId, int challengeId)
+ implements GenericEvent {}
- /** Request to forfeit a game. */
- public record SendForfeit(long clientId) implements GenericEvent {}
+ /** Requests to forfeit the current game. */
+ public record SendForfeit(long clientId)
+ implements GenericEvent {}
- /** Request to send a message from a client. */
- public record SendMessage(long clientId, String message) implements GenericEvent {}
+ /** Sends a chat or informational message from a client. */
+ public record SendMessage(long clientId, String message)
+ implements GenericEvent {}
- /** Request to display help to a client. */
- public record SendHelp(long clientId) implements GenericEvent {}
+ /** Requests general help information from the server. */
+ public record SendHelp(long clientId)
+ implements GenericEvent {}
- /** Request to display help for a specific command. */
- public record SendHelpForCommand(long clientId, String command) implements GenericEvent {}
+ /** Requests help information specific to a given command. */
+ public record SendHelpForCommand(long clientId, String command)
+ implements GenericEvent {}
- /** Request to close a specific client connection. */
- public record CloseClient(long clientId) implements GenericEvent {}
+ /** Requests to close an active client connection. */
+ public record CloseClient(long clientId)
+ implements GenericEvent {}
- /** Generic server response. */
- public record ServerResponse(long clientId) implements GenericEvent {}
+ /** A generic event indicating a raw server response. */
+ 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.
+ *
+ * The {@code identifier} is automatically assigned by {@link org.toop.framework.eventbus.EventFlow}
+ * to correlate with its corresponding {@link StartClientResponse}.
+ *
*
- * Carries IP, port, and a unique event ID for correlation with responses.
- *
- * @param networkingClient
- * @param networkingConnector
+ * @param networkingClient The client instance to start.
+ * @param networkingConnector Connection details (host, port, etc.).
+ * @param identifier Automatically injected unique identifier.
*/
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.
+ *
+ * The {@code identifier} value is automatically propagated from
+ * the original {@link StartClient} request by {@link org.toop.framework.eventbus.EventFlow}.
+ *
*
- * @param clientId The client ID assigned to the new connection.
- * @param successful If successfully connected or not. If not clientId will also be -1.
+ * @param clientId The newly assigned client ID.
+ * @param successful Whether the connection succeeded.
+ * @param identifier Automatically injected correlation ID.
*/
@AutoResponseResult
- 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 {}
+ public record StartClientResponse(long clientId, boolean successful, long identifier)
+ implements ResponseToUniqueEvent {}
/**
- * Request to change a client connection to a new server.
- *
- * @param clientId The client connection ID.
- * @param networkingConnector
+ * Requests reconnection of an existing client using its previous configuration.
+ *
+ * The {@code identifier} is automatically injected by {@link org.toop.framework.eventbus.EventFlow}.
+ *
*/
- 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.
- *
- * @param clientId The connection ID that received the message.
- * @param message The message content.
+ * Requests to change the connection target (host/port) for a client.
+ *
+ * The {@code identifier} is automatically injected by {@link org.toop.framework.eventbus.EventFlow}.
+ *
*/
- 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. */
- public record ClosedConnection(long clientId) implements GenericEvent {}
+ /** Response to a {@link ChangeAddress} event, carrying the success result. */
+ public record ChangeAddressResponse(boolean successful, long identifier)
+ implements ResponseToUniqueEvent {}
}