JSR 356 Introductory One Pager
Danny Coward
April 20th 2012

Purpose of this Project

JSR 356 will define a standard API for creating WebSocket applications as a mix of Java APIs together with Java annotations.

High-level Requirements

• Support creation of Java components to handle bi-directional WebSocket conversations
• Define simple and easy-to-use programming model, consistent with other Java APIs in the Java EE platform (e.g. JAX-RS)
  
• Integrate with Java EE platform
• Support initiating and intercepting WebSocket lifecycle events
• Support creation and consumption of WebSocket text and binary messages
• Define and handle WebSocket subprotocols
• Define and manage content models/custom message formats a web socket applications
• Handle configuration of WebSocket sessions, like timeouts, retries, cookies, connection pooling
• Specify of how WebSocket applications will work within the Java EE security model
• Define an API that can be implemented atop any Servlet 3.1 container
• [Explore] Standalone Java client API derived from/sharing much in common with the EE API
  

Output of JSR-356

• Specification document (api document + text document)
• Reference Implementation (see tyrus.java.net project)
• A Test Suite for testing conformance of implementations to the specification
• Sample code (as time allows)

Deployment scenarios

Primary: Server-(Java EE/Java Web Container)-based web socket applications that communicate with browser (Javascript/HTML5) clients
Secondary: Java SE-based web socket applications that communicate with web socket enabled server (such as above)

Example Scenario: 356-Chat Application

The 356-chat application is a web based chat application embedded within a larger web application. The application allows authorized users to sign in, monitor who else is currently actively chatting, send messages to all the current users, or privately to some subset of the users, and to logout when they are done. Residing on the server-side, a Java EE application, packaged in an EAR (or WAR) file, containing several Java classes that use both the Web Socket API classes and its Java annotations. Perhaps as part of this EE application, or separately in its own application, is a collection of web pages containing Javascript code that form the client side of the application. Each user signs into the chat web application using a standard web authentication method, which if successful, allows the server to initiate a web socket connection between the browser and the client. The chat application follows a specific choreography of messages during the course of a session: one example of part of this choregraphy: after signing in, the first message sent is a web socket message from the server to the client which contains the list of active users of the chat application. The server side of the application understands this choreography as a subprotocol of websockets called 'chat356'. Each message sent between the endpoints in the application throughout conforms to a message format which is modeled in the server side of the application as a collection of Java classes devoted to encoding and decoding chat messages. The end point representing the chat server to the client may be a POJO decorated with a mix of Java annotations defined by the Web Socket API and using the Web Socket API directly. The annotations allow the developer to mark the addressing of the end point in the ws:// URI-space of the server, to define the supported protocol 'chat356' and any others supported and to specify the application classes used to encode and decode incoming and outgoing text/binary messages. The annotations may allow such POJOs to intercept other lifecycle events of the end point. The POJO may alternatively extends the Web Socket API directly in order to become a Web Socket endpoint. The Web Socket Java APIs allow the application a view onto all its active clients (or peers) in order to be able, for example to maintain the list the currently active users, send messages according to the chat formats, and configure acceptable timeouts for inactive users. The 356-chat endpoint(s) are accessible to other Java EE components (like an Newsflash EJB that broadcasts important updates to active chat clients) through standards mechanisms like CDI.

The chat application may also have a Java-SE based client (for example, a desktop application, or applet in a web page) that uses the standalone Java client WebSocket API to initiate a web socket connection with the 356-chat endpoint(s) on the server and engage in bi-directional communication according to the 'chat356' subprotocol.