WebSocket in Jetty

WebSocket is an Internet protocol providing two-way communication between a client and a server. WebSocket was designed to be implemented in web browsers and web servers, but it can be used by any client or server application.

Messages can be delivered in either UTF-8 TEXT or BINARY format.

WebSocketServlet

Jetty's WebSocketServlet is a servlet that connects servlet technology to the WebSocket API. Inside WebSocketServlet's configure() method we register our WebSockets with a WebSocketServletFactory. The WebSockets are Java classes that deal with incoming WebSocket upgrade requests.

In the following example, a servlet deals with WebSocket requests from a webbrowser client.

$ tree
.
├── build.xml
└── src
    ├── com
    │   └── zetcode
    │       ├── MyServlet.java
    │       └── MySocket.java
    └── web
        ├── index.html
        ├── index.js
        └── WEB-INF

5 directories, 5 files

These are the contents of the project directory.

index.html
<!DOCTYPE html>
<html>
    <body>
        <script src="index.js"></script>
    </body>
</html>

The index.html file contains a <script> tag which loads an external script.

index.js
var ws = new WebSocket("ws://localhost:8080/ws/wsexample");

ws.onopen = function() {
    document.write("WebSocket opened <br>");
    ws.send("Hello Server");
};

ws.onmessage = function(evt) {
    document.write("Message: " + evt.data);
};

ws.onclose = function() {
    document.write("<br>WebSocket closed");
};

ws.onerror = function(err) {
    document.write("Error: " + err);
};

This JavaScript code creates a connection to a WebSocket. It defines four callback functions to WebSocket events.

var ws = new WebSocket("ws://localhost:8080/ws/wsexample");

A WebSocket object is created. The ws is an URI scheme for websocket connections. The constructor takes an URI which identifies a websocket server and resource name.

ws.onopen = function() {
    document.write("WebSocket opened <br>");
    ws.send("Hello Server");
};

When a connection to a WebSocket is created, an Open event is triggered. The send() method transmits data to the WebSocket.

ws.onmessage = function(evt) {
    document.write("Message: " + evt.data);
};

A message received from a WebSocket server is written to the HTML page using the document.write() method.

MyServlet.java
package com.zetcode;
 
import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.annotation.WebServlet;
import org.eclipse.jetty.websocket.servlet.WebSocketServlet;
import org.eclipse.jetty.websocket.servlet.WebSocketServletFactory;
 
@WebServlet(name = "WebSocket Servlet", urlPatterns = { "/wsexample" })
public class MyServlet extends WebSocketServlet {

    @Override
    public void doGet(HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {
        response.getWriter().println("HTTP GET method not implemented.");
    }

    @Override
    public void configure(WebSocketServletFactory factory) {
        factory.getPolicy().setIdleTimeout(10000);
        factory.register(MySocket.class);
    }
}

In the MyServlet.java class, we register a WebSocket to a WebSocketServletFactory in the configure method.

@Override
public void doGet(HttpServletRequest request,
        HttpServletResponse response) throws ServletException, IOException {
    response.getWriter().println("HTTP GET method not implemented.");
}

WebSocket requests are different from HTTP GET requests. Our servlet returns a message that the GET method is not implemented for attempts to connect to this servlet via a GET method. If we did not implement this method, we would receive an HTTP ERROR 405—HTTP method GET is not supported by this URL—error message from Jetty.

factory.getPolicy().setIdleTimeout(10000);

The connection will time out after ten seconds. A Close event will be triggered.

MySocket.java
package com.zetcode;

import java.io.IOException;
import org.eclipse.jetty.websocket.api.Session;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketClose;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketConnect;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketError;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketMessage;
import org.eclipse.jetty.websocket.api.annotations.WebSocket;

@WebSocket
public class MySocket {

    @OnWebSocketClose
    public void onClose(int statusCode, String reason) {
        System.out.println("Close: " + reason);
    }

    @OnWebSocketError
    public void onError(Throwable t) {
        System.out.println("Error: " + t.getMessage());
    }

    @OnWebSocketConnect
    public void onConnect(Session session) {
        System.out.println("Connect: " + session.getRemoteAddress().getAddress());
        
        try {
            session.getRemote().sendString("Hello Webbrowser");
        } catch (IOException e) {
            System.out.println("IO Exception");
        }
    }

