mirror of
https://github.com/2OOP/pism.git
synced 2026-02-04 10:54:51 +00:00
Documentation
This commit is contained in:
lieght
@@ -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.
|
||||
* <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
|
||||
* subsystem. Events are separated into those with unique IDs (UniqueEvent) and those without
|
||||
* (GenericEvent).
|
||||
* <h2>Important</h2>
|
||||
* 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 <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.
|
||||
*
|
||||
* <p>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.
|
||||
* <p>
|
||||
* This is a blocking request that returns the list asynchronously
|
||||
* via the provided {@link CompletableFuture}.
|
||||
*/
|
||||
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. */
|
||||
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.
|
||||
* <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
|
||||
* @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.
|
||||
* <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 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.
|
||||
* <p>
|
||||
* The {@code identifier} is automatically injected by {@link org.toop.framework.eventbus.EventFlow}.
|
||||
* </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.
|
||||
*
|
||||
* @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.
|
||||
* <p>
|
||||
* The {@code identifier} is automatically injected by {@link org.toop.framework.eventbus.EventFlow}.
|
||||
* </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. */
|
||||
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 {}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user