Building a Multi-Client Chat Application with Java Sockets and JavaFX

Houda Bachr — Sun, 18 Oct 2026 15:14:43 +0000

A group chat is a useful way to explore network programming because several concerns meet in one application: concurrent connections, message delivery, user identity, and a responsive interface. Relay is a small educational project that brings these pieces together using Java TCP sockets, virtual threads, JavaFX, and Maven.

This article describes the implementation, its main technical challenges, and the checks used to verify it. The project and this write-up were developed with assistance from OpenAI Codex.

The application

Relay has a central server and multiple clients. A named user can send messages to the room using a SEND button or Enter. The server adds the sender's name and a timestamp before distributing the message to every connected client, including the sender.

Users who connect without a username become guests in READ-ONLY MODE. They can receive messages and inspect the active-user list, but cannot send chat messages. The allUsers command returns the connected-user list privately to its requester. The end and bye commands, along with a LEAVE button, close a connection.

The server interface displays connected users in a live ListView, assigns a random background color to each session, and records connection and message activity. Both applications use JavaFX GridPane layouts and CSS.

Organizing the implementation

The project is a Maven reactor with three modules:

common: runtime configuration and the wire protocol.
server: connection management, membership, message distribution, and the server interface.
client: the client connection model and chat interface.

The central design decision is to keep socket logic independent of JavaFX. ChatServer and ChatClient contain the network operations. ServerApplication and ClientApplication present their state. Listener interfaces connect the two layers without requiring the models to import JavaFX classes.

The implementation work began with configuration, framing, and the networking models. The interfaces were then connected through listener callbacks. Socket integration tests checked the protocol behavior, followed by automated GUI checks and executable-JAR launch checks. UML diagrams and a three-minute demonstration document the final result.

Handling concurrent clients

A server cannot spend its entire execution waiting for one client to send a message. It must continue accepting connections and servicing existing users.

Relay uses a virtual-thread executor:

Executors.newVirtualThreadPerTaskExecutor();

The accept loop and individual client handlers run as executor tasks. This lets the implementation use straightforward blocking socket reads while handling multiple connections concurrently. The project targets Java 21 or newer and was tested with Java 22.

Concurrency also requires protecting shared state. Client membership and broadcasts are synchronized, and writes to each connection are serialized so frames do not interleave. This approach keeps the mini-project understandable, although it has a limitation: a client that stops reading can eventually delay a broadcast. A more scalable design would introduce bounded outgoing queues and separate writer tasks for each connection.

Giving TCP messages clear boundaries

TCP supplies a stream of bytes, so the application needs its own message boundaries. A raw newline-delimited chat protocol becomes ambiguous when a user writes a multiline message.

Relay uses this frame format:

TYPE<TAB>Base64(UTF-8 payload)<NEWLINE>

Encoding the payload allows a message to contain newlines or tabs without breaking the frame structure. UTF-8 supports international text and emoji. Base64 is only an encoding; it does not encrypt the conversation.

The connection begins with HELLO, containing the requested username. The server replies with WELCOME and MODE. Later frames distinguish chat messages, system notices, private user lists, errors, and leave requests.

The implementation bounds frame length and limits chat messages to 4,000 characters. A ten-second handshake timeout prevents a connection from waiting indefinitely for its initial identity message.

Enforcing read-only mode in two places

Disabling a button improves the interface, but it cannot enforce a network rule by itself. Another client could bypass that interface and send a frame directly.

Relay therefore enforces guest restrictions in both the UI and the server. A guest's composer and SEND button are disabled. Independently, the server checks the session's read-only flag and rejects attempts to send chat messages. Guests can still request the active-user list and leave normally.

Named users must also pass validation, and duplicate names are rejected without regard to case. This is username-based identification rather than password authentication: the application does not implement accounts or prove ownership of a name.

Keeping JavaFX responsive

Socket operations should not block the JavaFX Application Thread. Connection and send operations run outside that thread, and the client receives messages in a virtual thread.

When a model emits a callback, the view schedules its visual update through Platform.runLater. This keeps the networking model independent of JavaFX while ensuring that controls are updated on the correct thread.

The same separation makes testing easier. Networking tests instantiate ChatServer and ChatClient directly, without opening a window or starting JavaFX.

Commands, configuration, and disconnection

Ordinary messages are broadcast, but allUsers receives a direct reply on the requester's connection. This avoids exposing command responses to the whole room. A dedicated WHO'S ONLINE button provides the same operation for guests whose composer is disabled.

The disconnection paths remove the user from server membership, update the displayed list, and notify the remaining clients. Closing a window or losing a connection also requires cleanup; abrupt disconnects are covered by the socket tests.

Network settings live in an external file:

server.host=localhost
server.bind=0.0.0.0
server.port=3000

The applications read this file at runtime. Client command-line arguments can override the destination host and port, allowing deployment changes without recompilation.

Verification and final implementation

The recorded clean Maven build passed 12 JUnit tests. They exercise real loopback TCP sockets and cover:

24 concurrent clients and message delivery to all recipients;
timestamped Unicode and multiline messages;
private active-user replies and server-side rejection of guest writes;
invalid and duplicate usernames;
end, bye, LEAVE, abrupt disconnects, and server shutdown;
oversized messages, invalid frames, configuration overrides, and client lifecycle behavior.

An automated GUI demonstration also passed 12 checks, including SEND, Enter, guest restrictions, private replies, leaving, and reconnection. Separate launch checks confirmed that the packaged server and client start as independent Java processes.

The three-minute video combines a source walkthrough with real JavaFX controls communicating over local TCP sockets. Its recorder hosts the application views in one JVM; the delivered launchers run separately. These checks establish the tested local behavior, rather than claiming production-scale reliability or testing across every operating system.

The deliverables include two executable JARs, Maven source, configuration, class and deployment diagrams, a sequence diagram, and the demo video. The bundled JARs were built for macOS Apple Silicon. Other platforms should rebuild the project so Maven selects matching JavaFX native libraries.

Running the project

From the extracted project directory, build and test with:

./mvnw clean verify
./scripts/package.sh

Then start the server and clients in separate terminals:

java -jar dist/TCPServer.jar
java -jar dist/TCPClient.jar localhost 3000

On Windows, use mvnw.cmd clean verify and copy the generated server and client JARs from their module target directories into dist. Keep chat.properties in the working directory, or specify another file using the chat.config system property.

What could come next

This version focuses on the assignment's shared-room behavior. Useful extensions would include outgoing message queues, encrypted transport, authenticated accounts, and persistent message history. Each would introduce additional responsibilities that should remain separate from the JavaFX views.

The main lesson from this implementation is that a reliable chat interface depends on clear protocol boundaries, server-side rules, careful connection cleanup, and explicit coordination between networking and UI threads.

Project repository: Multi-Client Chat Application Using Java Sockets. Access to this private repository requires the owner's permission.

DEV Community: Houda Bachr