Skip to content
Tutorials Center
My learning

Topics

Lesson 182 of 201 ยท Projects

Project: Multi-Client Chat Server

Build a multi-client chat server in Java with ServerSocket and a virtual thread per client - nicknames, private messages, commands, broadcasting and clean shutdown.

A chat server is the "hello world" of network programming, and a surprisingly complete exercise. Many clients connect at once, each one waits for input at its own pace, and every message has to reach everyone else without lines getting mixed up. You need a protocol, shared state that many threads update at the same time, and a plan for clients that vanish without saying goodbye.

In this project you'll build a TCP chat server with nicknames, private messages, /me actions, a /who list and a clean shutdown. It serves every client on its own virtual thread, which makes the code look like simple blocking I/O while scaling to thousands of connections. Everything runs here: each program starts the server on 127.0.0.1 and connects several clients to it in the same program, so you can watch a whole conversation from every participant's point of view. At the end you'll get a standalone server and a console client to run in a few terminal windows on your own computer.

Before you start, it helps to have read Sockets (TCP, ServerSocket, reading and writing lines) and Virtual Threads. The project also uses sealed interfaces, records, ConcurrentHashMap, atomic variables and synchronization.

The protocol

Client and server talk in lines of UTF-8 text, one message per line. That's the simplest protocol that works, and it means you can even chat with tools like nc (netcat) or telnet. Lines that start with / are commands:

Client sends Everyone sees Notes
hello <Ana> hello A normal message goes to everyone, including the sender
/me waves * Ana waves An action
/nick Ana * guest1 is now known as Ana New clients start as guest1, guest2, ...
/msg bo psst only Bo: [Ana -> you] psst A private message; the sender gets a copy
/who only the sender: * Online: Ana, Bo
/quit * Ana left The server says goodbye and closes the connection
//etc <Ana> /etc Two slashes send a line that starts with /

Lines from the server that start with * are announcements, and lines that start with ! are errors meant only for you. Splitting the protocol out like this, before writing any socket code, makes every later stage easier: the parsing and the room logic can be tested without a network.

Stage 1: parsing commands

Each line becomes a Command. There's a fixed set of command kinds, each with its own data, so they're records inside a sealed interface. Nesting the records in the interface (see Nested interfaces) gives them names like Command.Say and Command.Nick and keeps the whole protocol in one place. Invalid input isn't an exception here: it's just another kind of command, Invalid, carrying the reason. Users make typos all the time, and a typo isn't exceptional.

Java Stage 1: turning lines into commands

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

/WHO works because command names are lower-cased with Locale.ROOT. //etc/hosts is a file becomes a normal message that starts with one slash. The 501-character line is rejected: a server must limit line length, or one client could send a gigabyte "line" and use up its memory.

The describe method is the shape of the server's main loop: a switch over the sealed interface with one record pattern per command and no default. If you later add record Kick(String name) to the protocol, every such switch stops compiling until it handles kicking. That's the main reason to model a protocol as a sealed hierarchy (see Pattern Matching).

Stage 2: the chat room

The room is the server's shared state: who's online, under which name, and what each command does. It knows nothing about sockets. It talks to clients through a tiny interface, Connection, with send(line) and close(). On the real server, a connection writes to a socket. In this stage it's a fake that just collects lines in a list, so you can run a whole conversation in a single thread and read each participant's screen afterwards.

Java Stage 2: the room logic, tested with fake connections

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Read the three screens. Bo's attempt to take the name ana fails because names are compared case-insensitively, and b! is rejected by the name pattern. The private message reaches only Bo, and the sender gets a copy. Ana's own screen ends with * Bye, Ana!, while everyone else sees * Ana left.

