Add: complete JavaDoc for networking, heartbeat, totem flow and game events

src/main/java/it/polimi/ingsw/gc14/ServerLauncher.java

@@ -192,15 +192,26 @@ public class ServerLauncher {
 
 
     /**
-     * The first method executed when the server program is launched.
-     * It creates all the objects needed: playerList, actionQueue, gameController, serverRMI, serverTCP, launcher.
-     * Then sets the playerList's action to execute launcher.run() and starts the TCP/RMI servers.
-     * Note: the model is initialized and set in the controller in TCP/RMI servers when the first user decides the number of players.
+     * Entry point of the server application.
      *
-     * @throws InterruptedException if this exception is issued by run method
-     * @throws RemoteException if this exception is issued by run method
+     * <p>The method initializes the shared player list, the network event queue,
+     * the game controller, the RMI server, the TCP server, and the server launcher.
+     * It also selects the network interface to expose, configures the server crash
+     * recovery state, and defines the action to execute once the required number
+     * of players has joined the game.
+     *
+     * <p>When the player list reaches its limit, the current game model is converted
+     * into a {@link MiniModel}, sent to all connected clients through both RMI and TCP,
+     * and rendered on the server-side TUI. Finally, the event-processing launcher
+     * and both network servers are started.
+     *
+     * <p>The game model itself is initialized by the TCP or RMI server when the first
+     * player joins and selects the total number of players.
+     *
+     * @param args the command-line arguments passed to the server application.
+     * @throws RemoteException if the RMI server cannot be created.
      */
-    public static void main(String[] args) throws InterruptedException, RemoteException {
+    public static void main(String[] args) throws RemoteException {
         playerList = new LimitedMap<String,Boolean>(5, ()->{});
         BlockingQueue<NetworkEvent> actionQueue = new LinkedBlockingQueue<>();
         GameController gameController = new GameController();
@@ -261,10 +272,13 @@ public class ServerLauncher {
 
 
     /**
-     * Creates and executes the game.
-     * Game creation: TCP/RMI servers send the game model to all players.
-     * Game execution: repeatedly calls doFirstEvent() to process the events in the actionQueue.
-     * @throws InterruptedException if the TCP server thread is interrupted
+     * Executes the main game loop.
+     *
+     * <p>The method repeatedly processes the first event in the action queue
+     * and, when a view is available, updates the rendered game state.
+     *
+     * <p>If the thread is interrupted while waiting for an event,
+     * the interruption status is restored and the loop terminates.
      */
     public void run() {
         while (true) {
@@ -282,6 +296,18 @@ public class ServerLauncher {
         }
     }
 
+    /**
+     * Lets the user choose the network interface to be used by the server.
+     *
+     * <p>The method scans all active, non-loopback, and non-virtual network
+     * interfaces, collecting their IPv4 addresses. If only one valid address is
+     * found, it is selected automatically. Otherwise, the available addresses are
+     * printed and the user is asked to choose one by index.
+     *
+     * @param scanner the scanner used to read the user's selection.
+     * @return the IPv4 address of the selected network interface.
+     * @throws Exception if no valid network interface is available.
+     */
     public static String chooseNetworkInterface(Scanner scanner) throws Exception {
         List<String> ips = new ArrayList<>();
 
@@ -315,6 +341,16 @@ public class ServerLauncher {
         return ips.get(choice);
     }
 
+    /**
+     * Saves the current game model to a local file.
+     *
+     * <p>The save file is stored in the {@code GameSaves/save.dat} path relative
+     * to the server executable location. If the directory does not exist, it is
+     * created before writing the serialized game model.
+     *
+     * @return {@code true} if the game is saved successfully,
+     *         {@code false} otherwise.
+     */
     private boolean gameSave(){
         try{
             Path jarPath = Paths.get(getClass().getProtectionDomain().getCodeSource().getLocation().toURI()).getParent();
@@ -340,6 +376,16 @@ public class ServerLauncher {
         }
     }
 
+    /**
+     * Loads a previously saved game model from the local save file.
+     *
+     * <p>The method attempts to deserialize the game stored in
+     * {@code GameSaves/save.dat}. If no save file exists or an I/O error occurs,
+     * {@code null} is returned.
+     *
+     * @return the loaded {@link Game} instance, or {@code null} if no valid save
+     *         can be loaded.
+     */
     private Game loadSave(){
         try {
             Path jarPath = Paths.get(getClass().getProtectionDomain().getCodeSource().getLocation().toURI()).getParent();
@@ -363,6 +409,12 @@ public class ServerLauncher {
         }
     }
 
+    /**
+     * Deletes the current local game save file.
+     *
+     * @return {@code true} if the save file is deleted successfully,
+     *         {@code false} otherwise.
+     */
     private boolean deleteSave(){
         try{
             Path jarPath = Paths.get(getClass().getProtectionDomain().getCodeSource().getLocation().toURI()).getParent();