WebSocket provide a full-duplex and bi-directional communication
protocol over a single TCP connection. JSR 356 is defining
a standard API for creating WebSocket applications in the Java EE 7
Platform. This Tip Of The Day (TOTD)
will provide an introduction to WebSocket and how the JSR is
evolving to support the programming model.
First, a little primer on WebSocket!
WebSocket is a combination of IETF RFC 6455 Protocol
and W3C JavaScript API
(still a Candidate Recommendation). The protocol defines an opening
handshake and data transfer. The API enables Web pages to use the
WebSocket protocol for two-way communication with the remote host.
Unlike HTTP, there is no need to create a new TCP connection and
send a chock-full of headers for every message exchange between
client and server. The WebSocket protocol defines basic message
framing, layered over TCP. Once the initial handshake happens using
HTTP
Upgrade, the client and server can send messages to each
other, independent from the other. There are no pre-defined message
exchange patterns of request/response or one-way between client and
and server. These need to be explicitly defined over the basic
protocol.
The communication between client and server is pretty symmetric but
there are two differences:
A client initiates a connection to a server that is listening
for a WebSocket request.
A client connects to one server using a URI. A server may
listen to requests from multiple
clients on the same URI.
Other than these two difference, the client and server behave
symmetrically after the opening handshake. In that sense, they are
considered as "peers".
After a successful handshake,
clients and servers transfer data back
and forth in conceptual units referred as "messages". On the wire, a
message is composed of one or more frames. Application frames carry
payload intended for the application and can be text or binary data.
Control frames carry data intended for protocol-level signaling.
Now lets talk about the JSR!
The Java API for
WebSocket is worked upon as JSR 356 in the
Java Community Process. This will define a standard API for building
WebSocket applications. This JSR will provide support for:
Creating WebSocket Java components to handle bi-directional
WebSocket conversations
Initiating and intercepting WebSocket events
Creation and consumption of WebSocket text and binary messages
The ability to define WebSocket protocols and content models
for an application
Configuration and management of WebSocket sessions, like
timeouts, retries, cookies, connection pooling
Specification of how WebSocket application will work within
the Java EE security model
Tyrus is the Reference
Implementation for JSR 356 and is already integrated in GlassFish
4.0 Promoted Builds.
And finally some code!
The API allows to create WebSocket endpoints using annotations and
interface. This TOTD will show a simple sample using annotations. A
subsequent blog will show more advanced samples.
A POJO can be converted to a WebSocket endpoint by specifying @WebSocketEndpoint
and @WebSocketMessage.
@WebSocketEndpoint(path="/hello")public class HelloBean {
@WebSocketMessage public String sayHello(String name) {
return "Hello " + name + "!";
}}
@WebSocketEndpoint marks this class as a
WebSocket endpoint listening at URI defined by the path
attribute.
The @WebSocketMessage identifies the method that
will receive the incoming WebSocket message. This first method
parameter is injected with payload of the incoming message. In
this case it is assumed that the payload is text-based. It can
also be of the type byte[] in case the payload is
binary. A custom object may be specified if decoders
attribute is specified in the @WebSocketEndpoint.
This attribute will provide a list of classes that define how a
custom object can be decoded.
This method can also take an optional Session
parameter. This is injected by the runtime and capture a
conversation between two endpoints.
The return type of the method can be String, byte[]
or a custom object. The encoders attribute on @WebSocketEndpoint
need to define how a custom object can be encoded.
The client side is an index.jsp with embedded
JavaScript. The JSP body looks like:
<div style="text-align: center;">
<form action="">
<input onclick="say_hello()" value="Say Hello" type="button">
<input id="nameField" name="name" value="WebSocket" type="text"><br>
</form>
</div>
<div id="output"></div>
The code is relatively straight forward. It has an HTML form with a
button that invokes say_hello() method and a text
field named nameField. A div placeholder
is available for displaying the output.
Now, lets take a look at some JavaScript code:
<script language="javascript" type="text/javascript">
var wsUri = "ws://localhost:8080/HelloWebSocket/hello";
var websocket = new WebSocket(wsUri);
websocket.onopen = function(evt) { onOpen(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };
function init() {
output = document.getElementById("output");
}
function say_hello() {
websocket.send(nameField.value);
writeToScreen("SENT: " + nameField.value);
}
This application is deployed as "HelloWebSocket.war" (download
here) on GlassFish
4.0 promoted build 57. So the WebSocket endpoint is
listening at "ws://localhost:8080/HelloWebSocket/hello". A new
WebSocket connection is initiated by specifying the URI to
connect to.
The JavaScript API defines callback methods that are invoked
when the connection is opened (onOpen), closed (onClose),
error received (onError), or a message from the
endpoint is received (onMessage).
The client API has several send methods that
transmit data over the connection. This particular script sends
text data in the say_hello method using nameField's
value from the HTML shown earlier.
Each click on the button sends the textbox content to the
endpoint over a WebSocket connection and receives a response
based upon implementation in the sayHello method
shown above.
How to test this out ?
Download the entire source project here
or just the WAR
file.
Download GlassFish4.0
build 57 or later
and unzip.
Start GlassFish as "asadmin start-domain".
Deploy the WAR file as "asadmin deploy HelloWebSocket.war".
Access the application at http://localhost:8080/HelloWebSocket/index.jsp.
After clicking on "Say Hello" button, the output would look like:
Here are some references for you:
WebSocket - Protocol
and JavaScript API
JSR 356: Java API for WebSocket - Specification (Early
Draft) and Implementation
(already integrated in GlassFish
4 promoted builds)
Subsequent blogs will discuss the following topics (not necessary in
that order) ...
Binary data as payload
Custom payloads using encoder/decoder
Error handling
Interface-driven WebSocket endpoint
Java client API
Client and Server configuration
Security
Subprotocols
Extensions
Other topics from the API
Capturing WebSocket on-the-wire messages