The last line of the output is the important one for a server: 100 clients asked for the name star at exactly the same moment, on 100 virtual threads, and exactly one got it. Here's why that works, and the other concurrency decisions in ChatRoom:

  • putIfAbsent claims a name atomically. It checks and inserts in one step, so two threads can never both see "free" and both take it. The obvious version, if (!members.containsKey(name)) members.put(name, member), has a gap between the check and the put, and under load two clients would end up with the same name. See Concurrent Collections.
  • The map key is the lower-case name (with Locale.ROOT), so Ana and ana collide, while the member remembers the spelling the user chose.
  • remove(key, member) removes the entry only if it still belongs to this member. A plain remove(key) could delete someone else's entry if the name had changed hands in between.
  • name is volatile. It's written by the member's own thread on /nick and read by other threads when they broadcast or answer /who. volatile guarantees those threads see the new name.
  • Guest numbers come from an AtomicInteger, so two clients connecting at once can't both become guest7. And if a user has already taken the name guest8 with /nick, join simply tries the next number.
  • Broadcasting iterates members.values() while other threads join and leave. A HashMap would throw ConcurrentModificationException, or worse, corrupt itself. ConcurrentHashMap iterators are weakly consistent: they never throw, and see a member that joins mid-broadcast either fully or not at all.

Stage 3: sockets and a virtual thread per client

Now the network. Before connecting the full room, it's worth seeing the bare minimum: a server that sends every line from any client to all clients. It's about 60 lines, and every networked server you'll ever write has the same skeleton:

  1. A ServerSocket waits for connections in an accept loop.
  2. Each accepted Socket gets its own thread, which loops on readLine() until the client hangs up.
  3. Shared state (here, the set of output streams) is a concurrent collection.

The server binds to the loopback address (127.0.0.1), so only programs on the same machine can connect, and to port 0, which lets the operating system pick any free port. The output starts with that port number, so it changes from run to run.

The three clients live in the same program. Each one has a virtual thread that reads incoming lines into a queue, and the test waits for specific lines with expect(...) before taking the next step. Without those waits the program would race ahead of the network, and messages would arrive in a different order each run.

Java Stage 3: a minimal broadcast server with three clients

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

user3 sends one message and then hangs up without saying anything. On the server, its readLine() returns null, the loop ends, and everyone else is told user3 left. Look at the transcripts: user1 has seen everything since it joined, user2 everything since user2 joined, and user3 never saw its own departure.

The lines that matter:

  • Executors.newVirtualThreadPerTaskExecutor() starts a new virtual thread for every submit. A blocked readLine() parks the virtual thread cheaply instead of holding an operating-system thread, so 10,000 idle clients cost about as much memory as 10,000 small objects. With platform threads, you'd need a thread pool and would have to choose its size. Virtual Threads explains the mechanics.
  • synchronized (client) around println. Several sessions can broadcast at the same moment, and two threads writing to one stream at once could interleave their characters. Locking on the writer makes each line arrive whole. Since Java 24, a virtual thread waiting for a synchronized lock no longer pins its carrier thread, so synchronized is fine here.
  • The newcomer is added to clients before "joined" is broadcast. In the other order, a message sent right after another client saw "user3 joined" could still miss user3. Ordering steps so that the rest of the world only learns about something after it's ready is a theme in all concurrent code.
  • try (socket; ...) closes the socket and its streams however the session ends, including when the client vanishes and readLine throws SocketException. (Since Java 9, an existing variable can go in a try-with-resources header, see try-with-resources.)
  • UTF-8 everywhere. Both sides name the charset explicitly, so รฉ and emoji survive even on machines with another default.

Stage 4: the complete server

Now the real thing: the Stage 3 skeleton with the ChatRoom from Stage 2 behind it. Each session joins the room, turns every line into a Command, hands it to the room, and leaves the room in a finally block, so a crash or a vanished client can never leave a ghost member behind.

The conversation is now a script in the Input box. Each line is N: text, meaning "client N sends text". A client connects the first time it appears, and N: !drop makes it hang up without /quit, like a laptop losing Wi-Fi. After each step, the program prints what every client received, tagged [1], [2], [3]. Change the script and run it again to try your own conversation.

