I built a multi-client desktop chat application as a university Java networking project. The goal was to connect several clients to one TCP server, exchange messages, and make the connection lifecycle visible through JavaFX interfaces.

The result is two independent Maven applications: TCPServer, which accepts connections and broadcasts messages, and TCPClient, which provides the chat interface. The project uses Java 21, JavaFX 21.0.9, TCP sockets, and virtual threads.

The interesting engineering work lies between sending the first message and handling the last disconnection: keeping the interface responsive, separating private commands from broadcasts, supporting read-only connections, and closing resources reliably.

Adnane’s JavaFX client showing a conversation with Sara and an Online indicator.

A fresh demonstration of the packaged application: Adnane and Sara exchange messages through the TCP server. The application screenshots in this post were captured from the actual project running locally; the conversation is demo data.

Keeping the architecture understandable

I separated presentation, coordination, and networking so that each part has a clear responsibility:

TCPClient ClientApplication → ClientController → ChatClient │ UTF-8 lines over TCP │ TCPServer ▼ ServerApplication → ServerController → ChatServer │ ClientHandler per connection 

The application classes create the JavaFX views. Controllers connect button actions and network callbacks to those views. ChatClient, ChatServer, and ClientHandler contain the networking logic without depending on JavaFX.

That separation also makes the protocol testable without opening a window. A socket-level check can exercise the same server logic used by the dashboard.

The server dashboard exposes its running status, listening port, connection log, and connected named users. Its user list deliberately represents named participants rather than every socket.

The server dashboard running on port 3000, listing Adnane and Sara while logging a read-only connection.

Three clients are connected, but only Adnane and Sara appear in the named-user list. The anonymous connection remains visible in the activity log.

The repository includes PlantUML architecture sources and rendered diagrams.

A small protocol over TCP

The client and server communicate using UTF-8 text, BufferedReader, and PrintWriter. Each application message occupies one line. That line boundary matters: TCP carries a byte stream, so the application needs its own way to distinguish messages.

The first line identifies the connection:

USERNAME:Adnane 

An empty username selects read-only mode:

USERNAME: 

After the handshake, named users can send normal messages or one of three exact, case-sensitive commands:

Input Server behavior
allUsers Reply to the requester with the active named users.
bye Close that client’s connection.
end Close that client’s connection.
Any other line Add the username and server timestamp, then broadcast it.

The server formats ordinary messages as [HH:mm] username: message. It broadcasts them to registered clients, including the sender and read-only listeners. Returning the sender’s message through the server keeps the displayed format consistent.

The production client also rejects embedded carriage returns and newlines in outgoing messages, preserving the one-line framing. The handshake and command routing are implemented in ClientHandler.

Why I used virtual threads

Each connection spends much of its time waiting for the next line. The server assigns a virtual thread to each accepted client, allowing the handler to use straightforward blocking I/O.

This excerpt comes from the accept loop in ChatServer:

ClientHandler handler = new ClientHandler(socket, this); connections.add(handler); log("Client connected: " + socket.getRemoteSocketAddress()); Thread.startVirtualThread(handler); 

The surrounding implementation coordinates acceptance and shutdown with a lifecycle lock. It also uses concurrent sets to track connections safely across handlers.

Virtual threads suit tasks that spend substantial time waiting for I/O. They do not make individual operations inherently faster, and using them does not establish that an application scales to a particular number of users. This project uses them to keep the connection-handling model simple; it does not include a large-scale performance benchmark. See Oracle’s Java 21 virtual-thread guide.

Making JavaFX responsive and thread-safe

Socket connection, sending, and receiving work runs outside the JavaFX Application Thread. Otherwise, a slow network operation could stop the interface from responding.

Network callbacks return to the UI through Platform.runLater(). For example, the client controller registers this listener:

client.setMessageListener(message -> Platform.runLater(() -> { if (!closed) { view.messagesArea.appendText(message + "\n"); } })); 

runLater() queues work on the JavaFX Application Thread, as described in the JavaFX API documentation. The closed guard prevents a queued callback from updating a view that has already been closed.

The server follows the same pattern. When its user list changes, the queued UI callback reads the current usernames. This avoids restoring an old snapshot after another connection or disconnection has already happened.

External CSS controls the visual styling. Controllers handle behavior, while the networking classes remain unaware of controls, colors, and layout.

Treating read-only access as a server rule

Leaving the username blank connects a listener that can receive broadcasts but cannot send messages or commands.

The interface communicates this state with a READ-ONLY MODE notice and disabled sending controls. However, disabling a button alone would not enforce the protocol: another client could still write directly to the socket.

The server therefore checks readOnly before interpreting every incoming line. An attempted message or command receives a rejection instead of being broadcast or executed.

