# Interface VirtualServer

All Superinterfaces:
  `Remote`

All Known Implementing Classes:
  `RmiServer`, `SocketServer`, `SocketServerHandler`

public interface VirtualServer extends Remote
This interface defines the methods for server-side operations that can be invoked remotely by a client. It serves as a generic representation of the server, allowing different underlying communication technologies (RMI, Socket) to implement it.

Methods declared in this interface are expected to throw `Exception` to signal any issues that prevent the successful completion of the operation. These exceptions can arise from low-level network communication failures or from application-level logical errors encountered during the execution of the requested operation on the server.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `abandonRace(UUID clientId)`
  Notifies the server that a client is abandoning the race, removing them from the active game.
  `void`
  `attachComponent(Component component, int x, int y, UUID clientId)`
  Requests the server to attach a component to the client's ship at specified coordinates.
  `void`
  `connect(VirtualView client)`
  Connects a new client's virtual view to the server.
  `void`
  `createGame(UUID id)`
  Requests the server to create a new game instance.
  `void`
  `drawCard(UUID clientId)`
  Requests the server to draw a card for the specified client.
  `void`
  `drawFaceDownComponent(UUID clientId)`
  Requests the server to draw a face-down component for the specified client.
  `void`
  `drawFaceUpComponent(int index, UUID clientId)`
  Requests the server to draw a face-up component at a specific index for the specified client.
  `void`
  `drawFromReserved(int index, UUID clientId)`
  Requests the server to draw a component from the reserved pile at a specific index.
  `void`
  `endAssemblePhase(UUID clientId)`
  Notifies the server that the assembling phase for the specified client has ended.
  `void`
  `endCrewPlacingPhase(UUID clientId)`
  Notifies the server that the crew placing phase for the specified client has ended.
  `void`
  `getFaceUpComponentList(UUID clientId)`
  Requests the server to send the current list of face-up components.
  `void`
  `getSubDeck(UUID clientId, int index)`
  Requests the server to send a specific sub-deck of cards.
  `void`
  `increment(UUID clientId)`
  Increments a counter used to trace clients' disconnections.
  `void`
  `joinGame(UUID id, int game)`
  Requests the server to join an existing game.
  `void`
  `leaveGame(UUID clientId)`
  Notifies the server that a client is leaving the game.
  `void`
  `ping(UUID clientId)`
  Sends a ping to the server for connection testing.
  `void`
  `placeCrewMember(UUID clientId, int x, int y, AlienColor a)`
  Requests the server to place a crew member or an alien of a given color at specified coordinates on the ship.
  `void`
  `placeRocket(UUID clientId, int position)`
  Requests the server to place the client's rocket at a specific position on the track.
  `void`
  `putDownComponent(Component component, UUID clientId)`
  Requests the server to put down a component.
  `void`
  `removeComponent(UUID clientId, int x, int y)`
  Requests the server to remove a component from the client's ship at specified coordinates.
  `void`
  `rollDice(UUID clientId)`
  Requests the server to roll the dice.
  `void`
  `setCardContext(UUID clientId, Map<String,Object> context)`
  Sets the context for a card effect on the server.
  `void`
  `setEffectContext(UUID clientId, Map<String,Object> context)`
  Sets the context for a card effect on the server.
  `void`
  `setGameLevel(UUID clientId, int level)`
  Sets the game level on the server.
  `void`
  `setMaxPlayers(UUID clientId, int maxPlayers)`
  Sets the maximum number of players allowed for a game on the server.
  `void`
  `setNickname(String nickname, UUID clientId)`
  Sets the nickname for the specified client on the server.
  `void`
  `showShip(UUID clientId, String nickname)`
  Requests the server to send the ship of a specific player to the requesting client.
  `void`
  `startFinalHourGlass(UUID clientId)`
  Requests the server to start the final hourglass timer.
  `void`
  `startHourGlass(UUID clientId)`
  Requests the server to start a standard hourglass timer.
  `void`
  `viewGame(UUID clientId)`
  Requests the server to send the list of available games that the client can join.

