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 {} }