API Overview
This section discusses the basic concepts of the Java WebSocket API and will help you gain a decent understanding of its building blocks. Luckily, the API itself is pretty compact which made it easy to ensure that this chapter touches upon all it's components. (most of) The items presented in this chapter have been covered via dedicated chapters throughout this book.
Server and client mode
To start with, let's understand what does server and client mean in the context of WebSocket in general
WebSocket Server endpoint
A server side component which
implements some business logic
publishes itself i.e. makes itself discoverable to potential clients (over a certain host and port combination)
gets triggered when clients connect to it
WebSocket Client endpoint
implements some business logic (just like it's server side counterpart)
it connects to existing WebSocket (server) endpoints
The Java WebSocket API provides both server and client side components
Client API components are as follows - ClientEndpoint
, ClientEndpointConfig
, ClientEndpointConfig.Builder
, ClientEndpointConfig.Configurator
, WebSocketContainer
(helps connect to existing WebSocket server endpoints)
Client side API has been covered in a separate chapter
Supported message formats
The WebSocket specification supports two on-wire data formats - text and binary. The Java WebSocket API supports these (obviously) and adds capability to work with Java objects as well as health check messages (ping-pong) defined by the specification
Deep dive of sending and recieving different types of messages will covered in subsequent chapters
Container Abstraction
The following APIs provide a high level abstraction of the WebSocket container (runtime)
RemoteEndpoint
WebSocket is a protocol using which two peers (client and server) communicate with each other. The javax.websocket.RemoteEndpoint
interface is an abstraction which represents the peer at the other end
It is available is two avatars
Endpoint
A javax.websocket.Endpoint
is a class which represents the WebSocket endpoint itself – either a server or a client. The Java WebSocket API provides both annotation and programmatic APIs (both will been explored in detail later) to develop endpoints. This class is designed for extension (since it is abstract) and is fit for scenarios where a programmatic style is preferred over annotation driven (declarative) implementation
It is important to understand that
Endpoint
andRemoteEndpoint
represent different concepts altogether
In the above diagram
WSE is both a
RemoteEndpoint
(from the perspective of it's connected peers) as well as an Endpoint (assuming its implemented by extending thejavax.websocket.Endpoint
class)Each of the peers (Peer 1,2,3,4… n) are
RemoteEndpoint
(s) from the perspective of the WSE (the websocket server with which they are interacting)
Session
The concept of a WebSocket session (represented by javax.websocket.Session
) is not very different than that of a HTTP Session: it encapsulates the interaction between two endpoints (peers). The conversation between two endpoints consists of events like – connection initialization, message exchange, connection termination, error transmission etc.
Each connection b/w a peer and the WebSocket server endpoint is represented by a unique
Session
object (refer previous diagram)Allows communication b/w a server-client pair by exposing a
javax.websocket.RemoteEndpoint
object (discussed later)
Declarative & Programmatic models
The annotations in the API offer a declarative model for building WebSocket based applications whereas the programmatic style lean towards a more classical way of development model i.e. using inheritance.
Encoders & Decoders
Think of them as hooks provided by the WebSocket API, which allow you to plugin your custom implementation that takes care of converting your Java objects (part of your logic, domain model etc.) to/from the on-wire representations supported by the WebSocket protocol i.e. text and binary
Configuration
In the context of the Java WebSocket API, configuration is nothing but the attributes/properties (deployed path, encoders, decoders, extensions, subprotocols) related to an endpoint (server or client) and is represented by the javax.websocket.EndpointConfig
interface. It is further extended by javax.websocket.server.ServerEndpointConfig
and javax.websocket.ClientEndpointConfig
which are the server and client counterparts respectively
Asynchronous constructs
Sending messages to peers need not always be a blocking call. One can choose to embrace the asynchronous style (as mentioned in the RemoteEndpoint section)
The SendHandler
, SendResult
interfaces (in the javax.websocket
package) enable asynchronous messaging in WebSocket endpoints
WebSocket Extension
Exceptions
All the exceptions defined by this API are
checked
part of the
javax.websocket
package
Miscellaneous
Path parameters
In case of an annotated server endpoint (details in the next chapter), javax.webocket.PathParam
helps inject the path parameters (from the URI specified in the @ServerEndpoint
annotation) into annotated websocket lifecycle methods
WebSocket connection handshake
Instances of HandshakeRequest
and HandshakeResponse
(from the javax.websocket
pacakge), allow access to the state of communication during establishment (handshake) of the WebSocket connection
Communicating connection termination details
javax.websocket.CloseReason
captures the details (reason) for the termination of a WebSocket connection. javax.websocket.CloseReason.CloseCode
is a marker interface for different reason codes and javax.websocket.CloseReason.CloseCodes
(please note the 's' at the end) contains an enumeration of ready-to-use codes (outlined in the following section of the WebSocket RFC specification) - give link
Coming up...
The next chapter will guide you through the Programming Models can be adopted while using the Java WebSocket API
Last updated