# The Java EE 7 Tutorial

# 18.1 Introduction to WebSocket

In a WebSocket application, the server publishes a WebSocket endpoint, and the client uses the endpoint's URI to connect to the server. The WebSocket protocol is symmetrical after the connection has been established; the client and the server can send messages to each other at any time while the connection is open, and they can close the connection at any time. Clients usually connect only to one server, and servers accept connections from multiple clients.

The WebSocket protocol has two parts: handshake and data transfer. The client initiates the handshake by sending a request to a WebSocket endpoint using its URI. The handshake is compatible with existing HTTP-based infrastructure: web servers interpret it as an HTTP connection upgrade request. An example handshake from a client looks like this:

    GET /path/to/websocket/endpoint HTTP/1.1
    Host: localhost
    Upgrade: websocket
    Connection: Upgrade
    Sec-WebSocket-Key: xqBt3ImNzJbYqRINxEFlkg==
    Origin: http://localhost
    Sec-WebSocket-Version: 13

An example handshake from the server in response to the client looks like this:

    HTTP/1.1 101 Switching Protocols
    Upgrade: websocket
    Connection: Upgrade
    Sec-WebSocket-Accept: K7DJLdLooIwIG/MOpvWFB3y3FE8=

The server applies a known operation to the value of the `Sec-WebSocket-Key` header to generate the value of the `Sec-WebSocket-Accept` header. The client applies the same operation to the value of the `Sec-WebSocket-Key` header, and the connection is established successfully if the result matches the value received from the server. The client and the server can send messages to each other after a successful handshake.

WebSocket supports text messages (encoded as UTF-8) and binary messages. The control frames in WebSocket are close, ping, and pong (a response to a ping frame). Ping and pong frames may also contain application data.

WebSocket endpoints are represented by URIs that have the following form:

    ws://host:port/path?query
    wss://host:port/path?query

The `ws` scheme represents an unencrypted WebSocket connection, and the `wss` scheme represents an encrypted connection. The `port` component is optional; the default port number is 80 for unencrypted connections and 443 for encrypted connections. The `path` component indicates the location of an endpoint within a server. The `query` component is optional.

Modern web browsers implement the WebSocket protocol and provide a JavaScript API to connect to endpoints, send messages, and assign callback methods for WebSocket events (such as opened connections, received messages, and closed connections).