TCPChat: Multi-Machine Chatroom

Terminal-based TCP chat application with Client-Server Architecture and extensive error handling. Real-time communication between multiple clients works on single machine or with multiple machines on same home network.

📋 Table of Contents

• TCPChat: Multi-Machine Chatroom
  • 📋 Table of Contents
  • ✨ Features
    • 🏗️ Architecture: Client-Server Model
  • 🏗️ File Architecture
  • 🚀 Local development setup & usage
    • 📦 Requirements
    • 🎮 Commands
  • 🎲 Chat Session Examples
  • 📄 License
    • 👤 Author
  • 🔧 Technical Details

✨ Features

🎯 Real-time messaging between numerous connected clients in the terminal
🎯 Broadcast messaging to all connected clients
🎯 Connection notifications when users join or leave
🎯 Client commands
🎯 Extensive error handling so it's nearly foolproof
🎯 Cross-platform (Windows, macOS, and Linux)

(back to table of contents)

🏗️ Architecture: Client-Server Model

 CLIENT 1                    SERVER                    CLIENT 2
    |                          |                          |
    |-------- connect -------->|<------- connect ---------|
    |                          |                          |
    |------ send message ----->|                          |
    |                          |------ broadcast -------->|
    |<----- broadcast ---------|<----- send message ------|
    |                          |                          |

(back to table of contents)

🏗️ File Architecture

TCPChat/
├── tcpchat/                           # Java package containing source code
│   ├── Client.java                    # Client-side implementation
│   └── Server.java                    # Server-side implementation
├── docs/                              # Auto-generated Javadoc documentation
│   └── (Javadoc generated files)
├── images/                            # README assets (screenshots, diagrams)
├── LICENSE.txt                        # CC BY-NC-ND 4.0 license file
├── CITATION.cff                       # Citation metadata with ORCID reference
└── README.md

(back to table of contents)

🚀 Local development setup & usage

【 Clone or download the project 】
$ git clone https://github.com/Jenspi/TCPChat
$ cd tcpchat

【 Compilation 】
$ javac tcpchat/Server.java
$ javac tcpchat/Client.java

【 Server 】
# 3a. Start the Server on a custom port:
$ java tcpchat.Server 3000                         # 3000 = desired port

# 3b. Start the Server on the default port (5000): 
$ java tcpchat.Server
# Note: This port number may already be taken by other processes on the machine if the user already has something running with *Vite*, *Expo*, etc.

【 Client 】
# 4a. Connecting Clients on the same machine (localhost):
$ java tcpchat.Client localhost 3000               # 3000 = desired port

# 4b. Connecting Clients on different machines (use Server's IP address; see below):
$ java tcpchat.Client 192.168.1.100 3000           # 3000 = desired port

# 4c. Connecting Clients using defaults (localhost, port 5000):
$ java tcpchat.Client

【 Finding your IP address for connecting to a custom server address 】
# Finding Your SERVER IP Address onmacOS/Linux:
$ ifconfig | grep "inet " | grep -v 127.0.0.1

# Finding Your SERVER IP Address on Windows:
$ ipconfig
# Look for "IPv4 Address" under your active network adapter.

【 Javadoc Generation 】
$ javadoc -d docs -author -version Client.java Server.java

📦 Requirements

• Java JDK 8 or higher
• Network connectivity (same home network and/or accessible IP addresses)
• Available ports (default: 5000)

🎮 Commands

Command	Description
bye	Disconnect from the chat server gracefully
allusers	Display list of all currently connected users
help	Show available commands

(back to table of contents)

🎲 Chat Session Examples

TCPChat 1.0 Example A: Server with 2 Clients connected, both on same machine.

TCPChat 1.0 Example B: Server with 2 Clients connected, one on different machine (hard to read, sorry).

(back to table of contents)

📄 License

Updated December 7, 2025.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International License.

👤 Author

Jenny Spicer / Jennifer Spicer

(back to table of contents)

🔧 Technical Details

🧵 Concurrency & Multithreading
✅ Multithreaded Server: Thread-per-client model - dedicated ServerHandler thread spawned for each connection
✅ Concurrent Message Handling: Multiple clients send/receive messages simultaneously without blocking
✅ Asynchronous I/O: Separate threads for reading and writing enable full-duplex communication
✅ Thread Lifecycle Management: Threads created on connection, gracefully terminated on disconnect
✅ Thread-Safe Collections: Uses HashMap for client storage (consider ConcurrentHashMap for production)

🛜 Networking
✅ TCP/IP Socket Programming: Connection-oriented protocol with automatic 3-way handshake (handled by Java Socket API)
✅ Client-Server Architecture: Centralized server coordinates all client communication
✅ Full-Duplex Communication: Simultaneous bidirectional data flow between server and clients
✅ Persistent Connections: Sockets remain open until client sends "bye" command

🗃️ Data Structures
✅ HashMap Storage: HashMap<String, Socket> maps username → client socket for O(1) lookup
✅ Output Stream Cache: HashMap<String, DataOutputStream> maps username → output stream for efficient broadcasting and prevents the need to recreate threads
⚠️ Thread Safety Note: Should upgrade to ConcurrentHashMap instead of HashMap for thread-safe client storage

📣 I/O Streams
🗣️ Client → Server: DataOutputStream → DataInputStream
📢 Server → Client: DataOutputStream (broadcast to all)
🗣️ User Input: BufferedReader reading from System.in

💬 Message Format
YYYY/MM/DD HH:MM:SS [Username]: Message content

💬 Example:
2025/12/08 15:30:45 [Batman27]: Hello.

(back to table of contents)

---

Caution

This is a learning project demonstrating TCP socket programming, multithreading, and client-server architecture in Java. It is not production-ready and lacks security features required for real-world applications.