A read-only client receiving Adnane and Sara’s messages, with its input and SEND button disabled.

The listener receives the conversation while sending remains disabled. LEAVE is still available.

Anonymous clients are registered broadcast recipients, but their usernames are stored as null and filtered out of the named-user list. This makes receiving messages and appearing as a named participant separate concerns.

Keeping allUsers private

An ordinary chat message belongs in the shared conversation. A user-list query only needs a response to the person who requested it.

The handler implements that distinction directly: allUsers calls its own sendMessage() method, while ordinary text calls server.broadcast().

Adnane’s client showing Active users: Adnane, Sara beneath the shared conversation.

Adnane requests allUsers and receives the named-user list.

Sara’s client showing the shared conversation without the private Active users response.

Sara’s client does not receive that response. The read-only connection is absent from the returned list.

This is a small routing decision, but it provides a useful pattern for separating shared events from connection-specific replies.

Connection cleanup is part of the design

The server keeps two concurrent sets with different purposes:

  • connections tracks accepted sockets, including clients still waiting to send a username handshake.
  • clients tracks registered broadcast recipients.

That distinction matters during shutdown. Closing only registered clients could leave a handler blocked waiting for its first line. stop() closes the listening socket and every tracked connection. Handler cleanup removes clients from the sets and triggers a user-list update.

The implementation also gives the socket ownership of stream cleanup. A writer can be blocked behind a send, so the handler closes the socket first rather than waiting to close the writer first. On the client, closing the socket releases the receiving operation; the controller then updates the connection state.

Adnane’s client showing Offline and Disconnected from server after the server window closes.

Closing the server changes the connected client to Offline and disables sending.

These lifecycle choices are visible in ChatServer and ChatClient.

Testing the behavior, not just the build

For this write-up, the source at commit adfd621 was built and checked on Windows x64 with Java 21. Both Maven packages built successfully.

A separate local socket-level verification harness passed 14 checks, covering:

  • Timestamped UTF-8 messages and delivery to the sender, another named client, and a read-only client.
  • Named-user filtering and private allUsers responses.
  • Server-side rejection of read-only messages and commands.
  • bye, end, invalid handshakes, and accepting a new client after a departure.
  • The production ChatClient handshake and receiving path.
  • Server shutdown, including a socket still waiting to complete its handshake.

The packaged JavaFX applications were also exercised directly: two named clients exchanged messages, a read-only client received them, allUsers stayed private, LEAVE updated the dashboard, and closing the server disconnected the remaining clients.

These checks were run separately while preparing the article. The repository currently has no committed automated test suite; Maven’s successful build alone is not evidence of functional test coverage. The checks also do not establish behavior under heavy load, across operating systems, or during prolonged network failures.

Packaging and running the application

The projects use Maven Shade to produce executable JARs with dependencies and resources. Their manifests point to the ordinary TCPServer and TCPClient entry-point classes, which resolve configuration before launching JavaFX.

From the repository root, build each application separately:

mvn -f TCPServer/pom.xml clean package mvn -f TCPClient/pom.xml clean package 

Start the server:

java -jar TCPServer/target/TCPServer-1.0.jar 

Then start one or more clients in separate terminals:

java -jar TCPClient/target/TCPClient-1.0.jar localhost 3000 

The two projects have separate POMs; there is no root aggregator POM. The shaded *-1.0.jar files are the executable artifacts, while the *-1.0-SNAPSHOT.jar files are intermediate thin JARs.

The Windows build includes JavaFX native dependencies, but does not include a Java runtime. The verified environment is Windows x64 with Java 21; another operating system needs an appropriate build and validation. The shaded applications emit an unnamed-module JavaFX configuration warning, which was present during the successful local demonstration.

Configuration comes from classpath application.properties resources loaded at startup. Defaults are localhost and port 3000. Changing packaged defaults requires rebuilding; the client can override its host and port by supplying both command-line arguments. It does not load an arbitrary external properties file from the working directory.

What I would improve next

This is a focused networking project with clear limits. Usernames are self-declared, duplicates are allowed, and there is no authentication, encryption, message persistence, or automatic reconnection.

The current broadcast loop writes directly to recipients. A slow reader can delay a broadcast, so a future version could add bounded outgoing queues and a clear policy for slow connections. Concurrent senders also have no explicit global message sequencer.

My next priorities would be to bring repeatable protocol checks into the repository, add handshake and resource limits, and test slow-reader behavior before making any scalability claims.

Building the application brought together networking, concurrency, UI coordination, and deployment. The most useful lesson was that a working connection is only one part of the system: each connection also needs an identity, a set of allowed operations, and a predictable way to end.

Explore the source code on GitHub.