Jetty Logo
Version: 9.2.3.v20140905
Contact the core Jetty developers at www.webtide.com

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

Jetty WebSocket Server API

The Jetty WebSocketServlet
Using the WebSocketCreator

Jetty provides the ability to wire up WebSocket endpoints to Servlet Path Specs via the use of a WebSocketServlet bridge servlet.

Internally, Jetty manages the HTTP Upgrade to WebSocket and migration from a HTTP Connection to a WebSocket Connection.

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)

The Jetty WebSocketServlet

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.

Example 30.16. MyEchoServlet.java


This example will create a Servlet mapped via the @WebServlet annotation to the Servlet path spec of "/echo" (or you can do this manually in the WEB-INF/web.xml of your web application) which will create MyEchoSocket instances when encountering HTTP Upgrade requests.

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.

Note

It is important that you take in account any firewall or router timeouts when configuring websockets. Be sure the websocket configuration is lower than your firewall or router.

Using the WebSocketCreator

All WebSocket's are created via whatever WebSocketCreator you have registered with the WebSocketServletFactory.

By default, the WebSocketServletFactory is a simple WebSocketCreator capable of creating a single WebSocket object. Use WebSocketCreator.register(Class<?> websocket) to tell the WebSocketServletFactory which class it should instantiate (make sure it has a default constructor).

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.

Example 30.17. MyAdvancedEchoCreator.java


Here we show a WebSocketCreator that will utilize the WebSocket subprotocol information from request to determine what WebSocket type should be created.

Example 30.18. MyAdvancedEchoServlet.java


When you want a custom WebSocketCreator, use WebSocketServletFactory.setCreator(WebSocketCreator creator) and the WebSocketServletFactory will use your creator for all incoming Upgrade requests on this servlet.

Other uses for a WebSocketCreator:

  • Controlling the selection of WebSocket subprotocol

  • Performing any WebSocket origin you deem important.

  • Obtaining the HTTP headers from incoming request

  • Obtaining the Servlet HttpSession object (if it exists)

  • Specifying a response status code and reason

If you don't want to accept the upgrade, simply return null from the WebSocketCreator.createWebSocket(UpgradeRequest req, UpgradeResponse resp) method.

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-10-20T01:00:34-07:00)