To keep the output in the same order on every run, the script player uses the protocol itself as a clock. After each step, it sends /ping from each client and reads until PONG comes back. The server handles each client's lines in order, so once PONG arrives, everything caused by the earlier lines has already been written to that client's socket. This trick, a request whose only job is to show that earlier requests are done, is called a barrier or sync marker, and real protocols use it too.

Java Stage 4: the complete chat server, driven by a script

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Follow the conversation in the output. Client 3 drops off the network, and the server notices because readLine() returns null; everyone else is told * guest3 left, exactly as if it had sent /quit. When the input runs out, the program closes the server, and Bo, the last one online, gets * The server is shutting down. Goodbye!.

What the final server adds:

  • SocketConnection.send is synchronized. Any session may broadcast to any connection at any moment, so each connection serializes its own writes. Each write is short, so holding the lock briefly is cheap.
  • setSoTimeout drops idle clients. A client that connects and then says nothing for 10 minutes makes readLine() throw SocketTimeoutException, the session ends, and the finally block removes the member. Without a timeout, abandoned connections would pile up forever. (A friendly client would send /ping every few minutes to stay connected.)
  • Shutdown happens in a careful order. close() first closes the ServerSocket (no new clients), then closeAll() tells every member goodbye and closes their sockets, which makes each session's blocked readLine() throw, and finally sessions.close() waits for all sessions to finish. During shutdown the room stops announcing departures with a closing flag; otherwise the clients still being closed would receive a flood of "left" messages.
  • Errors in one session stay in that session. Every exception from a client's socket is caught inside serve, so a broken connection never affects the accept loop or other clients.

Stage 5: a load test, and running it for real

Does the server hold up when everyone talks at once? This final program starts the same server and 20 bot clients on virtual threads. Each bot picks a name, waits until all bots are connected (a CountDownLatch, see Synchronizers), sends 5 messages as fast as it can, and then reads until it has received all 100 messages. Each bot also checks that messages from every other sender arrive in the order they were sent.

Java Stage 5: 20 clients talking at the same time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

All 20 bots receive all 100 messages, in order per sender, even though 20 threads broadcast simultaneously into 20 sockets. Order per sender is guaranteed because each client's lines are handled by one thread, one after another, and TCP keeps the bytes of one connection in order. Order between senders is not guaranteed: bot 3 may see bot 7's first message before bot 5's, while bot 4 sees the opposite. Chat users never notice, but it's the reason the test only checks order per sender.

To chat for real, run the server and the client below on your own computer. Start the server in one terminal, then start the client in two or three more terminal windows and talk between them:

Java
// ChatServerApp.java: run with  java ChatServerApp.java  (optionally a port number)
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.net.InetAddress;
import java.net.ServerSocket;
import java.net.Socket;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.regex.Pattern;

public class ChatServerApp {
    public static void main(String[] args) throws IOException {
        int port = args.length > 0 ? Integer.parseInt(args[0]) : 5050;
        try (ChatServer server = new ChatServer(InetAddress.getLoopbackAddress(), port)) {
            IO.println("Chat server listening on 127.0.0.1:" + server.port());
            IO.readln("Press Enter to stop the server.\n");
        }
        IO.println("Server stopped.");
    }
}

// Paste ChatServer, SocketConnection, Command, Connection and ChatRoom from Stage 4 here.

The client needs two threads, because it must wait for two things at once: lines typed on the keyboard and lines arriving from the server. Reading only the keyboard would hold back other people's messages until you pressed Enter.