- ## Method Details

  - ### connect

    void connect(VirtualView client) throws Exception
    Connects a new client's virtual view to the server.
    Parameters:
      `client` - The `VirtualView` instance representing the client's view.
    Throws:
      `Exception`

  - ### leaveGame

    void leaveGame(UUID clientId) throws Exception
    Notifies the server that a client is leaving the game.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### drawCard

    void drawCard(UUID clientId) throws Exception
    Requests the server to draw a card for the specified client.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### drawFaceDownComponent

    void drawFaceDownComponent(UUID clientId) throws Exception
    Requests the server to draw a face-down component for the specified client.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### drawFaceUpComponent

    void drawFaceUpComponent(int index, UUID clientId) throws Exception
    Requests the server to draw a face-up component at a specific index for the specified client.
    Parameters:
      `index` - The index of the face-up component to draw from the display.
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### attachComponent

    void attachComponent(Component component, int x, int y, UUID clientId) throws Exception
    Requests the server to attach a component to the client's ship at specified coordinates.
    Parameters:
      `component` - The `Component` to attach.
      `x` - The row on the ship's grid where the component should be placed.
      `y` - The column on the ship's grid where the component should be placed.
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### setNickname

    void setNickname(String nickname, UUID clientId) throws Exception
    Sets the nickname for the specified client on the server.
    Parameters:
      `nickname` - The nickname to set.
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### setCardContext

    void setCardContext(UUID clientId, Map<String,Object> context) throws Exception
    Sets the context for a card effect on the server. This method is used to perform an action that may/must be performed before the card's effect takes place.
    Parameters:
      `clientId` - The ID of the client.
      `context` - A map containing key-value pairs relevant to the card effect's resolution.
    Throws:
      `Exception`

  - ### setEffectContext

    void setEffectContext(UUID clientId, Map<String,Object> context) throws Exception
    Sets the context for a card effect on the server. This method is used to provide additional parameters needed to resolve a card's effect.
    Parameters:
      `clientId` - The ID of the client.
      `context` - A map containing key-value pairs relevant to the effect's resolution.
    Throws:
      `Exception`

  - ### endAssemblePhase

    void endAssemblePhase(UUID clientId) throws Exception
    Notifies the server that the assembling phase for the specified client has ended. This signals that the client has finished arranging components on their ship.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### setMaxPlayers

    void setMaxPlayers(UUID clientId, int maxPlayers) throws Exception
    Sets the maximum number of players allowed for a game on the server. This method is typically called by the game creator.
    Parameters:
      `clientId` - The ID of the client setting the maximum players.
      `maxPlayers` - The maximum number of players for the game.
    Throws:
      `Exception`

  - ### setGameLevel

    void setGameLevel(UUID clientId, int level) throws Exception
    Sets the game level on the server.
    Parameters:
      `clientId` - The ID of the client setting the game level.
      `level` - The game level to set.
    Throws:
      `Exception`

  - ### showShip

    void showShip(UUID clientId, String nickname) throws Exception
    Requests the server to send the ship of a specific player to the requesting client.
    Parameters:
      `clientId` - The ID of the client requesting to view the ship.
      `nickname` - The nickname of the player whose ship is to be shown.
    Throws:
      `Exception`

  - ### rollDice

    void rollDice(UUID clientId) throws Exception
    Requests the server to roll the dice.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### putDownComponent

    void putDownComponent(Component component, UUID clientId) throws Exception
    Requests the server to put down a component.
    Parameters:
      `component` - The `Component` to put down.
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### getFaceUpComponentList

    void getFaceUpComponentList(UUID clientId) throws Exception
    Requests the server to send the current list of face-up components.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### drawFromReserved

    void drawFromReserved(int index, UUID clientId) throws Exception
    Requests the server to draw a component from the reserved pile at a specific index.
    Parameters:
      `index` - The index of the component in the reserved pile to draw.
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### getSubDeck

    void getSubDeck(UUID clientId, int index) throws Exception
    Requests the server to send a specific sub-deck of cards.
    Parameters:
      `clientId` - The ID of the client.
      `index` - The index of the sub-deck to retrieve.
    Throws:
      `Exception`

  - ### placeRocket

    void placeRocket(UUID clientId, int position) throws Exception
    Requests the server to place the client's rocket at a specific position on the track.
    Parameters:
      `clientId` - The ID of the client.
      `position` - The position on the game track where the rocket should be placed.
    Throws:
      `Exception`

  - ### endCrewPlacingPhase

    void endCrewPlacingPhase(UUID clientId) throws Exception
    Notifies the server that the crew placing phase for the specified client has ended. This signals that the client has finished placing crew members.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### placeCrewMember

    void placeCrewMember(UUID clientId, int x, int y, AlienColor a) throws Exception
    Requests the server to place a crew member or an alien of a given color at specified coordinates on the ship.
    Parameters:
      `clientId` - The ID of the client.
      `x` - The x-coordinate (row) on the ship's gameboard where the crew member should be placed.
      `y` - The y-coordinate (column) on the ship's gameboard where the crew member should be placed.
      `a` - The `AlienColor` of the crew member to place.
    Throws:
      `Exception`

  - ### startHourGlass

    void startHourGlass(UUID clientId) throws Exception
    Requests the server to start a standard hourglass timer.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### startFinalHourGlass

    void startFinalHourGlass(UUID clientId) throws Exception
    Requests the server to start the final hourglass timer.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### abandonRace

    void abandonRace(UUID clientId) throws Exception
    Notifies the server that a client is abandoning the race, removing them from the active game.
    Parameters:
      `clientId` - The ID of the client abandoning the race.
    Throws:
      `Exception`

  - ### ping

    void ping(UUID clientId) throws Exception
    Sends a ping to the server for connection testing.
    Parameters:
      `clientId` - The ID of the client sending the ping.
    Throws:
      `Exception` - if a remote communication error occurs.

  - ### createGame

    void createGame(UUID id) throws Exception
    Requests the server to create a new game instance.
    Parameters:
      `id` - The ID of the client creating the game.
    Throws:
      `Exception`

  - ### viewGame

    void viewGame(UUID clientId) throws Exception
    Requests the server to send the list of available games that the client can join.
    Parameters:
      `clientId` - The ID of the client.
    Throws:
      `Exception`

  - ### joinGame

    void joinGame(UUID id, int game) throws Exception
    Requests the server to join an existing game.
    Parameters:
      `id` - The ID of the client joining the game.
      `game` - The ID of the game to join.
    Throws:
      `Exception`

  - ### removeComponent

    void removeComponent(UUID clientId, int x, int y) throws Exception
    Requests the server to remove a component from the client's ship at specified coordinates.
    Parameters:
      `clientId` - The ID of the client.
      `x` - The row of the component to remove.
      `y` - The column of the component to remove.
    Throws:
      `Exception`

  - ### increment

    void increment(UUID clientId) throws Exception
    Increments a counter used to trace clients' disconnections.
    Parameters:
      `clientId` - the ID of the client whose value needs to be incremented
    Throws:
      `Exception` - if the increment operation fails or if the client ID is invalid