    @OnWebSocketMessage
    public void onMessage(String message) {
        System.out.println("Message: " + message);
    }
}

This is a Java class that deals with WebSocket requests.

@WebSocket
public class MySocket {
...
}

The @WebSocket is an annotation that identifies a WebSocket class.

@OnWebSocketConnect
public void onConnect(Session session) {
    System.out.println("Connect: " + session.getRemoteAddress().getAddress());
    
    try {
        session.getRemote().sendString("Hello Webbrowser");
    } catch (IOException e) {
        System.out.println("IO Exception");
    }
}

The @OnWebSocketConnect annotation tags a method that receives connection Open events. The sendString() method sends a message back to the client.

@OnWebSocketMessage
public void onMessage(String message) {
    System.out.println("Message: " + message);
}

The @OnWebSocketMessage annotation tags a method that receives message events from the client. The message is written to the console from which we started Jetty.

build.xml
<?xml version="1.0" encoding="UTF-8"?>

<project name="WebSocket" default="compile">
    
    <property name="name" value="ws"/>
    <property environment="env"/>
    <property name="src.dir" value="src"/>
    <property name="web.dir" value="${src.dir}/web" />
    <property name="build.dir" location="${web.dir}/WEB-INF/classes"/>
    <property name="jetty.lib.dir" location="${env.JETTY_HOME}/lib"/>
    <property name="dist.dir" location="dist"/>
    <property name="deploy.path" location="${env.JETTY_BASE}/webapps"/>
  
    <path id="compile.classpath">
        <fileset dir="${jetty.lib.dir}"/>
    </path>
  
    <target name="init">
        <mkdir dir="${build.dir}"/>
        <mkdir dir="${dist.dir}"/>
    </target>     
  
    <target name="compile" depends="init">
        <javac srcdir="${src.dir}" destdir="${build.dir}" 
               includeantruntime="false">
            <classpath refid="compile.classpath"/>
        </javac>
        <echo>Compilation completed</echo>
    </target>
  
    <target name="archive" depends="compile">
        <war destfile="${dist.dir}/${name}.war" needxmlfile="false">
            <fileset dir="${web.dir}"/>
        </war>
        <echo>Archive created</echo>
    </target> 
  
    <target name="clean" depends="init">
        <delete dir="${build.dir}"/>
        <delete dir="${dist.dir}"/>
        <echo>Cleaning completed</echo>
    </target>  
    
    <target name="deploy" depends="archive">
        <copy file="${dist.dir}/${name}.war" overwrite="true" 
              todir="${deploy.path}"/>
        <echo>Archive deployed</echo>
    </target>    
    
</project>

This is the Ant build.xml file for the project.

$ java -jar $JETTY_HOME/start.jar --add-to-start=websocket

We need to add the WebSocket module to the Jetty base if it is not already enabled.

$ curl localhost:8080/ws/wsexample
HTTP GET method not implemented.

Sending an HTTP GET request produces this output.

WebSocket client
Figure: WebSocket client

A browser is a client that connects to the WebSocket server and sends a message. It also receives the "Hello Webbrowser" message from the server.

...
2014-09-06 17:08:42.193:INFO:oejs.Server:main: Started @4094ms
Connect: /127.0.0.1
Message: Hello Server
Error: Timeout on Read
Close: Idle Timeout

These are the messages that appear on Jetty's console.

WebSocket client

In this section we will show how to create a WebSocket request from two different clients. The first client is a Python script which uses the Python websocket library.

$ sudo apt-get install python-websocket

We need to install the python-websocket library.

#!/usr/bin/python

import websocket

websocket.enableTrace(True)
ws = websocket.create_connection("ws://localhost:8080/ws/wsexample")
print "Sending message"
ws.send("Hello server")
result = ws.recv()
print "Received '%s'" % result 

The script sends a message to our WebSocket server and receives the answer.

$ ./pyclient.py 
Sending message
Received 'Hello client'

Running the program we get this output.

In the second client, we use Jetty's WebSocketClient and ClientUpgradeRequest classes to establish a WebSocket connection and send and receive a message.

package com.zetcode;

import org.eclipse.jetty.websocket.api.Session;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketClose;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketConnect;
import org.eclipse.jetty.websocket.api.annotations.OnWebSocketMessage;
import org.eclipse.jetty.websocket.api.annotations.WebSocket;
import org.eclipse.jetty.websocket.client.ClientUpgradeRequest;
import org.eclipse.jetty.websocket.client.WebSocketClient;
import java.io.IOException;
import java.net.URI;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;

public class JettyWebSocketClient {

