<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Jetty WebSocket Server API</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, spdy, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty : The Definitive Reference"><link rel="up" href="websocket-jetty.html" title="Chapter&nbsp;30.&nbsp;Jetty Websocket API"><link rel="prev" href="jetty-websocket-api-adapter.html" title="Using the WebSocketAdapter"><link rel="next" href="jetty-websocket-client-api.html" title="Jetty WebSocket Client API"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.1.5.v20140505</span></td><td style="width: 50%"><script type="text/javascript">  (function() {
            var cx = '016459005284625897022:obd4lsai2ds';
            var gcse = document.createElement('script');
            gcse.type = 'text/javascript';
            gcse.async = true;
            gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
            '//www.google.com/cse/cse.js?cx=' + cx;
            var s = document.getElementsByTagName('script')[0];
            s.parentNode.insertBefore(gcse, s);
            })();
          </script><gcse:search></gcse:search></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Jetty WebSocket Server API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jetty-websocket-api-adapter.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;30.&nbsp;Jetty Websocket API<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jetty-websocket-client-api.html">Next <i class="icon-chevron-right"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
 scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="jetty-websocket-server-api"></a>Jetty WebSocket Server API</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="jetty-websocket-server-api.html#d0e21138">The Jetty WebSocketServlet</a></span></dt><dt><span class="section"><a href="jetty-websocket-server-api.html#d0e21162">Using the WebSocketCreator</a></span></dt></dl></div><p>Jetty provides the ability to wire up WebSocket endpoints to Servlet
  Path Specs via the use of a WebSocketServlet bridge servlet.</p><p>Internally, Jetty manages the HTTP Upgrade to WebSocket and migration
  from a HTTP Connection to a WebSocket Connection.</p><p>This will only work when running within the Jetty Container. (unlike
  past Jetty technologies, you cannot get Jetty WebSocket server functionality
  running Jetty within other containers like JBoss, Tomcat, or
  WebLogic)</p><p></p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e21138"></a>The Jetty WebSocketServlet</h3></div></div></div><p>To wire up your WebSocket to a specific path via the
    WebSocketServlet, you will need to extend
    org.eclipse.jetty.websocket.servlet.WebSocketServlet and specify what
    WebSocket object should be created with incoming Upgrade requests.</p><div class="example"><a name="d0e21143"></a><p class="title"><b>Example&nbsp;30.16.&nbsp;MyEchoServlet.java</b></p><div class="example-contents"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[package examples;

import javax.servlet.annotation.WebServlet;
import org.eclipse.jetty.websocket.servlet.WebSocketServlet;
import org.eclipse.jetty.websocket.servlet.WebSocketServletFactory;

@SuppressWarnings("serial")
@WebServlet(name = "MyEcho WebSocket Servlet", urlPatterns = { "/echo" })
public class MyEchoServlet extends WebSocketServlet {

    @Override
    public void configure(WebSocketServletFactory factory) {
        factory.getPolicy().setIdleTimeout(10000);
        factory.register(MyEchoSocket.class);
    }
}
]]>
        </script></div></div><br class="example-break"><p>This example will create a Servlet mapped via the <a class="link" href="http://docs.oracle.com/javaee/6/api/javax/servlet/annotation/WebServlet.html" target="_top">@WebServlet</a>
    annotation to the Servlet path spec of <code class="literal">"/echo"</code> (or you
    can do this manually in the <code class="filename">WEB-INF/web.xml</code> of your
    web application) which will create MyEchoSocket instances when
    encountering HTTP Upgrade requests.</p><p>The WebSocketServlet.configure(WebSocketServletFactory factory) is
    where you put your specific configuration for your WebSocket. In the
    example we specify a 10 second idle timeout and register MyEchoSocket with
    the default WebSocketCreator the WebSocket class we want to be created on
    Upgrade.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="d0e21162"></a>Using the WebSocketCreator</h3></div></div></div><p>All WebSocket's are created via whatever <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/websocket/servlet/WebSocketCreator.html" target="_top">WebSocketCreator</a>
    you have registered with the <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/websocket/servlet/WebSocketServletFactory.html" target="_top">WebSocketServletFactory</a>.
    </p><p>By default, the WebSocketServletFactory is a simple WebSocketCreator
    capable of creating a single WebSocket object. Use <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/websocket/servlet/WebSocketServletFactory.html#register(java.lang.Class)" target="_top"><code class="code">WebSocketCreator.register(Class&lt;?&gt;
    websocket)</code></a> to tell the WebSocketServletFactory which class
    it should instantiate (make sure it has a default constructor). </p><p>If you have a more complicated creation scenario, you might want to
    provide your own WebSocketCreator that bases the WebSocket it creates off
    of information present in the UpgradeRequest object.</p><div class="example"><a name="d0e21181"></a><p class="title"><b>Example&nbsp;30.17.&nbsp;MyAdvancedEchoCreator.java</b></p><div class="example-contents"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[package examples;

import org.eclipse.jetty.websocket.servlet.ServletUpgradeRequest;
import org.eclipse.jetty.websocket.servlet.ServletUpgradeResponse;
import org.eclipse.jetty.websocket.servlet.WebSocketCreator;

public class MyAdvancedEchoCreator implements WebSocketCreator {

    private MyBinaryEchoSocket binaryEcho;

    private MyEchoSocket textEcho;

    public MyAdvancedEchoCreator() {
        this.binaryEcho = new MyBinaryEchoSocket();
        this.textEcho = new MyEchoSocket();
    }

    @Override
    public Object createWebSocket(ServletUpgradeRequest req, ServletUpgradeResponse resp) {
        for (String subprotocol : req.getSubProtocols()) {
            if ("binary".equals(subprotocol)) {
                resp.setAcceptedSubProtocol(subprotocol);
                return binaryEcho;
            }
            if ("text".equals(subprotocol)) {
                resp.setAcceptedSubProtocol(subprotocol);
                return textEcho;
            }
        }
        return null;
    }
}
]]>
        </script></div></div><br class="example-break"><p>Here we show a WebSocketCreator that will utilize the <a class="link" href="http://tools.ietf.org/html/rfc6455#section-1.9" target="_top">WebSocket
    subprotocol</a> information from request to determine what WebSocket
    type should be created.</p><div class="example"><a name="d0e21192"></a><p class="title"><b>Example&nbsp;30.18.&nbsp;MyAdvancedEchoServlet.java</b></p><div class="example-contents"><script type="syntaxhighlighter" class="brush: java;toolbar: false">
          <![CDATA[package examples;

import javax.servlet.annotation.WebServlet;
import org.eclipse.jetty.websocket.servlet.WebSocketServlet;
import org.eclipse.jetty.websocket.servlet.WebSocketServletFactory;

@SuppressWarnings("serial")
@WebServlet(name = "MyAdvanced Echo WebSocket Servlet", urlPatterns = { "/advecho" })
public class MyAdvancedEchoServlet extends WebSocketServlet {

    @Override
    public void configure(WebSocketServletFactory factory) {
        factory.getPolicy().setIdleTimeout(10000);
        factory.setCreator(new MyAdvancedEchoCreator());
    }
}
]]>
        </script></div></div><br class="example-break"><p>When you want a custom WebSocketCreator, use <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/websocket/servlet/WebSocketServletFactory.html#setCreator(org.eclipse.jetty.websocket.servlet.WebSocketCreator)" target="_top"><code class="code">WebSocketServletFactory.setCreator(WebSocketCreator
    creator)</code></a> and the WebSocketServletFactory will use your
    creator for all incoming Upgrade requests on this servlet.</p><p>Other uses for a WebSocketCreator:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Controlling the selection of WebSocket subprotocol</p></li><li class="listitem"><p>Performing any WebSocket origin you deem important.</p></li><li class="listitem"><p>Obtaining the HTTP headers from incoming request</p></li><li class="listitem"><p>Obtaining the Servlet HttpSession object (if it exists)</p></li><li class="listitem"><p>Specifying a response status code and reason</p></li></ul></div><p>If you don't want to accept the upgrade, simply return null from the
    <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/websocket/servlet/WebSocketCreator.html#createWebSocket(org.eclipse.jetty.websocket.api.UpgradeRequest, org.eclipse.jetty.websocket.api.UpgradeResponse)" target="_top"><code class="code">WebSocketCreator.createWebSocket(UpgradeRequest
    req, UpgradeResponse resp)</code></a> method.</p></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jetty-websocket-api-adapter.html"><i class="icon-chevron-left"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="websocket-jetty.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jetty-websocket-client-api.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Using the WebSocketAdapter&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Jetty WebSocket Client API</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/jetty-project/jetty-documentation">Contribute to this documentation at
                <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2014-05-15T16:24:32-05:00)</i></span></div></p><script xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-1149868-7']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
    </script></body></html>