# Assignment Specification: TCP Concurrent Multi-Client Even/Odd Game Server (Java)

**Course:** Distributed Computing & Computer Systems  
**Evaluation Standard:** Concurrent Socket Systems Programming & Wire Protocol Framing  
**Module:** SiPro SocketArena™ & SecureProctor™  
**Assignment Question:** Question 2 (Q2) — Concurrent Even/Odd Game Server  
**Language:** Java (SE 11+)  
**Author:** SiPro Technologies Systems Engineering  

---

## 1. Executive Summary & Objective

In this assignment (**Question 2**), students implement a **Concurrent Multi-Client TCP Server and Client** for a real-time **Even/Odd Game** over raw TCP/IP sockets in **Java**.

Unlike single-threaded iterative servers that process requests one-by-one, this server implements a **multi-client concurrent architecture**:
1. The **Master Listener Thread** accepts incoming connections on port `9098` using `ServerSocket`.
2. For each connecting client, the server **forks / spawns a dedicated worker thread** (`new Thread(new ClientHandler(clientSocket))`) to isolate each player's session and handle concurrent gameplay independently.
3. The client selects an integer number (1–10) and guesses whether the final sum will be **"EVEN"** or **"ODD"**.
4. The server generates its own pseudo-random integer (1–10), calculates the total sum:
   $$\text{Sum} = \text{ClientNumber} + \text{ServerNumber}$$
5. The server checks the parity of the sum ($\text{Sum} \pmod 2 = 0$). If the actual parity matches the client's guess, the client **WINS**; otherwise, the client **LOSES**.
6. The server transmits the evaluated outcome back across the socket stream.

---

## 2. System Architecture & Concurrency Sequence

```mermaid
sequenceDiagram
    autonumber
    actor C1 as Client 1 (Alice)
    actor C2 as Client 2 (Bob)
    participant Master as Master Server (Port 9098)
    participant W1 as Worker Thread 1 (Alice)
    participant W2 as Worker Thread 2 (Bob)

    C1->>Master: TCP SYN (Port 9098)
    Master-->>C1: TCP SYN-ACK
    Master->>W1: Spawn new Thread(new ClientHandler(C1))
    W1-->>C1: READY RFC-SIPRO-EVENODD Server v1.0
    
    C2->>Master: TCP SYN (Port 9098)
    Master-->>C2: TCP SYN-ACK
    Master->>W2: Spawn new Thread(new ClientHandler(C2))
    W2-->>C2: READY RFC-SIPRO-EVENODD Server v1.0

    C1->>W1: PLAY Alice
    W1-->>C1: WELCOME Alice Pick number (1-10) and guess (EVEN|ODD)

    C2->>W2: PLAY Bob
    W2-->>C2: WELCOME Bob Pick number (1-10) and guess (EVEN|ODD)

    Note over C1,W1: Client 1 picks 4 and guesses "EVEN"
    C1->>W1: GUESS 4 EVEN
    Note over W1: Server picks random 2.<br/>Sum = 4 + 2 = 6 (EVEN).<br/>Guess matches -> WIN!
    W1-->>C1: RESULT WIN 4 2 6 EVEN Congratulations! 6 is EVEN.

    Note over C2,W2: Client 2 picks 5 and guesses "EVEN"
    C2->>W2: GUESS 5 EVEN
    Note over W2: Server picks random 2.<br/>Sum = 5 + 2 = 7 (ODD).<br/>Guess does not match -> LOSS!
    W2-->>C2: RESULT LOSS 5 2 7 ODD Sorry! 7 is ODD.
```

---

## 3. Protocol Specification: RFC-SIPRO-EVENODD

Communication is conducted using line-delimited (`\n`) ASCII stream frames.