Java
// ChatClient.java: run with  java ChatClient.java  (optionally host and port)
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.PrintWriter;
import java.net.Socket;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class ChatClient {
    public static void main(String[] args) throws IOException, InterruptedException {
        String host = args.length > 0 ? args[0] : "127.0.0.1";
        int port = args.length > 1 ? Integer.parseInt(args[1]) : 5050;

        try (Socket socket = new Socket(host, port);
             var fromServer = new BufferedReader(new InputStreamReader(socket.getInputStream(), StandardCharsets.UTF_8));
             var toServer = new PrintWriter(socket.getOutputStream(), true, StandardCharsets.UTF_8)) {

            // Thread 1: print everything the server sends, as soon as it arrives
            Thread printer = Thread.ofVirtual().start(() -> {
                try {
                    String line;
                    while ((line = fromServer.readLine()) != null) {
                        IO.println(line);
                    }
                } catch (IOException e) {
                    // socket closed by us
                }
                IO.println("(disconnected - press Enter to exit)");
            });

            // Thread 2 (main): send every line the user types
            BufferedReader keyboard = new BufferedReader(new InputStreamReader(System.in));
            String typed;
            while (printer.isAlive() && (typed = keyboard.readLine()) != null) {
                toServer.println(typed);
                if (typed.strip().equalsIgnoreCase("/quit")) {
                    break;
                }
            }
            printer.join(Duration.ofSeconds(2));       // let the goodbye message arrive
        }
    }
}

The server listens only on 127.0.0.1, so only programs on your own computer can connect. To chat across a network, bind to all interfaces with new ChatServer(null, port) instead, and think carefully first. A public chat server needs authentication, rate limits (one client sending thousands of lines per second would flood everyone), TLS encryption (SSLServerSocket), and protection against long lines and idle connections, which the server already has.

Ideas to extend it

  • Rooms. Add /join ROOM and keep a ConcurrentHashMap<String, ChatRoom>; a member belongs to one room at a time.
  • History. Keep the last 20 messages in a bounded, thread-safe structure and send them to each newcomer after the welcome.
  • Rate limiting. Track each member's messages per second and answer ! Slow down above a limit, the same idea as a token bucket.
  • Moderators. Give the first client in a room /kick NAME. Adding record Kick(String name) to Command will show you every switch that needs updating.
  • A Swing client. Combine the console client with what you built in Swing Basics: a JTextArea for the conversation and a JTextField for input. Remember to update components from the network thread with SwingUtilities.invokeLater.
  • JSON messages. Replace the text protocol with one JSON object per line (see JSON with Jackson) so messages can carry timestamps and types.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the room claim nicknames with putIfAbsent instead of containsKey followed by put?

    Check-then-act sequences are race conditions when other threads can act in between. putIfAbsent makes the check and the insert a single atomic operation, so exactly one client wins.
  2. 2. A client's laptop loses its network connection without sending /quit. How does the server find out?

    A closed connection makes readLine return null or throw. A connection that silently disappears is caught by setSoTimeout. Either way, the finally block removes the member.
  3. 3. Why is SocketConnection.send synchronized?

    Any session may write to any connection. Locking per connection makes each println complete before the next one starts, so every line arrives whole.
  4. 4. Why does the server need one thread (virtual or not) per client in this design?

    Blocking I/O waits on one socket at a time. With a thread per client, each one waits independently. Virtual threads make that cheap enough for thousands of clients.
  5. 5. In Stage 5, which ordering does the load test check, and why?

    Each client's lines are processed one after another by its own session, and TCP preserves order on each connection. Between different senders there's no global order.

Summary

  • The protocol is UTF-8 text lines; a sealed Command interface with nested records parses them, treats bad input as an Invalid command, and limits line length.
  • ChatRoom holds the shared state in a ConcurrentHashMap keyed by lower-case names: putIfAbsent claims names atomically, remove(key, value) removes safely, volatile publishes renames, and an AtomicInteger numbers guests.
  • The room talks to clients through a Connection interface, so its logic is tested with fake connections and no network.
  • The server accepts on a ServerSocket and serves each client on a virtual thread that loops on readLine(); null or an exception means the client is gone, and finally always removes it.
  • Writes to each connection are synchronized, idle clients time out, and shutdown closes the listener, then the clients, then waits for the sessions.
  • Tests stay deterministic by waiting for expected lines or using /ping as a sync marker; a 20-client load test confirms every message arrives, in order per sender.

Next: Data Structures in Java, where you'll implement dynamic arrays, stacks, queues, linked lists and binary search trees yourself.