Merge pull request #36 from rubenpirreram/Javadoc-for-Game

Javadoc-for-Game

src/main/java/it/polimi/ingsw/gc14/Model/Game.java

@@ -17,50 +17,139 @@ import it.polimi.ingsw.gc14.Model.GamePackage.GameStages;
 import java.io.Serializable;
 import java.util.*;
 import java.util.stream.Collectors;
-
+import it.polimi.ingsw.gc14.Network.Observer;
+/**
+ * Represents the main game model.
+ * A Game object stores the players, the current state of the match,
+ * the slot assignments, the board, and the logic required to manage the game flow.
+ */
 public class Game implements Serializable {
 
+    private transient List<Observer> observers = new ArrayList<>(); // transient! non serializzare
+
+    public void addObserver(Observer observer) {
+        observers.add(observer);
+    }
+
+    private void notifyObservers() {
+        for (Observer o : observers) {
+            o.update(this);
+        }
+    }
+
+    /**
+     * The list of players participating in the game.
+     */
     private ArrayList<Player> playersList;
+
+    /**
+     * The current state of the game.
+     */
     private CurrentState currentState;
+
+    /**
+     * The mapping between slots and the players assigned to them.
+     */
     private HashMap<Slot,Player> slotMap;
+
+    /**
+     * The configured number of players for this game.
+     */
     private int nPlayers;
+
+    /**
+     * The queue of players involved in optional card resolution.
+     */
     private Queue<Player> OptionalCardQueue;
+
+    /**
+     * The order logic card associated with this game.
+     */
     private OrderLogicCard orderLogicCard;
+
+    /**
+     * The board associated with this game.
+     */
     private Board board;
 
-
+    /**
+     * Returns clones of the upper tribe cards currently available on the board.
+     *
+     * @return a list containing clones of the upper tribe cards currently available on the board.
+     */
     public List<TribeCard>getUpperListTribeCards() {
         List<TribeCard> cards = new ArrayList<>();
         board.upperListTribe.forEach(x->cards.add(x.clone()));
         return cards;
     }
+
+    /**
+     * Returns clones of the lower tribe cards currently available on the board.
+     *
+     * @return a list containing clones of the lower tribe cards currently available on the board.
+     */
     public List<TribeCard>getLowerListTribeCards() {
         List<TribeCard> cards = new ArrayList<>();
         board.lowerListTribe.forEach(x->cards.add(x.clone()));
         return cards;
     }
+
+    /**
+     * Returns clones of the upper building cards currently available on the board.
+     *
+     * @return a list containing clones of the upper building cards currently available on the board.
+     */
     public List<BuildingCard>getUpperListBuilding() {
         List<BuildingCard> cards = new ArrayList<>();
         board.upperListBuilding.forEach(x->cards.add(x.clone()));
         return cards;
     }
+
+    /**
+     * Returns clones of the lower building cards currently available on the board.
+     *
+     * @return a list containing clones of the lower building cards currently available on the board.
+     */
     public List<BuildingCard>getLowerListBuilding() {
         List<BuildingCard> cards = new ArrayList<>();
         board.lowerListBuilding.forEach(x->cards.add(x.clone()));
         return cards;
     }
+
+    /**
+     * Returns the current state of the game.
+     *
+     * @return the current state of the game.
+     */
     public CurrentState getCurrentState() {
         return currentState;
     };
 
+    /**
+     * Returns the player with the specified username, if present.
+     *
+     * @param Username the username of the player to search for.
+     * @return the player with the specified username, or {@code null} if no such player exists.
+     */
     public Player getPlayerByUsername(String Username) throws IndexOutOfBoundsException {
         return playersList.stream().filter(x->x.getUserName().equals(Username)).findFirst().orElse(null);
     }
 
-
+    /**
+     * Returns the configured number of players for this game.
+     *
+     * @return the configured number of players for this game.
+     */
     public int getNPlayers() {
         return nPlayers;
     }
+
+    /**
+     * Creates a game with the specified number of players.
+     *
+     * @param nPlayers the configured number of players for the game.
+     * @throws IllegalArgumentException if {@code nPlayers < 0} or {@code nPlayers > 5}.
+     */
     public Game(int nPlayers) throws IllegalArgumentException{
         if(nPlayers < 0||nPlayers > 5)
             throw new IllegalArgumentException();
@@ -75,11 +164,24 @@ public class Game implements Serializable {
         playersList = new ArrayList<>();
         OptionalCardQueue = new LinkedList<>();
     }
+
+    /**
+     * Creates a game with 0 configured players.
+     */
     public Game()
     {
         this(0);
     }
 
+    /**
+     * Attempts to add the specified player to the game.
+     * The operation succeeds only if the configured number of players is not 0,
+     * the current game stage is {@code WAITING}, and the player is not already present.
+     * If the number of players reaches the configured maximum, the game is initialized.
+     *
+     * @param player the player to add to the game.
+     * @return {@code true} if the player is successfully added, {@code false} otherwise.
+     */
     public boolean addPlayer(Player player) {
         if(this.nPlayers==0)
         {
@@ -96,6 +198,12 @@ public class Game implements Serializable {
         }
         return true;
     }
+
+    /**
+     * Initializes the game after all required players have been added.
+     * The method creates the appropriate order logic card according to the number of players,
+     * selects the first current player, and updates the game stage to {@code SLOT_CHOICE}.
+     */
     public void init() {
 
         switch (nPlayers) {
@@ -116,7 +224,18 @@ public class Game implements Serializable {
         currentState.GameStageUpdate(GameStages.SLOT_CHOICE);
     }
 
-    //region Cotroller Methods
+    //region Controller Methods
+
+    /**
+     * Attempts to assign the slot at the specified index to the specified player.
+     * The operation succeeds only if the index is valid, the current game stage is {@code SLOT_CHOICE},
+     * the specified player is the current player, and the selected slot is not already assigned.
+     * If the slot is successfully assigned, the next player setup is triggered.
+     *
+     * @param player the player performing the slot choice.
+     * @param slotIndex the index of the selected slot.
+     * @return {@code true} if the slot choice succeeds, {@code false} otherwise.
+     */
     public boolean SlotChoiceByIndex(Player player, int slotIndex) {
         if(slotIndex<0 || slotIndex>=slotMap.size())
             return  false;
@@ -140,6 +259,20 @@ public class Game implements Serializable {
     }
 
     //region Drawing Methods
+
+    /**
+     * Attempts to draw the upper tribe card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one upper card draw is still available,
+     * and the selected tribe card is not an event card.
+     * If successful, the card is inserted into the player's collection, removed from the board,
+     * and the number of remaining upper draws is decremented.
+     * If both upper and lower draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the upper tribe card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawUpperTribeCardByIndex(Player player,int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.upperListTribe.size())
             return false;
@@ -166,6 +299,20 @@ public class Game implements Serializable {
         return true;
 
     }
+
+    /**
+     * Attempts to draw the lower tribe card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one lower card draw is still available,
+     * and the selected tribe card is not an event card.
+     * If successful, the card is inserted into the player's collection, removed from the board,
+     * and the number of remaining lower draws is decremented.
+     * If both lower and upper draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the lower tribe card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawLowerTribeCardByIndex(Player player, int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.lowerListTribe.size())
             return false;
@@ -195,6 +342,18 @@ public class Game implements Serializable {
 
     }
 
+    /**
+     * Attempts to draw the upper building card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one upper card draw is still available,
+     * and the selected building card can be bought by the player.
+     * If successful, the building card is removed from the board and the number of remaining upper draws is decremented.
+     * If both upper and lower draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the upper building card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawUpperBuildingCardByIndex(Player player,int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.upperListBuilding.size())
             return false;
@@ -221,6 +380,19 @@ public class Game implements Serializable {
 
         return true;
     }
+
+    /**
+     * Attempts to draw the lower building card at the specified index for the specified player.
+     * The operation succeeds only if the index is valid, the game stage is {@code RESOLVING_ACTIONS},
+     * the specified player is the current player, at least one lower card draw is still available,
+     * and the selected building card can be bought by the player.
+     * If successful, the building card is removed from the board and the number of remaining lower draws is decremented.
+     * If both lower and upper draws become zero, the next player setup is triggered.
+     *
+     * @param player the player performing the draw.
+     * @param cardIndex the index of the lower building card to draw.
+     * @return {@code true} if the draw succeeds, {@code false} otherwise.
+     */
     public boolean DrawLowerBuildingCardByIndex(Player player,int cardIndex) {
         if( cardIndex<0 || cardIndex >=board.lowerListBuilding.size())
             return false;

src/main/java/it/polimi/ingsw/gc14/Network/Observer.java

@@ -0,0 +1,7 @@
+package it.polimi.ingsw.gc14.Network;
+
+import it.polimi.ingsw.gc14.Model.Game;
+
+public interface Observer {
+    public void update(Game model);
+}