WebSocket is a computer communications protocol which is designed to be implemented in web browsers and web servers, but it can be used by any client or server application.
The WebSocket Protocol is an independent TCP-based protocol. Its only relationship to HTTP is that its handshake is interpreted by HTTP servers as an Upgrade request. The WebSocket protocol makes more interaction between a browser and a web server possible, facilitating the real-time data transfer from and to the server.
This is made possible by providing a standardized way for the server to send content to the browser without being solicited by the client, and allowing for messages to be passed back and forth while keeping the connection open. In this way, a two-way (bi-directional) ongoing conversation can take place between a browser and the server. The communications are done over TCP port number 80, which is of benefit for those environments which block non-web Internet connections using a firewall.
The WebSocket protocol is currently supported in most major browsers including Google Chrome, Microsoft Edge, Internet Explorer, Firefox, Safari and Opera. WebSocket also requires web applications on the server to support it.
Table Of Contents
1. The tools
- Java JDK
- Eclipse IDE
- Apache Tomcat
2. Introduction
In this example we are going to show you how to use Apache Tomcat to establish a client server WebSocket connection. We are going to write a simple echo client server application and deploy it on Tomcat.
3. Prerequisites
- JDK installed
- Eclipse installed
4. Download Tomcat
Go to the page https://tomcat.apache.org/download-80.cgi and download the tomcat server as a zip compressed file for windows.
5. Tomcat Installation
5.1 Uncompress Apache Tomcat
Choose an installation directory and uncompress the Tomcat server in its own directory.
5.2 Install the Tomcat service
Open the Windows terminal and go to the Tomcat Installation bin directory.
Tomcat installation directory
1 | C:\Java\Apache Tomcat 8.0.15\bin> |
Install the service with the following command:
Install Tomcat service
1 | C:\Java\Apache Tomcat 8.0.15\bin>service install |
You should get an output similar to this:
install Tomcat output
1 2 3 4 5 6 7 | Installing the service 'Tomcat8' ...Using CATALINA_HOME: "C:\Java\Apache Tomcat 8.0.15"Using CATALINA_BASE: "C:\Java\Apache Tomcat 8.0.15"Using JAVA_HOME: "C:\Java\jdk1.8.0_40"Using JRE_HOME: "C:\Java\jre1.8.0_40"Using JVM: "C:\Java\jre1.8.0_40\bin\client\jvm.dll"The service 'Tomcat8' has been installed. |
5.3 Start the Tomcat service
Start the service with the following command:
Start tomcat output
1 | C:\Java\Apache Tomcat 8.0.15\bin>sc start Tomcat8 |
You should get an output similar to the following:
console
01 02 03 04 05 06 07 08 09 10 | SERVICE_NAME: Tomcat8 TYPE : 10 WIN32_OWN_PROCESS STATUS : 2 START_PENDING (NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN) WIN32_OUTPUT_CODE : 0 (0x0) SERVICE_OUTPUT_CODE: 0 (0x0) CHECK-POINT : 0x0 START-INDICATOR : 0x7d0 PID : 5552 MARKS : |
5.4 Check that tomcat is running
Open the browser in the URL: http://localhost:8080 and you should see the Tomcat Welcome screen.
6. Create the web socket server
We are going to create a new WebSocket server, open eclipse and create a new dynamic web application from the menu.
6.1 Create the project
Name the application and press finish.
Create a new class with right click on the project menu.
Name the class and press finish.
6.2 Coding the server
Anotate the class
1 2 | @ServerEndpoint("/websocketendpoint")public class WsServer { |
This class level annotation declares that the class it decorates is a web socket endpoint that will be deployed and made available in the URI-space of a web socket server. The annotation allows the developer to define the URL which this endpoint will be published.
Server endpoint classes are Plain Old Java Objects that are annotated with javax.websocket.server.ServerEndpoint.
Open WebSocket
1 2 3 4 | @OnOpenpublic void onOpen(){ System.out.println("Open Connection ...");} |
@OnOpen annotation is used on a @ServerEndpoint method, but only once per endpoint. It is used to decorate a method which is called, once new connection is established.
Close WebSocket
1 2 3 4 | @OnClosepublic void onClose(){ System.out.println("Close Connection ...");} |
@OnClose annotation is used on a @ServerEndpoint method, but only once per endpoint. It is used to decorate a method which is called, once the connection is being closed.
Receive and echo the client message
1 2 3 4 5 6 | @OnMessagepublic String onMessage(String message){ System.out.println("Message from the client: " + message); String echoMsg = "Echo from the server : " + message; return echoMsg;} |
@OnMessage annotation is used on a @ServerEndpoint method, but only once per endpoint. It is used to decorate a method which is called, once new message is received.
Capture errors
1 2 3 4 | @OnErrorpublic void onError(Throwable e){ e.printStackTrace();} |
@OnError annotation is used on a @ServerEndpoint method, but only once per endpoint. It is used to decorate a method which is called, once Exception is being thrown by any method annotated with @OnOpen, @OnMessage and @OnClose.
6.3 Create the client
Right click on the project and choose New HTML File.
Write the name of the HTML file and click finish.
6.4 The HTML client
the form
1 2 3 4 5 | <form> <input id="message" type="text"> <input onclick="wsSendMessage();" value="Echo" type="button"> <input onclick="wsCloseConnection();" value="Disconnect" type="button"></form> |
This form has an input text to write the message that we are going to send to the server. A button to send the message and a button to close the connection.
xml
1 | <textarea id="echoText" rows="5" cols="30"></textarea> |
In this text area we are going to write the echo from the server.
6.5 Javascript code
Web Socket
1 | var webSocket = new WebSocket("ws://localhost:8080/WebSocketServerExample/websocketendpoint"); |
Open the web socket connection.
HTML elements
1 2 3 | var echoText = document.getElementById("echoText");echoText.value = "";var message = document.getElementById("message"); |
Get the HTML elements.
functions
1 2 3 4 | webSocket.onopen = function(message){ wsOpen(message);};webSocket.onmessage = function(message){ wsGetMessage(message);};webSocket.onclose = function(message){ wsClose(message);};webSocket.onerror = function(message){ wsError(message);}; |
Assign the functions to the webSocket we created before.
Open
1 2 3 | function wsOpen(message){ echoText.value += "Connected ... \n";} |
When we open the page the text “connected” is written to the text area.
Send message
1 2 3 4 5 | function wsSendMessage(){ webSocket.send(message.value); echoText.value += "Message sended to the server : " + message.value + "\n"; message.value = "";} |
When the button echo is clicked this function is called and it invokes the send method of the web socket class with the value of the textbox as a parameter.
Also we write to the text area.
Close
1 2 3 | function wsCloseConnection(){ webSocket.close();} |
Close the WebSocket connection.
Response
1 2 3 | function wsGetMessage(message){ echoText.value += "Message received from to the server : " + message.data + "\n";} |
Get the WebSocket message from the server and send it to the text area.
Close event
1 2 3 | function wsClose(message){ echoText.value += "Disconnect ... \n";} |
Capture the close event and write a message to the text area.
Error
1 2 3 | function wsError(message){ echoText.value += "Error ... \n";} |
If we get any errors we write them to the text area.
7. The complete source code
7.1 Server
java
01 02 03 04 05 06 07 08 09 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 | package server.ws;import javax.websocket.OnClose;import javax.websocket.OnError;import javax.websocket.OnMessage;import javax.websocket.OnOpen;import javax.websocket.server.ServerEndpoint;@ServerEndpoint("/websocketendpoint")public class WsServer { @OnOpen public void onOpen(){ System.out.println("Open Connection ..."); } @OnClose public void onClose(){ System.out.println("Close Connection ..."); } @OnMessage public String onMessage(String message){ System.out.println("Message from the client: " + message); String echoMsg = "Echo from the server : " + message; return echoMsg; } @OnError public void onError(Throwable e){ e.printStackTrace(); }} |
7.2 Client
xml
01 02 03 04 05 06 07 08 09 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 43 44 45 46 47 | <!DOCTYPE html><html><head><meta charset="UTF-8"><title>Tomcat WebSocket</title></head><body> <form> <input id="message" type="text"> <input onclick="wsSendMessage();" value="Echo" type="button"> <input onclick="wsCloseConnection();" value="Disconnect" type="button"> </form> <br> <textarea id="echoText" rows="5" cols="30"></textarea> <script type="text/javascript"> var webSocket = new WebSocket("ws://localhost:8080/WebSocketServerExample/websocketendpoint"); var echoText = document.getElementById("echoText"); echoText.value = ""; var message = document.getElementById("message"); webSocket.onopen = function(message){ wsOpen(message);}; webSocket.onmessage = function(message){ wsGetMessage(message);}; webSocket.onclose = function(message){ wsClose(message);}; webSocket.onerror = function(message){ wsError(message);}; function wsOpen(message){ echoText.value += "Connected ... \n"; } function wsSendMessage(){ webSocket.send(message.value); echoText.value += "Message sended to the server : " + message.value + "\n"; message.value = ""; } function wsCloseConnection(){ webSocket.close(); } function wsGetMessage(message){ echoText.value += "Message received from to the server : " + message.data + "\n"; } function wsClose(message){ echoText.value += "Disconnect ... \n"; } function wsError(message){ echoText.value += "Error ... \n"; } </script></body></html> |
8. Running the example
Right click on the project folder and choose Run as -> Run on server choose Tomcat 8 server and click finish.
9. Results
The WebSocket is opened when the page is loaded. Everytime you write a text in the textbox, the message goes to the server and the latter sends the echo message response.
10. Download the Source Code
This was an example of: Tomcat WebSocket.
Very clearly written article. I could create a server based on code you posted and test with HTML client code taken from somebody else’s post on websocket that I already had. Worked without any problem. Thanks a lot!
After 5 minutes socket closes with handshake failed. Response code 404. Do you know why is this happening?
Really useful, thanks !
Nice article !
There is minor typo that needs to be corrected. While declaring function wserror, the ‘e’ has to be uppercase.
All I can say I cannot thank you enough for this.
i am not getting echo message response from the server
I wish all tutorials were this complete! This should seen as a gold standard template on how to construct a tutorial.