    public static void main(String[] args) throws Exception {
        
        JettyWebSocketClient app = new JettyWebSocketClient();
        app.start();
    }
    
    public void start() throws Exception {

        WebSocketClient client = new WebSocketClient();
        MyWebSocket socket = new MyWebSocket();
        
        client.start();
        
        URI destUri = new URI("ws://localhost:8080/ws/wsexample");
        
        ClientUpgradeRequest request = new ClientUpgradeRequest();
        System.out.println("Connecting to: " + destUri);
        client.connect(socket, destUri, request);
        socket.awaitClose(5, TimeUnit.SECONDS);

        client.stop();
    }

    @WebSocket
    public class MyWebSocket {
    
        private final CountDownLatch closeLatch = new CountDownLatch(1);

        @OnWebSocketConnect
        public void onConnect(Session session) throws IOException {
        
            System.out.println("Sending message: Hello server");
            session.getRemote().sendString("Hello server");
        }

        @OnWebSocketMessage
        public void onMessage(String message) {
            System.out.println("Message from Server: " + message);
        }

        @OnWebSocketClose
        public void onClose(int statusCode, String reason) {
            System.out.println("WebSocket Closed. Code:" + statusCode);
        }

        public boolean awaitClose(int duration, TimeUnit unit) 
                throws InterruptedException {
            return this.closeLatch.await(duration, unit);
        }
    }
}

This example is a Java WebSocket client.

URI destUri = new URI("ws://localhost:8080/ws/wsexample");

An URI pointing to our websocket endpoint is created.

ClientUpgradeRequest request = new ClientUpgradeRequest();

The initial conversation to open a websocket connection is done over the HTTP protocol. The client sends an Upgrade request to the server. If the server supports WebSocket protocol, it agrees to the protocol switch. Jetty uses ClientUpgradeRequest class to create an Upgrade request.

client.connect(socket, destUri, request);

We connect to the specified URI via the established WebSocket and send the Upgrade request.

session.getRemote().sendString("Hello server");

The message is sent with the sendString() method.

<?xml version="1.0" encoding="UTF-8"?>

<project name="JettyWebSocketClient" default="compile">
    
    <property name="name" value="wsclient"/>
    <property environment="env"/>
    <property name="src.dir" value="src"/>
    <property name="build.dir" location="build"/>
    <property name="jetty.lib.dir" location="${env.JETTY_HOME}/lib"/>
  
    <path id="compile.classpath">
        <fileset dir="${jetty.lib.dir}"/>
    </path>
    
 <path id="run.classpath">
        <pathelement path="${build.dir}"/>
        <fileset dir="${jetty.lib.dir}"> 
            <include name="**/*.jar"/> 
        </fileset>
    </path>      
  
    <target name="init">
        <mkdir dir="${build.dir}"/>
    </target>     
  
    <target name="compile" depends="init">
        <javac srcdir="${src.dir}" destdir="${build.dir}" 
                includeantruntime="false">
            <classpath refid="compile.classpath"/>
        </javac>
        <echo>Compilation completed</echo>
    </target>
   
    <target name="clean" depends="init">
        <delete dir="${build.dir}"/>
        <echo>Cleaning completed</echo>
    </target>  
    
    <target name="run" depends="compile">
        <echo>Running the program</echo>
        <java classname="com.zetcode.JettyWebSocketClient" 
                classpathref="run.classpath"/>
    </target> 
    
</project>

This is the Ant build file to compile and run the WebSocket client.

$ ant run
Buildfile: /home/janbodnar/prog/jetty/websocket3/build.xml
init:
compile:
     [echo] Compilation completed
run:
     [echo] Running the program
     [java] 2014-09-07 23:13:39.796:INFO::main: Logging initialized @1230ms
     [java] Connecting to: ws://localhost:8080/ws/wsexample
     [java] Sending message: Hello server
     [java] Message from server: Hello client
     [java] WebSocket closed. Code:1001
BUILD SUCCESSFUL
Total time: 6 seconds

We get this output when we run the code.

In this chapter of the Jetty tutorial, we have established WebSocket connections in Jetty.