The WebSocket API expresses a view of the HTML5 standard for WebSocket, which defines the model inside a web browser and the protocol for communication. In terms of the Java API, a WebSocket endpoint is a Java object that represents a terminated socket connection between two peers. If two different Java applications have a Web Socket connection, then each one will have an instance of a Java WebSocket.
There are two ways to create a Java WebSocket. The easiest way is to develop endpoints using the Java annotations. The less travelled road is to develop endpoints against the WebSocket API programmatically. The developer writes classes and implements the classes required by the WebSocket API. The second way means the developer writes behavior for a WebSocket to produce and consume messages, publish itself as a configured endpoint, and write code to register itself for client connections and/or connect to remote endpoints.
The HTML5 standard for WebSocket defines three native formats for communication: text, binary, and pong.
The native format Text is the
java.lang.String in Java and for JavaScript programming language corresponds to the type String. So we have a one-to-one association.
Binary format is
java.nio.ByteBuffer in Java and the type ArrayBuffer in JavaScript. (Some web browsers may also permit the DOM type Blob in JavaScript; since the standard is not completely ratified, you would be very wise to check your integration!)
The Pong format is also java.nio.ByteBuffer in Java and the type ArrayBuffer in JavaScript. The Ping and Pong format is a special format for checking the connectivity between two WebSockets. In the networking parlance, these types of messages are often called heartbeats. In the current WebSocket standard, please note there is no defined API to send either a Ping or Pong message using JavaScript.
Let's continue with the annotated WebSocket endpoints.
Developers have access to the lifecycle of the WebSocket through annotations, which unsurprisingly are very similar to the JavaScript implementation. The annotations are @javax.websocket.OnMessage, which you have already seen @javax.websocket.OnOpen, @javax.websocket.OnClose, and @javax.websocket.OnError. These annotations, apart from @OnMessage, do not accept any attributes. All of the annotations are only applied to instance methods in a Java class.
Here is a table of these annotations:
This method-level annotation can be used to make a Java method receive incoming WebSocket messages. Each WebSocket endpoint may only have one message handling method for each of the native WebSocket message formats: text, binary, and pong.
The Java WebSocket API defines a session object that represents a conversation between two peers. The javax.websocket.Session is an interface, which defines a number of methods that a developer may invoke to get extra information about the connection, session data, the lifecycle, and also perform the close action on the connection. Moreover, the Session object is the way to associate the conversation with the peer into a semantic context in terms of a business application.
Each WebSocket session has a unique session ID, which is associated with one and only one session instance. An implementation may choose to implement a WebSocket connection pool and therefore an instance may be appropriately reused. In such cases, the specification stipulates that a reused session instance must have a new unique session ID.
The session instance in a distributed Java EE container can also be passivated on managed server node instance and therefore migrated to another node. Implementations of the Java WebSocket API are permitted to migrate the WebSocket session instances from one node to another for the purposes of load balancing and failover. The only rule is that the provider must preserve the WebSocket session of any connected peers seamlessly and transparently. This is particularly interesting from the point of view of a cloud-computing platform. This, probably, will be a common question for application architects. How do WebSocket connections, nodes, and servers scale? The simplest answer, perhaps, is to choose a provider that reliably has the non-functional requirements that your business needs.
Methods annotated with lifecycle events@OnOpen, @OnClose, @OnMessage, and @OnError annotation are permitted to accept a javax.websocket.Session object as an argument. The implementation will inject the session instance into the method call.
Methods annotated with@OnMessage annotation additionally can also declare a @javax.websocket.PathParam argument in order to accept WebSocket connection arguments.
Here is a table for the methods of javax.websocket.Session:
Although there are lots of methods in javax.websocket.Session, the most important methods are: getId(); getRemoteBasic() and getRemoteAsync(); isOpen(), close(), and getRequestParameterMap().
Now let us see a more capable server-side WebSocket application.