Java EE 7 introduces a number of new APIs and changes to existing APIs that cater to web developers using HTML5. There are three areas of interest: a new API for working with JSON, a significant update to JSF for working with new attributes, and a new API for working with the WebSocket protocol, one of a variety of technologies that make up HTML5.
The WebSocket protocol changes the way a web server reacts to client requests: instead of closing the connection, it sends back a 101 status and leaves the connection open, expecting both that messages will be written on the stream and that it will be able to write to the stream. Unlike HTTP, the protocol supports full-duplex communication so the client, typically a browser, and the server can send messages to each other at the same time.
The protocol is defined via IETF RFC 6455.
To establish a WebSocket connection, the client sends a WebSocket handshake request, and the server sends a response, as shown in the following example:
GET /mychat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Protocol: chat
Sec-WebSocket-Version: 13
Origin: http://example.com
Server response:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat
Once the handshake has taken place the client and server are connected and are peers; both can send and received messages, and terminate the connection.
The client-side is handled using JavaScript with the API for this defined by W3C.
Java WebSocket applications consist of WebSocket endpoints, which are Java objects representing one end of a WebSocket connection between two peers.
The Java WebSocket API models each peer of a session with an endpoint as an instance of the RemoteEndpoint interface. This interface and its two subtypes (RemoteEndpoint.Whole and RemoteEndpoint.Partial) contain a variety of methods for sending WebSocket messages from the endpoint to its peer.
There are two main means by which an endpoint can be created. The first is to implement certain of the API classes from the Java WebSocket API with the required behaviour to handle the endpoint lifecycle, consume and send messages, publish itself, or connect to a peer:
session.addMessageHandler(new MessageHandler.Whole<String>() {
public void onMessage(String text) {
try {
remote.sendText("Got your message (" + text + "). Thanks !");
} catch (IOException ioe) {
ioe.printStackTrace();
} }
The second is to decorate a Plain Old Java Object (POJO) with certain of the annotations from the Java WebSocket API. The implementation then takes these annotated classes and creates the appropriate objects at runtime to deploy the POJO as a WebSocket endpoint.
@ServerEndpoint("/hello")
public class MyHelloServer {
@OnMessage
public String handleMessage(String message) {
return "Got your message (" + message + "). Thanks !";
} }
The API limits the registration of MessageHandlers per Session to be one MessageHandler per native WebSocket message type (text, binary, pong) though this may change in the future.
The endpoint participates in the opening handshake that establishes the WebSocket connection. The endpoint will typically send and receive a variety of WebSocket messages. The endpoint's lifecycle is complete when the WebSocket connection is closed.
If an open connection to a WebSocket endpoint is to be closed for any reason, whether as a result of receiving a WebSocket close event from the peer, or because the underlying implementation has reason to close the connection, the WebSocket implementation must invoke the onClose() method of the WebSocket endpoint.
It was of course possible to implement WebSocket applications in Java prior to the introduction of Java EE 7, but each of the many different APIs that could be used were slightly different, so if you had written a WebSocket application in Apache Tomcat 7 it would need modifying to work with Jetty, or JBoss or Resin. Having a standard method for doing this in Java EE is a welcome addition.
