Java is a high-level, class-based, object-oriented programming language that aims to have as few implementation dependencies as feasible. Because Java is a general-purpose programming language, compiled Java code can run on all platforms that accept Java without the need to recompile. This is what is meant by the phrase “write once, run anywhere.”
Regardless of the underlying computer architecture, Java applications are often compiled to bytecode that can run on any Java virtual machine (JVM). Although Java has fewer low-level features than either C or C++, it has syntax that is similar to each of them. Unlike most traditional compiled languages, the Java runtime has dynamic capabilities (such as reflection and runtime code change).
The Java language project was launched in June 1991 by Patrick Naughton, Mike Sheridan, and James Gosling. Although Java was initially intended for interactive television, the digital cable television market at the time found it to be too sophisticated. The name “Oak” for the language came from an oak tree that was outside Gosling’s office.
WebSocket
WebSockets enable real-time communication on the web. ws:// or wss:// protocol is an upgraded version of the http:// protocol. Unlike HTTP, WS is long-lived and can receive messages from the server as they occur in real-time.
A two-way interactive communication session can be started between a user’s browser and a server using the WebSocket API, a cutting-edge technology. Without needing to poll the server for a response, you may use this API to send messages to a server and receive event-driven responses.
The HTML5 specification first used WebSocket as a placeholder for a TCP-based socket API under the name TCP connection. Michael Carter facilitated a series of discussions that led to the creation of the initial iteration of the WebSocket protocol in June 2008.
Soon after, through collaboration on the #whatwg IRC chat room, Ian Hickson and Michael Carter came up with the name “WebSocket,” which was later written by Ian Hickson for inclusion in the HTML5 specification.
In today’s post, we will see how to build a WebSocket server in Java and test it using PieSocket’s online websocket client.
Prepare Environment
You need the following installed on your system to follow this tutorial
- Java (How To Install And Configure Java On Ubuntu Linux.)
- Gradle (How To Install Gradle On Ubuntu Linux)
- VSCode (
sudo snap --classic install code
)
Please note that we are using Ubuntu for the purpose of demonstration you can use any operating system and the process should be similar.
You may use any text editor of your choice, however, we are using VScode along with the following 3 plugins to make it easy to code in Java.

Create Project
Run the following commands to create a directory for your project and switch the current working directory
1 2 |
mkdir java-websocket cd java-websocket |
Open the directory in VS Code
1 |
code . |
It is an empty directory so far, initialize grade to create the required project structure with the following command
1 |
gradle init --type=java-application |
Few prompts will appear.
Select Groovy as build script DSL.
Then, JUnit Jupiter as a testing framework
Leave default selected for the rest i.e., Project name and Source package.
Gradle should initialize the project with following output:

Java Code For WebSocket Server
Add the following dependency
in the dependencies
block of app/build.gradle
file
1 |
implementation 'javax.websocket:javax.websocket-api:1.1' |
When you save this file, VS Code will show a prompt to update the classpath configuration, select yes as shown below.
Create a file app/src/main/java/java/websocket/WebSocket.java
and add the following to it.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
package websocket.java; import javax.websocket.OnMessage; import javax.websocket.server.ServerEndpoint; @ServerEndpoint("/socket") public class WebSocket { @OnMessage public String handleTextMessage(String message) { System.out.println("New Text Message Received"); return message; } @OnMessage(maxMessageSize = 1024000) public byte[] handleBinaryMessage(byte[] buffer) { System.out.println("New Binary Message Received"); return buffer; } } |
Create an HTML file app/src/main/webapp/index.html
to serve as the root for the WebSocket server and add the following content to it
1 |
Hello From WebSocket! |
You will have to create the webapp
directory first in app/src/main
.
Add Gretty Plugin
We need to use Tomcat Servlet to serve the WebSocket server code, and for this, we need to add Gretty to our project.
Add the following to plugins
section of the app/build.gradle
file
1 |
id "org.gretty" version "3.0.5" |
And finally, add the following at the very bottom of the same build.gradle
file.
1 2 3 4 |
gretty { servletContainer = 'tomcat9' contextPath = '/' } |
Your complete app/build.gradle
the file should look like following
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
/* * This file was generated by the Gradle 'init' task. * * This generated file contains a sample Java application project to get you started. * For more details take a look at the 'Building Java & JVM projects' chapter in the Gradle * User Manual available at https://docs.gradle.org/7.2/userguide/building_java_projects.html */ plugins { // Apply the application plugin to add support for building a CLI application in Java. id 'application' id "org.gretty" version "3.0.5" } repositories { // Use Maven Central for resolving dependencies. mavenCentral() } dependencies { // Use JUnit Jupiter for testing. testImplementation 'org.junit.jupiter:junit-jupiter:5.7.2' // This dependency is used by the application. implementation 'com.google.guava:guava:30.1.1-jre' implementation 'javax.websocket:javax.websocket-api:1.1' } application { // Define the main class for the application. mainClass = 'java.websocket.App' } tasks.named('test') { // Use JUnit Platform for unit tests. useJUnitPlatform() } gretty { servletContainer = 'tomcat9' contextPath = '/' } |
Running the server
It’s time to test the WebSocket server.
To do so, we need to first run the WebSocket server in a terminal and leave it running.
1 |
./gradlew appRun |
Run the command given above from the project directory and you should see an output similar to the following.

Open http://localhost:8080 in your browser and you should see a “Hello From WebSocket” message.
This means the WebSocket server is running and we can test it with PieSocket’s WebSocket Client Extension.
Open the extension and enter http://localhost:8080/socket as WebSocket URL and click Connect.

You should be now able to send and receive messages from your Java WebSocket server.
Conclusion
We learned how to build a WebSocket server with Java without Springboot, Spark, or any other framework. We also learned how to test a WebSocket server with PieSocket’s WebSocket tester extension.
WebSockets are easy to build, but difficult to scale, and maintain, we recommend using PieSocket’s Managed WebSocket API for all your production WebSocket use-cases.