### Client to Server Messages:
| Command | Syntax | Description | Example |
| :--- | :--- | :--- | :--- |
| `PLAY` | `PLAY <playerName>` | Client registration packet | `PLAY Alice` |
| `GUESS` | `GUESS <number> <EVEN\|ODD>` | Number choice (1–10) and parity guess | `GUESS 4 EVEN` |
| `QUIT` | `QUIT` | Gracefully end session and close socket | `QUIT` |

### Server to Client Messages:
| Command | Syntax | Description | Example |
| :--- | :--- | :--- | :--- |
| `READY` | `READY <info>` | Connection greeting and protocol version | `READY RFC-SIPRO-EVENODD Server` |
| `WELCOME` | `WELCOME <name> <instructions>` | Player acknowledged with instructions | `WELCOME Alice Pick a number...` |
| `RESULT` | `RESULT <WIN\|LOSS> <cNum> <sNum> <sum> <parity> <msg>` | Outcome frame with full calculation | `RESULT WIN 4 2 6 EVEN Won!` |
| `ERROR` | `ERROR <reason>` | Invalid syntax or out-of-range number | `ERROR Number must be 1..10` |
| `BYE` | `BYE <message>` | Acknowledgment before socket closure | `BYE Thanks for playing!` |

---

## 4. Fill-In-The-Blanks Breakdown & Evaluation Rubric (100 Marks)

### Section A: Server Implementation (`EvenOddServer.java`) [50 Marks]
- **Blank 1 (5 Marks):** Master `ServerSocket` creation on port 9098.
- **Blank 2 (5 Marks):** Address reuse flag (`setReuseAddress(true)`).
- **Blank 3 (5 Marks):** Socket binding to local host endpoint (`bind(new InetSocketAddress(PORT))`).
- **Blank 4 (5 Marks):** Incoming connection accept loop (`serverSocket.accept()`).
- **Blank 5 (5 Marks):** Spawn/fork dedicated client worker thread (`new Thread(new ClientHandler(clientSocket)).start()`).
- **Blank 6 (5 Marks):** Command token format verification (`tokens.length == 3`).
- **Blank 7 (5 Marks):** Number range (1–10) and parity string validation ("EVEN" or "ODD").
- **Blank 8 (5 Marks):** Server random integer generation (`random.nextInt(10) + 1`).
- **Blank 9 (5 Marks):** Parity calculation (`(sum % 2 == 0) ? "EVEN" : "ODD"`).
- **Blank 10 (5 Marks):** Graceful socket closure & stream teardown (`clientSocket.close()`).

### Section B: Client Implementation (`EvenOddClient.java`) [40 Marks]
- **Blank 1 (5 Marks):** TCP stream client `Socket` initialization.
- **Blank 2 (5 Marks):** Server connection handshake (`socket.connect(...)`).
- **Blank 3 (5 Marks):** `BufferedReader` stream construction.
- **Blank 4 (5 Marks):** Auto-flushing `PrintWriter` stream construction.
- **Blank 5 (5 Marks):** `PLAY` registration packet serialization.
- **Blank 6 (5 Marks):** User input prompt & `GUESS <number> <parity>` transmission.
- **Blank 7 (5 Marks):** Server `RESULT` frame reading and parsing.
- **Blank 8 (5 Marks):** Clean socket termination on `QUIT` or exit.

### Section C: Concurrency & Stress Testing [10 Marks]
- **Multi-Client Concurrency (5 Marks):** Verified that 3+ concurrent clients can play simultaneously without blocking each other.
- **Clean Disconnection (5 Marks):** Verified that if one client disconnects, the server worker thread terminates cleanly without affecting other active sessions.

---

## 5. Compilation & Execution Instructions

### Terminal 1: Compile & Start the Concurrent Even/Odd Server
```bash
javac EvenOddServer.java
java EvenOddServer
```

### Terminal 2: Connect Player 1 (Alice)
```bash
javac EvenOddClient.java
java EvenOddClient Alice
```

### Terminal 3: Connect Player 2 (Bob)
```bash
java EvenOddClient Bob
```