Java Platform, Enterprise Edition (Java EE) 8
The Java EE Tutorial

Previous Next Contents

Protocol Upgrade Processing

In HTTP/1.1, clients can request to switch to a different protocol on the current connection by using the Upgrade header field. If the server accepts the request to switch to the protocol indicated by the client, it generates an HTTP response with status 101 (switching protocols). After this exchange, the client and the server communicate using the new protocol.

For example, a client can make an HTTP request to switch to the XYZP protocol as follows:

GET /xyzpresource HTTP/1.1
Host: localhost:8080
Accept: text/html
Upgrade: XYZP
Connection: Upgrade
OtherHeaderA: Value

The client can specify parameters for the new protocol using HTTP headers. The server can accept the request and generate a response as follows:

HTTP/1.1 101 Switching Protocols
Upgrade: XYZP
Connection: Upgrade
OtherHeaderB: Value

(XYZP data)

Java EE supports the HTTP protocol upgrade functionality in servlets, as described in Table 18-7.

Table 18-7 Protocol Upgrade Support

Class or Interface



HttpUpgradeHandler upgrade(Class handler)

The upgrade method starts the protocol upgrade processing. This method instantiates a class that implements the HttpUpgradeHandler interface and delegates the connection to it.

You call the upgrade method inside a service method when accepting a request from a client to switch protocols.


void init(WebConnection wc)

The init method is called when the servlet accepts the request to switch protocols. You implement this method and obtain input and output streams from the WebConnection object to implement the new protocol.


void destroy()

The destroy method is called when the client disconnects. You implement this method and free any resources associated with processing the new protocol.


ServletInputStream getInputStream()

The getInputStream method provides access to the input stream of the connection. You can use Nonblocking I/O with the returned stream to implement the new protocol.


ServletOutputStream getOutputStream()

The getOutputStream method provides access to the output stream of the connection. You can use Nonblocking I/O with the returned stream to implement the new protocol.

The following code demonstrates how to accept an HTTP protocol upgrade request from a client:

public class XYZPUpgradeServlet extends HttpServlet {
   public void doGet(HttpServletRequest request,
                     HttpServletResponse response) {
      if ("XYZP".equals(request.getHeader("Upgrade"))) {
         /* Accept upgrade request */
         response.setHeader("Upgrade", "XYZP");
         response.setHeader("Connection", "Upgrade");
         response.setHeader("OtherHeaderB", "Value");
         /* Delegate the connection to the upgrade handler */
         XYZPUpgradeHandler = request.upgrade(XYZPUpgradeHandler.class);
         /* (the service method returns immedately) */
      } else {
         /* ... write error response ... */

The XYZPUpgradeHandler class handles the connection:

public class XYZPUpgradeHandler implements HttpUpgradeHandler {
   public void init(WebConnection wc) {
      ServletInputStream input = wc.getInputStream();
      ServletOutputStream output = wc.getOutputStream();
      /* ... implement XYZP using these streams (protocol-specific) ... */
   public void destroy() { ... }

The class that implements HttpUpgradeHandler uses the streams from the current connection to communicate with the client using the new protocol. See the Servlet 4.0 specification at for details on HTTP protocol upgrade support.

Previous Next Contents
Oracle Logo  Copyright © 2017, Oracle and/or its affiliates. All rights reserved.